dc7 - 1.0
DebConf7
| Speakers | |
|---|---|
|
W. Borgert |
| Schedule | |
|---|---|
| Day | 15 |
| Room | Upper Talk Room |
| Start time | 09:45 |
| Duration | 00:45 |
| Info | |
| ID | 24 |
| Event type | Lecture |
| Track | DebConf |
| Language | English |
| Feedback | |
|---|---|
|
Did you attend this event? Give Feedback |
WTFM, again: Write The Fine Manual page
without having to learn ROFF
According to Debian policy, each program should have a manual page. The required nroff format is a bit out of fashion nowadays, however. The process of producing manual pages, GNU info pages, and other output from trendy DocBook XML sources is presented in this talk, as well as FHS description of manual sections, what should be in a manual page, and style issues.
Manual pages are one of the reminders of UNIX V7 in 1979, that are still present in Debian. Manual pages are easy to access, self-contained, structured in a simple and well-known way and people are customarily asked to read them.
The Debian policy, chapter 12, mandates: "Each program, utility, and function should have an associated manual page included in the same package." It also suggests manual pages for all configuration files and for protocols and other auxiliary things.
The FHS (file hierarchy standard), describes the sections 1..8 of manual pages and where to store manual pages for different languages and character sets.
The layout of manual pages includes typical paragraphes, such as NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES, KNOWN BUGS, FILES, AUTHOR, REPORTING BUGS, COPYRIGHT, SEE ALSO. A manual page is a reference document, i.e. it should describe all command line options of a program. It is not a tutorial nor howto nor readme.
There has been a lot of criticism against manual pages and the GNU project came up with an competing concept, GNU info (TeXinfo). Other projects use HTML based hypertext help. Some of the negative sides of manual pages are: The nroff format is archaic and not many people like to learn it, the classical man viewer has no support for hypertext links, and many manual pages are either outdated, incomprehensible, too laconic, too long-winded or simply missing.
Using a state-of-the-art input format, DocBook XML, one can produce UNIX manual pages, GNU info pages, HTML, and PDF from the same source. The details, including the inevitable devils, are presented in this talk. Examples are given.