1DOCLIFTER(1) Documentation Tools DOCLIFTER(1)
2
6 doclifter - translate troff requests into DocBook
7
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
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 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 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 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 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 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 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 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 See the Troubleshooting section for discussion of how to solve document
58 conversion problems.
59
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 -o
68 Set the output location where files will be saved. Defaults to
69 current working directory.
70 -h
72 Name a file to which information on semantic hints gathered during
73 analysis should be written.
74 -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 -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 -S
87 Set the filename to be used in error and warning messages. This is
88 mainly inttended for use by test scripts.
89 -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 -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 -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 -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 -v
116 The -v option makes doclifter noisier about what it's doing. This
117 is mainly useful for debugging.
118 -w
120 Enable strict portability checking. Multiple instances of -w
121 increase the strictness. See the section called “PORTABILITY
122 CHECKING”.
123 -V
125 With this option, the program emits a version message and exits.
126
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 Troff and macro-package special character escapes are mapped into ISO
133 character entities.
134 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 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 Some notes on specific translations:
146 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 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 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 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 The following macros are translated into paragraph breaks: .LP, .PP,
169 .P, .HP, and the single-argument form of .IP.
170 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 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 The \*R, \*(Tm, \*(lq, and \*(rq symbols are translated.
180 The following (purely presentation-level) macros are ignored: .PD,.DT.
182 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 .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 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 .NT/.NE, .PN, and .MS are translated structurally.
198 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 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 Known problem areas with man translation:
211 • 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 • 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 Pod2man Translation
222 doclifter recognizes the extension macros produced by pod2man (.Sh,
223 .Sp, .Ip, .Vb, .Ve) and translates them structurally.
224 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 If possible, generate your DocBook from the POD sources. There is a
231 pod2docbook module on CPAN that does this.
232 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 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 Known problems with mandoc translation: All .Bd/.Ed display blocks are
244 translated as LiteralLayout tag pairs .
245 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 For a document to be recognized as containing ms markup, it must have
254 the extension .ms. This avoids problems with false positives.
255 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 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 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 The .B1 and .B2 box macros are translated to a Sidebar tag pair.
271 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 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 For a document to be recognized as containing me markup, it must have
283 the extension .me. This avoids problems with false positives.
284 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 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 .q(/.q) is translated structurally .
294 Most other requests are ignored.
296 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 For a document to be recognized as containing mm markup, it must have
304 the extension .mm. This avoids problems with false positives.
305 The following highlight macros are translated int Emphasis tags: .B,
307 .I, .R, .BI, .BR, .IB, .IR, .RB, .RI.
308 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 The following macros are ignored:
315 .)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 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 Pairs of .DS/.DE are interpreted as informal figures. If an .FG is
326 present it becomes a caption element.
327 .BS/.BE and .IA/.IE pairs are passed through. The text inside them may
329 need to be deleted or moved.
330 The mark argument of .ML is ignored; the following list id formatted as
332 a normal ItemizedList.
333 The contents of .DS/.DE or .DF/.DE gets turned into a Screen display.
335 Arguments controlling presentation-level formatting are ignored.
336 Mwww Translation
338 The mwww macros are an extension to the man macros supported by
339 groff(1) for producing web pages.
340 The URL, FTP, MAILTO, FTP, IMAGE, TAG tags are translated structurally.
342 The HTMLINDEX, BODYCOLOR, BACKGROUND, HTML, and LINE tags are ignored.
343 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 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 Table continuations (.T&) are not supported.
355 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 Most other presentation-level TBL commands are ignored. The ‘b’ format
362 qualifier is processed, but point size and width qualifiers are not.
363 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 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 Troff Translation
378 The troff translation is meant only to support interpretation of the
379 macro sets. It is not useful standalone.
380 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 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 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 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 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 Some troff escape sequences are lifted:
413 1. The \e and \\ escapes become a bare backslash, \. a period, and \-
415 a bare dash.
416 2. The troff escapes \^, \`, \' \&, \0, and \| are lifted to
418 equivalent ISO special spacing characters.
419 3. A \ followed by space is translated to an ISO non-breaking space
421 entity.
422 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 5. The \u and \d half-line motion vertical motion escapes, when
429 paired, become Superscript or Subscript tags.
430 6. The \c escape is handled as a line continuation. in circumstances
432 where that matters (e.g. for token-pasting).
433 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 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 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 Other escapes than these will yield warnings or errors.
450 All other troff requests are ignored but passed through into XML
452 comments. A few (such as .ce) also trigger a warning message.
453
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 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 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
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 • Names of function formal arguments
476 • Names of command options
478 Local hints are used to mark up the individual page from which they are
480 gathered. The global list includes:
481 • Names of functions
483 • Names of commands
485 • Names of function return types
487 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 .\" | mark <phrase> as <markup>
493 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 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 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
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 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 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 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 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 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 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 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
570 There are a few constructions that are a good idea to check by hand
571 after lifting a page.
572 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 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
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 Equation number arguments of EQN calls are ignored.
589 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 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 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 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 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 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 Macro definitions in a manual page NAME section are not interpreted.
617 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 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 The line numbers in doclifter error messages are unreliable in the
627 presence of .EQ/.EN, .PS/.PE, and quantum fluctuations.
628
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
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 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
650 The pic2plot(1) utility must be installed in order to translate PIC
651 diagrams to SVG.
652
654 man(7), mdoc(7), ms(7), me(7), mm(7), mwww(7), troff(1).
655
657 Eric S. Raymond <esr@thyrsus.com>
658 There is a project web page at http://www.catb.org/~esr/doclifter/.
660doclifter 01/19/2023 DOCLIFTER(1)