Python library for creating Unix manual page documents (“man pages”).

Ben Finney a61776979f Add a Distutils command to build documents for the distribution. 8 years ago
manpage a61776979f Add a Distutils command to build documents for the distribution. 8 years ago
tests 4cd6a9de9e Add test cases for ‘build_manpages.DocumentBuilder’. 8 years ago
.gitignore e5d32ebf7d Add Git ignore patterns. 8 years ago
LICENSE.GPL-3 b6411952f6 Add verbatim text of GNU General Public License version 3. 8 years ago
MANIFEST.in 8910fd8797 Add a README document for the code base. 8 years ago
Makefile e723f01c26 Add Distutils script ‘setup.py’. 8 years ago
README 8910fd8797 Add a README document for the code base. 8 years ago
setup.py e723f01c26 Add Distutils script ‘setup.py’. 8 years ago
tox.ini b8bc8a3a19 Add configuration for Tox automated testing. 8 years ago

README

Manual page library for Python
##############################

The standard Unix manual system is structured into documents, each
called a “manual page” (or “man page”). This library helps you to
generate these documents from Python code.


Features
========

* Python API for generating Unix manual page documents.

* Integration with the `argparse.ArgumentParser` class for each
command, to create a manual page document for the command.

* Integration with the Setuptools build system, to generate manual
page documents when building the distribution.


Requirements
============

* Python 3.3 or later.


Motivation
==========

While the Unix manual page system is a common standard, too many
Python packages install commands, libraries, and file formats without
any Unix manual pages.


Legacy markup language
----------------------

A manual page document is written in `troff`_, which is a text markup
language. In the 21st century, almost nobody uses troff anymore
*except* for writing Unix manual page documents, and there is a lack
of experience in using the language well.

So it's hard to find well-formatted manual pages, and many such pages
do not conform to markup conventions for the system.

The `manpage` library provides ways to generate Unix man pages,
without any need to learn any troff.

.. _troff: http://www.troff.org/


Avoid duplicate documentation
-----------------------------

A good manual page document has a structure and contains significant
information; it is not just a terse listing of command options.
Neither is it a full end-user treatise or tutorial. Instead, it should
be a concise reference work, in a standard format.

Some parts of the manual page should be written specifically for that
document. Others, though, can be automatically gathered from text
written elsewhere.

So it's hard to find well-written or complete manual pages, and many
busy developers postpone writing them at all.

The `manpage` library has various sensible defaults for a document's
meta-data. It can also populate larger parts of the document from
existing text in the Python code.


Copying this work
=================

Copyright © 2016 Ben Finney .

This is free software: you may copy, modify, and/or distribute this work
under the terms of the GNU General Public License as published by the
Free Software Foundation; version 3 of that license or any later version.

No warranty expressed or implied. See the file ‘LICENSE.GPL-3’ for details,
or view it online at .


..
Local variables:
coding: utf-8
mode: text
mode: rst
End:
vim: fileencoding=utf-8 filetype=rst :