3

I would like to parse man pages into a more structure form, but I'm unable to find a proper specification for the data format under use by man pages. Should I be looking for troff or nroff or groff or something else? groff(7) says

The groff system has all features of the classical roff, but adds many extensions.

Are these extensions the various preprocessors like tbl or something else?

So far I've found the following resources:

  • troff.org - This has historical notes and some tutorials, and some dead links.

  • roff(7) (OpenBSD, Linux) - Doesn't really have a specification, only a brief overview and bunch of history.

  • man-pages(7) (Linux) - This provides guidelines about sections in man pages (which is useful), but it doesn't talk about the data format.

  • A Typesetter-independent TROFF and Troff User's Manual - these are fairly old, so I can't really judge what the differences are between the troff in those papers and in practice.

Is there a clear specification somewhere for the exact format under use by man pages?

  • 2
    no standard - just similar/derived implementations. You omitted one manpage, with the macros (here). – Thomas Dickey Nov 11 '18 at 0:18
  • @ThomasDickey, yes I looked at that but I don't know if that is comprehensive (my hunch is that it isn't). – cutculus Nov 11 '18 at 0:22
  • sure it is not: but the point of your question is standards, and there are none. – Thomas Dickey Nov 11 '18 at 0:30
  • To clarify, does your comment mean "none of roff/troff/nroff/groff have standards" or "man pages in practice do not follow any particular *roff system" or both? – cutculus Nov 11 '18 at 0:36
  • All of the *roff variants use the same instructions. Man pages add to those instructions a set of macros to do common things. But individual manpages may use either the underlying instructions or the macros or both with no consistency. ivanivan's answer, for example, is all about macros. But some pages hardly use the macros. – Cupcake Protocol Nov 11 '18 at 0:53
1

There is no single source form.

Some people write manual pages in roff. Almost no-one uses raw roff; but people write manual pages using various sets of roff macros, such as an or mdoc. These macro sets differ extensively from one another. But many people nowadays do not write manual pages in roff at all.

People can also author manual pages in Docbook XML, perl's POD, TEΧ, Teχinfo, ASCIIDOC, plain HTML, or other systems.

Some of these, most notably Docbook XML, are quite structured in the first place and the conversion to roff is lossy. You are better off ignoring roff if they are the source, and using the actual source forms directly, which will likely already have the structured form that you are looking for.

Indeed, there is no roff intermediary when viewing some of these forms. (All of the aforementioned can be converted directly to formats such as HTML without going through an intermediate roff stage. Manual pages authored in Docbook XML, again notably, can even be viewed directly as the XML using several WWW browsers, without an HTML intermediary, if Docbook CSS or similar is employed.)

Many of these source forms are themselves standardized, but there is no single universal source form for manual pages.

Examples

0

Yup. Think like HTML... but pre-HTML. Basically a bunch of typesetting macros for groff ...

First, there are some commonly agreed on sections - of course you can add more...

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
BUGS
AUTHOR
SEE ALSO

And for each (and everywhere else) you use the groff typesetting macro syntax.

For example, a TITLE HEADER can be done like so -

.TH [name of program] [section number] [center footer] [left footer] [center header]

Or a SECTION HEADER -

.SH [section name]

And of course, you can bold, italic, underline, etc -

.B = bold
.BI = bold alternating italic
.BR = bold alternating Roman
.I = italic
.IB = italic alternating bold
.IR = italic alternating Roman
.RB = Roman alternating bold
.RI = Roman alternating italic 

And you can even make comments in your text file -

." This is a comment

And then things like paragraphing (like the <p></p> html tag set) with .PP

Don't forget to name the file appropriately, and then gzip it when done.

This info (and more) is from http://www.linuxhowtos.org/System/creatingman.htm

  • " Think like HTML... but pre-HTML" -- that is a bit hard, given that I am younger than HTML :P. – cutculus Nov 11 '18 at 0:24
  • I'm not sure how accurate this answer is. man(1) page uses .\" for comments. – cutculus Nov 11 '18 at 0:42
  • @theindigamer I only wrote one man page (out of curiosity, much like the OP seems to be) and it was a long time ago and I don't have the bookmark (maybe at work?). My last sentence states where I got that info. – ivanivan Nov 11 '18 at 2:05
  • Note that manuals may not be written with the same macro package. If they are written using mdoc, then the macros will be completely different. – Kusalananda Nov 11 '18 at 7:59

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.