1DOCLIFTER(1)                  Documentation Tools                 DOCLIFTER(1)
2
3
4

NAME

6       doclifter - translate troff requests into DocBook
7

SYNOPSIS

9       doclifter [-o output-location] [-e output-encoding]
10                 [-i input-encodings] [-h hintfile] [-q] [-x] [-v] [-w] [-V]
11                 [-D token=type] [-I path] [-S spoofname] file...
12

DESCRIPTION

14       doclifter translates documents written in troff macros to DocBook.
15       Structural subsets of the requests in man(7), mdoc(7), ms(7), me(7),
16       mm(7), and troff(1) are supported.
17
18       The translation brings over all the structure of the original document
19       at section, subsection, and paragraph level. Command and C function
20       synopses are translated into DocBook markup, not just a verbatim
21       display. Tables (TBL markup) are translated into DocBook table markup.
22       PIC diagrams are translated into SVG. Troff-level information that
23       might have structural implications is preserved in XML comments.
24
25       Where possible, font-change macros are translated into structural
26       markup.  doclifter recognizes stereotyped patterns of markup and
27       content (such as the use of italics in a FILES section to mark
28       filenames) and lifts them. A means to edit, add, and save semantic
29       hints about highlighting is supported.
30
31       Some cliches are recognized and lifted to structural markup even
32       without highlighting. Patterns recognized include such things as URLs,
33       email addresses, man page references, and C program listings.
34
35       The tag .in and .ti requests are passed through with complaints. They
36       indicate presentation-level markup that doclifter cannot translate into
37       structure; the output will require hand-fixing.
38
39       The tag .ta is passed through with a complaint unless the immediarely
40       following by text lines contains a tab, in which case the following
41       span of lines containing tabs is lifted to a table.
42
43       Under some circumstances, doclifter can even lift formatted manual
44       pages and the text output produced by lynx(1) from HTML. If it finds no
45       macros in the input, but does find a NAME section header, it tries to
46       interpret the plain text as a manual page (skipping boilerplate headers
47       and footers generated by lynx(1)). Translations produced in this way
48       will be prone to miss structural features, but this fallback is good
49       enough for simple man pages.
50
51       doclifter does not do a perfect job, merely a surprisingly good one.
52       Final polish should be applied by a human being capable of recognizing
53       patterns too subtle for a computer. But doclifter will almost always
54       produce translations that are good enough to be usable before
55       hand-hacking.
56
57       See the Troubleshooting section for discussion of how to solve document
58       conversion problems.
59

OPTIONS

61       If called without arguments doclifter acts as a filter, translating
62       troff source input on standard input to DocBook markup on standard
63       output. If called with arguments, each argument file is translated
64       separately (but hints are retained, see below); the suffix .xml is
65       given to the translated output.
66
67       -o
68           Set the output location where files will be saved. Defaults to
69           current working directory.
70
71       -h
72           Name a file to which information on semantic hints gathered during
73           analysis should be written.
74
75       -D
76           The -D allows you to post a hint. This may be useful, for example,
77           if doclifter is mis-parsing a synopsis because it doesn't recognize
78           a token as a command. This hint is merged after hints in the input
79           source have been read.
80
81       -I
82           The -I option adds its argument to the include path used when
83           docfilter searches for inclusions. The include path is initially
84           just the current directory.
85
86       -S
87           Set the filename to be used in error and warning messages. This is
88           mainly inttended for use by test scripts.
89
90       -e
91           The -e allows you to set the output encoding of the XML and the
92           encoding field to be emitted in its header. It defaults to UTF-8.
93
94       -i
95           The -i allows you to set a comma-separated list of encodings to be
96           looked for in the input. The default is "ISO-8859-1,UTF-8", which
97           should cover almost all cases.
98
99       -q
100           Normally, requests that doclifter could not interpret (usually
101           because they're presentation-level) are passed through to XML
102           comments in the output. The -q option suppresses this. It also
103           suppresses listing of macros. Messages about requests that are
104           unrecognized or cannot be translated go to standard error whatever
105           the state of this option. This option is intended to reduce clutter
106           when you believe you have a clean lift of a document and want to
107           lose the troff legacy.
108
109       -x
110           The -x option requests that doclifter generate DocBook version 5
111           compatible xml content, rather than its default DocBook version 4.4
112           output. Inclusions and entities may not be handled correctly with
113           this switch enabled.
114
115       -v
116           The -v option makes doclifter noisier about what it's doing. This
117           is mainly useful for debugging.
118
119       -w
120           Enable strict portability checking. Multiple instances of -w
121           increase the strictness. See the section called “PORTABILITY
122           CHECKING”.
123
124       -V
125           With this option, the program emits a version message and exits.
126

TRANSLATION RULES

128       Overall, you can expect that font changes will be turned into Emphasis
129       macros with a Remap attribute taken from the troff font name. The basic
130       font names are R, I, B, U, CW, and SM.
131
132       Troff and macro-package special character escapes are mapped into ISO
133       character entities.
134
135       When doclifter encounters a .so directive, it searches for the file. If
136       it can get read access to the file, and open it, and the file consists
137       entirely of command lines and comments, then it is included. If any of
138       these conditions fails, an entity reference for it is generated.
139
140       doclifter performs special parsing when it recognizes a display such as
141       is generated by .DS/.DE. It repeatedly tries to parse first a function
142       synopsis, and then plain text off what remains in the display. Thus,
143       most inline C function prototypes will be lifted to structured markup.
144
145       Some notes on specific translations:
146
147   Man Translation
148       doclifter does a good job on most man pages, It knows about the
149       extended UR/UE/UN and URL requests supported under Linux. If any .UR
150       request is present, it will translate these but not wrap URLs outide
151       them with Ulink tags. It also knows about the extended .L (literal)
152       font markup from Bell Labs Version 8, and its friends.
153
154       The .TH macro is used to generate a RefMeta section. If present, the
155       date/source/manual arguments (see man(7)) are wrapped in RefMiscInfo
156       tag pairs with those class attributes. Note that doclifter does not
157       change the date.
158
159       doclifter performs special parsing when it recognizes a synopsis
160       section. It repeatedly tries to parse first a function synopsis, then a
161       command synopsis, and then plain text off what remains in the section.
162
163       The following man macros are translated into emphasis tags with a remap
164       attribute: .B, .I, .L, .BI, .BR, .BL, .IB, .IR, .IL, .RB, .RI, .RL,
165       .LB, .LI, .LR, .SB, .SM. Some stereotyped patterns involving these
166       macros are recognized and turned into semantic markup.
167
168       The following macros are translated into paragraph breaks: .LP, .PP,
169       .P, .HP, and the single-argument form of .IP.
170
171       The two-argument form of .IP is translated either as a VariableList
172       (usually) or ItemizedList (if the tag is the troff bullet or square
173       character).
174
175       The following macros are translated semantically: .SH,.SS, .TP, .UR,
176       .UE, .UN, .IX. A .UN call just before .SH or .SS sets the ID for the
177       new section.
178
179       The \*R, \*(Tm, \*(lq, and \*(rq symbols are translated.
180
181       The following (purely presentation-level) macros are ignored: .PD,.DT.
182
183       The .RS/.RE macros are translated differently depending on whether or
184       not they precede list markup. When .RS occurs just before .TP or .IP
185       the result is nested lists. Otherwise, the .RS/.RE pair is translated
186       into a Blockquote tag-pair.
187
188       .DS/.DE is not part of the documented man macro set, but is recognized
189       because it shows up with some frequency on legacy man pages from older
190       Unixes.
191
192       Certain extension macros originally defined under Ultrix are translated
193       structurally, including those that occasionally show up on the manual
194       pages of Linux and other open-source Unixes.  .EX/.EE (and the synonyms
195       .Ex/.Ee), .Ds/.De,
196
197       .NT/.NE, .PN, and .MS are translated structurally.
198
199       The following extension macros used by the X distribution are also
200       recognized and translated structurally: .FD, .FN, .IN, .ZN, .hN, and
201       .C{/.C} The .TA and .IN requests are ignored.
202
203       When the man macros are active, any .Pp macro definition containing the
204       request .PP will be ignored. and all instances of .Pp replaced with
205       .PP. Similarly, .Tp will be replaced with .TP. This is the least
206       painful way to deal with some frequently-encountered stereotyped
207       wrapper definitions that would otherwise cause serious interpretation
208       problems
209
210       Known problem areas with man translation:
211
212       ·   Weird uses of .TP. These will sometime generate invalid XML and
213           sometimes result in a FIXME comment in the generated XML (a warning
214           message will also go to standard error).
215
216       ·   It is debatable how the man macros .HP and .IP without tag should
217           be translated. We treat them as an ordinary paragraph break. We
218           could visually simulate a hanging paragraph with list markup, but
219           this would not be a structural translation.
220
221   Pod2man Translation
222       doclifter recognizes the extension macros produced by pod2man (.Sh,
223       .Sp, .Ip, .Vb, .Ve) and translates them structurally.
224
225       The results of lifting pages produced by pod2man should be checked
226       carefully by eyeball, especially the rendering of command and function
227       synopses.  Pod2man generates rather perverse markup; doclifter's
228       struggle to untangle it is sometimes in vain.
229
230       If possible, generate your DocBook from the POD sources. There is a
231       pod2docbook module on CPAN that does this.
232
233   Tkman Translation
234       doclifter recognizes the extension macros used by the Tcl/Tk
235       documentation system: .AP, .AS, .BS, .BE, .CS, .CE, .DS, .DE, .SO, .SE,
236       .UL, .VS, .VE. The .AP, .CS, .CE, .SO, .SE, .UL, .QW and .PQ macros are
237       translated structurally.
238
239   Mandoc Translation
240       doclifter should be able to do an excellent job on most mdoc(7) pages,
241       because this macro package expresses a lot of semantic structure.
242
243       Known problems with mandoc translation: All .Bd/.Ed display blocks are
244       translated as LiteralLayout tag pairs .
245
246   Ms Translation
247       doclifter does a good job on most ms pages. One weak spot to watch out
248       for is the generation of Author and Affiliation tags. The heuristics
249       used to mine this information out of the .AU section work for authors
250       who format their names in the way usual for English (e.g. "M. E. Lesk",
251       "Eric S. Raymond") but are quite brittle.
252
253       For a document to be recognized as containing ms markup, it must have
254       the extension .ms. This avoids problems with false positives.
255
256       The .TL, .AU, .AI, and .AE macros turn into article metainformation in
257       the expected way. The .PP, .LP, .SH, and .NH macros turn into paragraph
258       and section structure. The tagged form of .IP is translated either as a
259       VariableList (usually) or ItemizedList (if the tag is the troff bullet
260       or square character); the untagged version is treated as an ordinary
261       paragraph break.
262
263       The .DS/.DE pair is translated to a LiteralLayout tag pair . The
264       .FS/.FE pair is translated to a Footnote tag pair. The .QP/.QS/.QE
265       requests define BlockQuotes.
266
267       The .UL font change is mapped to U.  .SM and .LG become numeric plus or
268       minus size steps suffixed to the Remap attribute.
269
270       The .B1 and .B2 box macros are translated to a Sidebar tag pair.
271
272       All macros relating to page footers, multicolumn mode, and keeps are
273       ignored (.ND, .DA, .1C, .2C, .MC, .BX, .KS, .KE, .KF). The .R, .RS, and
274       .RE macros are ignored as well.
275
276   Me Translation
277       Translation of me documents tends to produce crude results that need a
278       lot of hand-hacking. The format has little usable structure, and
279       documents written in it tend to use a lot of low-level troff macros;
280       both these properties tend to confuse doclifter.
281
282       For a document to be recognized as containing me markup, it must have
283       the extension .me. This avoids problems with false positives.
284
285       The following macros are translated into paragraph breaks: .lp, .pp.
286       The .ip macro is translated into a VariableList. The .bp macro is
287       translated into an ItemizedList. The .np macro is translated into an
288       OrderedList.
289
290       The b, i, and r fonts are mapped to emphasis tags with B, I, and R
291       Remap attributes. The .rb ("real bold") font is treated the same as .b.
292
293       .q(/.q) is translated structurally .
294
295       Most other requests are ignored.
296
297   Mm Translation
298       Memorandum Macros documents translate well, as these macros carry a lot
299       of structural information. The translation rules are tuned for
300       Memorandum or Released Paper styles; information associated with
301       external-letter style will be preserved in comments.
302
303       For a document to be recognized as containing mm markup, it must have
304       the extension .mm. This avoids problems with false positives.
305
306       The following highlight macros are translated int Emphasis tags: .B,
307       .I, .R, .BI, .BR, .IB, .IR, .RB, .RI.
308
309       The following macros are structurally translated: .AE, .AF, .AL, .RL,
310       .APP, .APPSK, .AS, .AT, .AU, .B1, .B2, .BE, .BL, .ML, .BS, .BVL, .VL,
311       .DE, .DL .DS, .FE, .FS, .H, .HU, .IA, .IE, .IND, .LB, .LC, .LE, .LI,
312       .P, .RF, .SM, .TL, .VERBOFF, .VERBON, .WA, .WE.
313
314       The following macros are ignored:
315
316        .)E, .1C, .2C, .AST, .AV, .AVL, .COVER, .COVEND, .EF, .EH, .EDP,
317       .EPIC, .FC, .FD, .HC, .HM, .GETR, .GETST, .HM, .INITI, .INITR, .INDP,
318       .ISODATE, .MT, .NS, .ND, .OF, .OH, .OP, .PGFORM, .PGNH, .PE, .PF, .PH,
319       .RP, .S, .SA, .SP, .SG, .SK, .TAB, .TB, .TC, .VM, .WC.
320
321       The following macros generate warnings: .EC, .EX, .GETHN, .GETPN,
322       .GETR, .GETST, .LT, .LD, .LO, .MOVE, .MULB, .MULN, .MULE, .NCOL, .nP,
323       .PIC, .RD, .RS, .RE, .SETR
324
325       Pairs of .DS/.DE are interpreted as informal figures. If an .FG is
326       present it becomes a caption element.
327
328        .BS/.BE and .IA/.IE pairs are passed through. The text inside them may
329       need to be deleted or moved.
330
331       The mark argument of .ML is ignored; the following list id formatted as
332       a normal ItemizedList.
333
334       The contents of .DS/.DE or .DF/.DE gets turned into a Screen display.
335       Arguments controlling presentation-level formatting are ignored.
336
337   Mwww Translation
338       The mwww macros are an extension to the man macros supported by
339       groff(1) for producing web pages.
340
341       The URL, FTP, MAILTO, FTP, IMAGE, TAG tags are translated structurally.
342       The HTMLINDEX, BODYCOLOR, BACKGROUND, HTML, and LINE tags are ignored.
343
344   TBL Translation
345       All structural features of TBL tables are translated, including both
346       horizontal and vertical spanning with ‘s’ and ‘^’. The ‘l’, ‘r’, and
347       ‘c’ formats are supported; the ‘n’ column format is rendered as ‘r’.
348       Line continuations with T{ and T} are handled correctly. So is .TH.
349
350       The expand, box, doublebox, allbox, center, left, and right options are
351       supported. The GNU synonyms frame and doubleframe are also recognized.
352       But the distinction between single and double rules and boxes is lost.
353
354       Table continuations (.T&) are not supported.
355
356       If the first nonempty line of text immediately before a table is
357       boldfaced, it is interpreted as a title for the table and the table is
358       generated using a table and title. Otherwise the table is translated
359       with informaltable.
360
361       Most other presentation-level TBL commands are ignored. The ‘b’ format
362       qualifier is processed, but point size and width qualifiers are not.
363
364   Pic Translation
365       PIC sections are translated to SVG.  doclifter calls out to pic2plot(1)
366       to accomplish this; you must have that utility installed for PIC
367       translation to work.
368
369   Eqn Translation
370       EQN sections are filtered into embedded MathML with eqn -TMathML if
371       possible, otherwise passed through enclosed in LiteralLayout tags.
372       After a delim statement has been seen, inline eqn delimiters are
373       translated into an XML processing instruction. Exception: inline eqn
374       equations consisting of a single character are translated to an
375       Emphasis with a Role attribute of eqn.
376
377   Troff Translation
378       The troff translation is meant only to support interpretation of the
379       macro sets. It is not useful standalone.
380
381       The .nf and .fi macros are interpreted as literal-layout boundaries.
382       Calls to the .so macro either cause inclusion or are translated into
383       XML entity inclusions (see above). Calls to the .ul and .cu macros
384       cause following lines to be wrapped in an Emphasis tag with a Remap
385       attribute of "U". Calls to .ft generate corresponding start or end
386       emphasis tags. Calls to .tr cause character translation on output.
387       Calls to .bp generate a BeginPage tag (in paragraphed text only). Calls
388       to .sp generate a paragraph break (in paragraphed text only). Calls to
389       .ti wrap the following line in a BlockQuote These are the only troff
390       requests we translate to DocBook. The rest of the troff emulation
391       exists because macro packages use it internally to expand macros into
392       elements that might be structural.
393
394       Requests relating to macro definitions and strings (.ds, .as, .de, .am,
395       .rm, .rn, .em) are processed and expanded. The .ig macro is also
396       processed.
397
398       Conditional macros (.if, .ie, .el) are handled. The built-in conditions
399       o, n, t, e, and c are evaluated as if for nroff on page one of a
400       document. The m, d, and r troff conditionals are also interpreted.
401       String comparisons are evaluated by straight textual comparison. All
402       numeric expressions evaluate to true.
403
404       The extended groff requests cc, c2, ab, als, do, nop, and return and
405       shift are interpreted. Its .PSPIC extension is translated into a
406       MediaObject.
407
408       The .tm macro writes its arguments to standard error (with -t). The .pm
409       macro reports on defined macros and strings. These facilities may aid
410       in debugging your translation.
411
412       Some troff escape sequences are lifted:
413
414        1. The \e and \\ escapes become a bare backslash, \. a period, and \-
415           a bare dash.
416
417        2. The troff escapes \^, \`, \' \&, \0, and \| are lifted to
418           equivalent ISO special spacing characters.
419
420        3. A \ followed by space is translated to an ISO non-breaking space
421           entity.
422
423        4. A \~ is also translated to an ISO non-breaking space entity;
424           properly this should be a space that can't be used for a linebreak
425           but stretches like ordinary whitepace during line adjustment, but
426           there is no ISO or Unicode entity for that.
427
428        5. The \u and \d half-line motion vertical motion escapes, when
429           paired, become Superscript or Subscript tags.
430
431        6. The \c escape is handled as a line continuation. in circumstances
432           where that matters (e.g. for token-pasting).
433
434        7. The \f escape for font changes is translated in various
435           context-dependent ways. First, doclifter looks for cliches
436           involving font changes that have semantic meaning, and lifts to a
437           structural tag. If it can't do that, it generates an Emphasis tag.
438
439        8. The \m[] extension is translated into a phrase span with a remap
440           attribute carrying the color. Note: Stylesheets typically won't
441           render this!
442
443        9. Some uses of the \o request are translated: pairs with a letter
444           followed by one of the characters ` ' : ^ o ~ are translated to
445           combining forms with diacriticals acute, grave, umlaut, circumflex,
446           ring, and tilde respectively if the corresponding Latin-1 or
447           Latin-2 character exists as an ISO literal.
448
449       Other escapes than these will yield warnings or errors.
450
451       All other troff requests are ignored but passed through into XML
452       comments. A few (such as .ce) also trigger a warning message.
453

PORTABILITY CHECKING

455       When portability checking is enabled, doclifter emits portability
456       warnings about markup which it can handle but which will break various
457       other viewers and interpreters.
458
459        1. At level 1, it will warn about constructions that would break
460           man2html(1), (the C program distributed with Linux man(1), not the
461           older and much less capable Perl script). A close derivative of
462           this code is used in GNOME yelp. This should be the minimum level
463           of portability you aim for, and corresponds to what is recommended
464           on the groff_man(7) manual page.
465
466        2. At level 2, it will warn about constructions that will break
467           portability back to the Unix classic tools (including long macro
468           names and glyph references with \[]).
469

SEMANTIC ANALYSIS

471       doclifter keeps two lists of semantic hints that it picks up from
472       analyzing source documents (especially from parsing command and
473       function synopses). The local list includes:
474
475       ·   Names of function formal arguments
476
477       ·   Names of command options
478
479       Local hints are used to mark up the individual page from which they are
480       gathered. The global list includes:
481
482       ·   Names of functions
483
484       ·   Names of commands
485
486       ·   Names of function return types
487
488       If doclifter is applied to multiple files, the global list is retained
489       in memory. You can dump a report of global hints at the end of the run
490       with the -h option. The format of the hints is as follows:
491
492            .\" | mark <phrase> as <markup>
493
494       where <phrase> is an item of text and <markup> is the DocBook markup
495       text it should be wrapped with whenever it appeared either highlighted
496       or as a word surrounded by whitespace in the source text.
497
498       Hints derived from earlier files are also applied to later ones. This
499       behavior may be useful when lifting collections of documents that apply
500       to a function or command library. What should be more useful is the
501       fact that a hints file dumped with -h can be one of the file arguments
502       to doclifter; the code detects this special case and does not write XML
503       output for such a file. Thus, a good procedure for lifting a large
504       library is to generate a hints file with a first run, inspect it to
505       delete false positives, and use it as the first input to a second run.
506
507       It is also possible to include a hints file directly in a troff
508       sourcefile. This may be useful if you want to enrich the file by stages
509       before converting to XML.
510

TROUBLESHOOTING

512       doclifter tries to warn about problems that it can can diagnose but not
513       fix by itself. When it says "look for FIXME", do that in the generated
514       XML; the markup around that token may be wrong.
515
516       Occasionally (less than 2% of the time) doclifter will produce invalid
517       DocBook markup even from correct troff markup. Usually this results
518       from strange constructions in the source page, or macro calls that are
519       beyond the ability of doclifter's macro processor to get right. Here
520       are some things to watch for, and how to fix them:
521
522   Malformed command synopses.
523       If you get a message that says "command synopsis parse failed", try
524       rewriting the synopsis in your manual page source. The most common
525       cause of failure is unbalanced [] groupings, a bug that can be very
526       difficult to notice by eyeball. To assist with this, the error message
527       includes a token number in parentheses indicating on which token the
528       parse failed.
529
530       For more information, use the -v option. This will trigger a dump
531       telling you what the command synopsis looked like after preprocessing,
532       and indicate on which token the parse failed (both with a token number
533       and a caret sign inserted in the dump of the synopsis tokens). Try
534       rewriting the synopsis in your manual page source. The most common
535       cause of failure is unbalanced [] groupings, a bug that can be very
536       difficult to notice by eyeball. To assist with this, the error token
537       dump tries to insert ‘$’ at the point of the last nesting-depth
538       increase, but the code that does this is failure-prone.
539
540   Confusing macro calls.
541       Some manual page authors replace standard requests (like .PP, .SH and
542       .TP) with versions that do different things in nroff and troff
543       environments. While doclifter tries to cope and usually does a good
544       job, the quirks of [nt]roff are legion and confusing macro calls
545       sometimes lead to bad XML being generated. A common symptom of such
546       problems is unclosed Emphasis tags.
547
548   Malformed list syntax.
549       The manual-page parser can be confused by .TP constructs that have
550       header tags but no following body. If the XML produced doesn't
551       validate, and the problem seems to be a misplaced listitem tag, try
552       using the verbose (-v) option. This will enable line-numbered warnings
553       that may help you zero in on the problem.
554
555   Section nesting problems with SS.
556       The message "possible section nesting error" means that the program has
557       seen two adjacent subsection headers. In man pages, subsections don't
558       have a depth argument, so doclifter cannot be certain how subsections
559       should be nested. Any subsection heading between the indicated line and
560       the beginning of the next top-level section might be wrong and require
561       correcting by hand.
562
563   Bad output with no doclifter error message
564       If you're translating a page that uses user-defined macros, and
565       doclifter fails to complain about it but you get bad output, the first
566       thing to do is simplify or eliminate the user-defined macros. Replace
567       them with stock requests where possible.
568

IMPROVING TRANSLATION QUALITY

570       There are a few constructions that are a good idea to check by hand
571       after lifting a page.
572
573       Look near the BlockQuote tags. The troff temporary indent request (.ti)
574       is translated into a BlockQuote wrapper around the following line.
575       Sometimes LiteralLayout or ProgramListing would be a better
576       translation, but doclifter has no way to know this.
577
578       It is not possible to unambiguously detect candidates for wrapping in a
579       DocBook option tag in running text. If you care, you'll have to check
580       for these and fix them by hand.
581

BUGS AND LIMITATIONS

583       About 3% of man pages will either make this program throw error status
584       1 or generate invalid XML. In almost all such cases the misbehavior is
585       triggered by markup bugs in the source that are too severe to be coped
586       with.
587
588       Equation number arguments of EQN calls are ignored.
589
590       Semicolon used as a TBL field separator will lead to garbled tables.
591       The easiest way to fix this is by patching the source.
592
593       The function-synopsis parser is crude (it's not a compiler) and prone
594       to errors. Function-synopsis markup should be checked carefully by a
595       human.
596
597       If a man page has both paragraphed text in a Synopsis section and also
598       a body section before the Synopis section, bad things will happen.
599
600       Running text (e.g., explanatory notes) at the end of a Synopsis section
601       cannot reliably be distinguished from synopsis-syntax markup. (This
602       problem is AI-complete.)
603
604       Some firewalls put in to cope with common malformations in troff code
605       mean that the tail end of a span between two \f{B,I,U,(CW} or .ft
606       highlight changes may not be completely covered by corresponding
607       Emphasis macros if (for example) the span crosses a boundary between
608       filled and unfilled (.nf/.fi) text.
609
610       The treatment of conditionals relies on the assumption that conditional
611       macros never generate structural or font-highlight markup that differs
612       between the if and else branches. This appears to be true of all the
613       standard macro packages, but if you roll any of your own macros you're
614       on your own.
615
616       Macro definitions in a manual page NAME section are not interpreted.
617
618       Uses of \c for line continuation sometimes are not translated, leaving
619       the \c in the output XML. The program will print a warning when this
620       occurs.
621
622       It is not possible to unambiguously detect candidates for wrapping in a
623       DocBook option tag in running text. If you care, you'll have to check
624       for these and fix them by hand.
625
626       The line numbers in doclifter error messages are unreliable in the
627       presence of .EQ/.EN, .PS/.PE, and quantum fluctuations.
628

OLD MACRO SETS

630       There is a conflict between Berkeley ms's documented .P1
631       print-header-on-page request and an undocumented Bell Labs use for
632       displayed program and equation listings. The ms translator uses the
633       Bell Labs interpretation when .P2 is present in the document, and
634       otherwise ignores the request.
635

RETURN VALUES

637       On successful completion, the program returns status 0. It returns 1 if
638       some file or standard input could not be translated. It returns 2 if
639       one of the input sources was a .so inclusion. It returns 3 if there is
640       an error in reading or writing files. It returns 4 to indicate an
641       internal error. It returns 5 when aborted by a keyboard interrupt.
642
643       Note that a zero return does not guarantee that the output is valid
644       DocBook. It will almost always (as in, more than 98% of cases) be
645       syntactically valid XML, but in some rare cases fixups by hand may be
646       necessary to meet the semantics of the DocBook DTD. Validation problems
647       are most likely to occur with complicated list markup.
648

REQUIREMENTS

650       The pic2plot(1) utility must be installed in order to translate PIC
651       diagrams to SVG.
652

SEE ALSO

654       man(7), mdoc(7), ms(7), me(7), mm(7), mwww(7), troff(1).
655

AUTHOR

657       Eric S. Raymond <esr@thyrsus.com>
658
659       There is a project web page at http://www.catb.org/~esr/doclifter/.
660
661
662
663doclifter                         06/12/2018                      DOCLIFTER(1)
Impressum