Path: csiph.com!fu-berlin.de!uni-berlin.de!not-for-mail
From: Ben Finney <ben+python@benfinney.id.au>
Newsgroups: comp.lang.python
Subject: Writing manual pages using Python code (was: manpage writing)
Date: Sat, 30 Apr 2016 12:25:21 +1000
Lines: 40
Message-ID: <mailman.247.1461983708.32212.python-list@python.org>
References: <57223b76$0$22140$c3e8da3$5496439d@news.astraweb.com> <nfthhs$klf$1@ger.gmane.org> <1461865210.3218352.592571425.2069E4EB@webmail.messagingengine.com> <nftjuh$t2b$1@ger.gmane.org> <mailman.207.1461867295.32212.python-list@python.org> <87a8kdshyh.fsf@elektro.pacujo.net> <nftot6$4ii$2@ger.gmane.org> <1461873085.3251720.592695601.44633E5E@webmail.messagingengine.com> <nftu4v$3d1$1@ger.gmane.org> <mailman.214.1461877741.32212.python-list@python.org> <5722bb82$0$1600$c3e8da3$5496439d@news.astraweb.com> <alpine.LSU.2.11.1604290441080.29512@znpeba.jbaqresebt.arg> <85k2jfj036.fsf@benfinney.id.au>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de T6aNKc39ZhWlzVzx1L65Kg2RiOHVBBN8gkeX+9NxcASg==
Cancel-Lock: sha1:tVitMS6twVKyDNISak9mTECLLGQ=
Return-Path: <python-python-list@m.gmane.org>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.002
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'subject:Python': 0.05; 'distutils': 0.05; 'gpl': 0.07; 'important,': 0.07; 'modifying': 0.07; 'subject:code': 0.07; 'instance.': 0.09; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'subject:Writing': 0.09; 'subject:using': 0.09; 'python': 0.10; 'language,': 0.11; 'feedback.': 0.15; 'inputs': 0.16; 'package).': 0.16; 'received:80.91.229.3': 0.16; 'received:io': 0.16; 'received:plane.gmane.org': 0.16; 'received:psf.io': 0.16; 'subject:writing': 0.16; 'specifies': 0.18; 'library': 0.20; 'code,': 0.23; 'decide': 0.23; "i've": 0.25; 'header:User-Agent:1': 0.26; "doesn't": 0.26; 'header:X -Complaints-To:1': 0.26; 'pages,': 0.27; 'gnu': 0.27; 'specify': 0.27; 'page.': 0.28; 'markup': 0.29; 'code': 0.30; "i'd": 0.31; 'option': 0.31; 'steven': 0.33; 'ones': 0.35; 'could': 0.35; 'done': 0.35; 'generic': 0.35; 'instance': 0.35; 'library.': 0.35; 'but': 0.36; 'url:org': 0.36; 'cases': 0.36; 'to:addr:python- list': 0.36; 'subject:: ': 0.37; 'received:org': 0.37; 'manual': 0.38; 'several': 0.38; 'data': 0.39; 'format': 0.39; 'enough': 0.39; 'to:addr:python.org': 0.40; 'where': 0.40; 'software': 0.40; 'documents': 0.61; 'making': 0.62; 'bases': 0.63; 'more': 0.63; 'skip:\xe2 10': 0.70; 'money': 0.71; 'banks': 0.72; 'useful.': 0.72; '8bit%:46': 0.76; 'inform': 0.79; '_o__)': 0.84; 'clearer': 0.84; 'received:125': 0.84; 'url:fi': 0.84; '\xe2\x80\x9cthe': 0.93
X-Injected-Via-Gmane: http://gmane.org/
X-Gmane-NNTP-Posting-Host: jigong.madmonks.org
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.4 (gnu/linux)
X-Public-Key-ID: 0xAC128405
X-Public-Key-Fingerprint: 517C F14B B2F3 98B0 CB35  4855 B8B2 4C06 AC12 8405
X-Public-Key-URL: http://www.benfinney.id.au/contact/bfinney-pubkey.asc
X-Post-From: Ben Finney <bignose+hates-spam@benfinney.id.au>
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.22
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <https://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list/>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <https://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
X-Mailman-Original-Message-ID: <85k2jfj036.fsf@benfinney.id.au>
X-Mailman-Original-References: <57223b76$0$22140$c3e8da3$5496439d@news.astraweb.com> <nfthhs$klf$1@ger.gmane.org> <1461865210.3218352.592571425.2069E4EB@webmail.messagingengine.com> <nftjuh$t2b$1@ger.gmane.org> <mailman.207.1461867295.32212.python-list@python.org> <87a8kdshyh.fsf@elektro.pacujo.net> <nftot6$4ii$2@ger.gmane.org> <1461873085.3251720.592695601.44633E5E@webmail.messagingengine.com> <nftu4v$3d1$1@ger.gmane.org> <mailman.214.1461877741.32212.python-list@python.org> <5722bb82$0$1600$c3e8da3$5496439d@news.astraweb.com> <alpine.LSU.2.11.1604290441080.29512@znpeba.jbaqresebt.arg>
Xref: csiph.com comp.lang.python:107891

"Martin A. Brown" <martin@linux-ip.net> writes:

> Hello [Steven D'Aprano],
>
> >What is a good place where I can find out more about writing manpage?

Writing manual pages directly in standard GNU troff markup is simple
enough <URL:http://liw.fi/manpages/>. It's not a pretty markup language,
but it's workable.

For writing manual page documents programmatically via Python code, I am
working on a ‘manpage’ library.

It is not yet at PyPI, but Steven may find the existing library
<URL:https://notabug.org/bignose/python-manpage> useful. It's free
software under the GNU GPL v3 or later.

Steven, if you want to use that library for making manual pages, I'd
love to get feedback.

Currently it works on an ArgumentParser instance (to get the program's
name and option help), and a Distutils distribution (to get the boader
metadata about the package).

What ‘manpage’ doesn't yet have is a more generic way to specify the
metadata of a manual page; the above inputs are the only ones that I've
tested. Everything is done by directly modifying a Document instance. I
have yet to decide a data format for the data which specifies a manual
page.

If several more code bases could use this library to generate manual
pages, that would make it clearer what use cases are important, and
thereby inform a data format for the specification. Please experiment!

-- 
 \      “The process by which banks create money is so simple that the |
  `\     mind is repelled.” —John Kenneth Galbraith, _Money: Whence It |
_o__)                                       Came, Where It Went_, 1975 |
Ben Finney