7

What's the best way to author man pages? Should I write using the standard man macros, or is there some clever package available now that takes some kind of XML-ified source and can output man pages, HTML, ASCII, and what not?

Thanks

Suraj Jain
  • 4,463
  • 28
  • 39
vy32
  • 28,461
  • 37
  • 122
  • 246

5 Answers5

2

I have previously used the GNU version of nroff called groff to write man pages.

Nice intro article on it here:

http://www.linuxjournal.com/article/1158

DEzra
  • 2,978
  • 5
  • 31
  • 50
1

If you are looking at writing once and generating different output formats such as manpages, HTML, plain txt, or even PDF, then docbook should work best.

Sid Heroor
  • 663
  • 4
  • 11
  • docbook doesn't produce man pages. It can ingest them, but not produce them. – vy32 May 01 '10 at 13:56
  • I think shadow-utils uses it successfully, something like "xsltproc -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/profile-docbook.xsl $FILE" – Paweł Hajdan Feb 22 '12 at 18:51
1

A tool that is commonly used in the Tcl community is doctools which can produce a restricted (but useful) subset of the manpage format, suitable for rendering with groff or nroff. It can also generate both plain text and HTML directly.

Donal Fellows
  • 133,037
  • 18
  • 149
  • 215
0

Doxygen is what you are looking for. Keep in mind that it is designed to document source code but you could easily adapt it.

It can generate html, pdf, and latex documentation too.

Nathan Osman
  • 71,149
  • 71
  • 256
  • 361
  • Doxygen is a powerful system, but it's not clear to me how I get it to emit nice man pages for command line options and such. – vy32 May 01 '10 at 14:03
  • Ya. Probably you need something else. – Nathan Osman May 01 '10 at 20:34
  • You can get doxygen to output man formatted pages by setting GENERATE_MAN and then optionally MAN-OUTPUT (to set location of output) in the doxygen configuration file: http://www.doxygen.nl/config.html#cfg_man_output As mentioned in docs, if you leave the man-output value blank it will default to putting the man pages under a subdir called 'man' – DEzra May 21 '10 at 15:58
0

For my atinout program I have been using ronn which lets you write man pages in a very, very readable markdown like syntax. I am extremely happy with it.

atinout(1) -- Send AT commands to modem, capturing the response
===============================================================

## SYNOPSIS

`atinout` <input_file>|`-` <modem_device> <output_file>|`-`<br>
`atinout` `--version`<br>
`atinout` `--usage`<br>
`atinout` `--help`<br>

## DESCRIPTION

**Atinout** reads a list of AT commands. It sends those commands one by one
to the modem, waiting for the final result code for the
currently running command before continuing with the next command in
the list. The output from the commands is saved.
...

see the whole page here.

hlovdal
  • 26,565
  • 10
  • 94
  • 165
  • Although, how do you distribute a configure script that automatically runs `atinout`? – vy32 Oct 14 '17 at 21:55
  • You mean "... automatically run ronn"? Well I don't . Both hat atinout does not have a configure script and also I distribute a premade atinout.1 so that ronn is not a hard build dependency (only if you want to modify the man page do you need it). – hlovdal Oct 14 '17 at 23:12
  • Okay. In my autoconf-based projects, I distribute the source for the man pages and nroff gets run automatically.. – vy32 Oct 15 '17 at 01:19