DOCLIFTER(1)

NAME
 doclifter - translate troff requests into DocBook

SYNOPSIS

doclifter [-h hintfile] [-e encoding] [-q] [-v] [-I path] [-D token=type] file...

DESCRIPTION

doclifter translates documents written in troff macros to DocBook. Structural subsets of the requests in man(7), mdoc(7), ms(7), me(7), mm(7), and troff(1) are supported.

The translation brings over all the structure of the original document at section, subsection, and paragraph level. Command and C function synopses are translated into DocBook markup, not just a verbatim display. Tables (TBL markup) are translated into DocBook table markup. PIC diagrams are translated into SVG. Troff-level information that might have structural implications is preserved in XML comments.

Where possible, font-change macros are translated into structural markup. doclifter recognizes stereotyped patterns of markup and content (such as the use of italics in a FILES section to mark filenames) and lifts them. A means to edit, add, and save semantic hints about highlighting is supported.

Some cliches are recognized and lifted to structural markup even without highlighting. Patterns recognized include such things as URLs, email addresses, man page references, and C program listings.

The
requests are ignored. Thus, presentation-level simulation of tables and columnar-spacing effects using these will not be translated correctly.

Under some circumstances, doclifter can even lift formatted manual pages and the text output produced by lynx(1) from HTML. If it finds no macros in the input, but does find a NAME section header, it tries to interpret the plain text as a manual page (skipping boilerplate headers and footers generated by lynx(1)). Translations produced in this way will be prone to miss structural features, but this fallback is good enough for simple man pages.

doclifter does not do a perfect job, merely an extremely good one. Final polish should be applied by a human being capable of recognizing patterns too subtle for a computer. But doclifter will almost always produce translations that are good enough to be usable before hand-hacking.

See the Troubleshooting section for discussion of how to solve document conversion problems.

OPTIONS

If called without arguments doclifter acts as a filter, translating troff source input on standard input to DocBook markup on standard output. If called with arguments, each argument file is translated separately (but hints are retained, see below); the suffix .xml is given to the translated output.

-h  Name a file to which information on semantic hints gathered during analysis should be written.

-I  The -I option adds its argument to the include path used when docfilter searches for inclusions. The include path is initially just the current directory.

-D  The -D allows you to post a hint. This may be useful, for example, if doclifter is mis-parsing a synopsis because it doesn't recognize a token as a command. This hint is merged after hints in the input source have been read.

-e  The -e allows you to set the encoding field to be emitted in the output XML. It defaults to ISO-8859-1 (Latin-1).

-q  Normally, requests that doclifter could not interpret (usually because they're presentation-level) are passed through to XML comments in the output. The -q option suppresses this. It also suppresses listing of macros. Messages about requests that are unrecognized or cannot be translated go to standard error whatever the state of this option. This option is intended to reduce clutter when you believe you have a clean lift of a document and want to lose the troff legacy.

-v  The -v option makes doclifter noisier about what it's doing. This is mainly useful for debugging.

TRANSLATION RULES

Overall, you can expect that font changes will be turned into Emphasis macros with a Remap attribute taken from the troff font name. The basic font names are R, I, B, U, CW, and SM.

Troff and macro-package special character escapes are mapped into ISO character entities.

When doclifter encounters a .so directive, it searches for the file. If it can get read access to the file, and open it, and the file consists entirely of command lines and comments, then it is included. If any of these conditions fails, an entity reference for it is generated.

doclifter performs special parsing when it recognizes a display such as is generated by

Some notes on specific translations:

  Man Translation

doclifter does a good job on most man pages, It knows about the extended UR/UE/UN requests supported under Linux. If any request is present, it will translate these but not wrap URLs outide them with Ulink tags. It also knows about the extended (literal) font markup from Bell Labs Version 8, and its friends.

The macro is used to generate a RefMeta section. If present, the date/source/manual arguments (see man(7)) are wrapped in RefMiscInfo tag pairs with those class attributes. Note that doclifter does not change the date.

doclifter performs special parsing when it recognizes a synopsis section. It repeatedly tries to parse first a function synopsis, then a command synopsis , and then plain text off what remains in the section.

The following man macros are translated into emphasis tags with a remap attribute:

The following macros are translated into paragraph breaks:

The two-argument form of

    is translated either as a VariableList (usually) or ItemizedList (if the tag is the troff bullet or square character).

The following macros are translated semantically: call just before

or

  sets the ID for the new section.

The \*R, \*(Tm, \*(lq, and \*(rq symbols are translated.

The following (purely presentation-level) macros are ignored:

The macros are translated differently depending on whether or not they precede list markup. When
    occurs just before

    or

        the result is nested lists. Otherwise, the pair is translated into a Blockquote tag-pair.

    is not part of the documented man macro set, but is recognized because it shows up with some frequency on legacy man pages from older Unixes.

    Certain extension macros originally defined under Ultrix are translated structurally, including those that occasionally show up on the manual pages of Linux and other open-source Unixes. (and the symptoms are translated structurally.

    The following extension macros used by the X distribution are also recognized and translated structurally: and IN requests are ignored.

    When the man macros are active, any macro definition containing the request

    will be ignored. and all instances of replaced with will be replaced with

    Known problem areas with man translation:

    •   Weird uses of

    •   It is debatable how the man macros

    and

        without tag should be translated. We treat them as an ordinary paragraph break. We could visually simulate a hanging paragraph with list markup, but this would not be a structural translation.

  Pod2man Translation

doclifter recognizes the extension macros produced by pod2man (.Sh,

The results of lifting pages produced by pod2man should be checked carefully by eyeball, especially the rendering of command and function synopses. Pod2man generates rather perverse markup; doclifter's struggle to untangle it is sometimes in vain.

If possible, generate your DocBook from the POD sources. There is a pod2docbook module on CPAN that does this.

  Tkman Translation

doclifter recognizes the extension macros used by the Tcl/Tk documentation system: macros are translated structurally.

  Mandoc Translation

doclifter should be able to do an excellent job on most mdoc(7) pages, because this macro package expresses a lot of semantic structure.

Known problems with mandoc translation: All display blocks are translated as LiteralLayout tag pairs.

  Ms Translation

doclifter does a good job on most ms pages. One weak spot to watch out for is the generation of Author and Affiliation tags. The heuristics used to mine this information out of the section work for authors who format their names in the way usual for English (e.g. "M. E. Lesk", "Eric S. Raymond") but are quite brittle.

For a document to be recognized as containing ms markup, it must have the extension .ms. This avoids problems with false positives.

The macros turn into article metainformation in the expected way. The macros turn into paragraph and section structure. The tagged form of

    is translated either as a VariableList (usually) or ItemizedList (if the tag is the troff bullet or square character); the untagged version is treated as an ordinary paragraph break.

The pair is translated to a LiteralLayout tag pair. The pair is translated to a Footnote tag pair. The requests define BlockQuotes.

The font change is mapped to U. and become numeric plus or minus size steps suffixed to the Remap attribute.

The and box macros are translated to a Sidebar tag pair.

All macros relating to page footers, multicolumn mode, and keeps are ignored (.ND,
macros are ignored as well.

  Me Translation

Translation of me documents tends to produce crude results that need a lot of hand-hacking. The format has little usable structure, and documents written in it tend to use a lot of low-level troff macros; both these properties tend to confuse doclifter.

For a document to be recognized as containing me markup, it must have the extension .me. This avoids problems with false positives.

The following macros are translated into paragraph breaks: macro is translated into a VariableList. The
macro is translated into an ItemizedList. The macro is translated into an OrderedList.

The b, i, and r fonts are mapped to emphasis tags with B, I, and R Remap attributes. The ("real bold") font is treated the same as

is translated structurally.

Most other requests are ignored.

  Mm Translation

Memorandum Macros documents translate well, as these macros carry a lot of structural information. The translation rules are tuned for Memorandum or Released Paper styles; information associated with external-letter style will be preserved in comments.

For a document to be recognized as containing mm markup, it must have the extension .mm. This avoids problems with false positives.

The following highlight macros are translated int Emphasis tags:

The following macros are structurally translated:

The following macros are ignored:

.)E,

The following macros generate warnings:

.BS/.BE and pairs are passed through. The text inside them may need to be deleted or moved.

The mark argument of is ignored; the following list id formatted as a normal ItemizedList.

The contents of or gets turned into a Screen display. Arguments controlling presentation-level formatting are ignored.

  Mwww Translation

The mwww macros are an extension to the man macros supported by groff(1) for producing web pages.

The URL, FTP, MAILTO, FTP, IMAGE, TAG tags are translated structurally. The HTMLINDEX, BODYCOLOR, BACKGROUND, HTML, an LINE tags are ignored.

  TBL Translation

All structural features of TBL tables are translated, including both horizontal and vertical spanning with ‘s’ and ‘^’. The ‘l’, ‘r’, and ‘c’ formats are supported; the ‘n’ column format is rendered as ‘r’. Line continuations with T{ and T} are handled correctly. So is

The expand, box, doublebox, allbox, center, left, and right options are supported. The GNU synonyms frame and doubleframe are also recognized. But the distinction between single and double rules and boxes is lost.

Table continuations (.T&) are not supported.

If the first nonempty line of text immediately before a table is boldfaced, it is interpreted as a title for the table and the table is generated using a table and title. Otherwise the table is translated with infornaltable.

Most other presentation-level TBL commands are ignored. The ‘b’ format qualifier is processed, but point size and width qualifiers are not.

  Pic Translation

PIC sections are translated to SVG. doclifter calls out to pic2plot(1) to accomplish this; you must have that utility installed for PIC translation to work.

  Eqn Translation

EQN sections are passed through enclosed in LiteralLayout tags. After a delim statement has been seen, inline eqn delimiters are translated into an XML processing instruction. Exception: inline eqn equations consisting of a single character are translated to an Emphasis with a Role attribute of eqn.

  Troff Translation

The troff translation is meant only to support interpretation of the macro sets. It is not useful standalone.

The
and
macros are interpreted as literal-layout boundaries. Calls to the .so macro either cause inclusion or are translated into XML entity inclusions (see above). Calls to the and macros cause following lines to be wrapped in an Emphasis tag with a Remap attribute of "U". Calls to generate corresponding start or end emphasis tags. Calls to cause character translation on output. Calls to
generate a BeginPage tag. Calls to

generate a paragraph break (in paragraphed text only). These are the only troff requests we translate to DocBook. The rest of the troff emulation exists because macro packages use it internally to expand macros into elements that might be structural.

Requests relating to macro definitions and strings (.ds,