Annotation of src/usr.bin/mandoc/mandoc.1, Revision 1.62
1.62 ! schwarze 1: .\" $OpenBSD: mandoc.1,v 1.61 2014/08/30 18:04:52 schwarze Exp $
1.1 kristaps 2: .\"
1.44 schwarze 3: .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.58 schwarze 4: .\" Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
1.1 kristaps 5: .\"
6: .\" Permission to use, copy, modify, and distribute this software for any
1.3 schwarze 7: .\" purpose with or without fee is hereby granted, provided that the above
8: .\" copyright notice and this permission notice appear in all copies.
1.1 kristaps 9: .\"
1.3 schwarze 10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1 kristaps 17: .\"
1.62 ! schwarze 18: .Dd $Mdocdate: August 30 2014 $
1.2 deraadt 19: .Dt MANDOC 1
1.1 kristaps 20: .Os
21: .Sh NAME
22: .Nm mandoc
23: .Nd format and display UNIX manuals
24: .Sh SYNOPSIS
25: .Nm mandoc
1.62 ! schwarze 26: .Op Fl acfhklV
1.54 schwarze 27: .Sm off
28: .Op Fl I Cm os Li = Ar name
29: .Sm on
1.1 kristaps 30: .Op Fl m Ns Ar format
1.26 jmc 31: .Op Fl O Ns Ar option
1.17 schwarze 32: .Op Fl T Ns Ar output
1.38 schwarze 33: .Op Fl W Ns Ar level
1.45 schwarze 34: .Op Ar
1.1 kristaps 35: .Sh DESCRIPTION
36: The
37: .Nm
1.10 schwarze 38: utility formats
1.1 kristaps 39: .Ux
1.25 jmc 40: manual pages for display.
1.53 schwarze 41: .Pp
42: By default,
43: .Nm
44: reads
45: .Xr mdoc 7
46: or
47: .Xr man 7
48: text from stdin, implying
49: .Fl m Ns Cm andoc ,
50: and produces
51: .Fl T Ns Cm ascii
52: output.
53: .Pp
1.61 schwarze 54: The options are as follows:
1.5 schwarze 55: .Bl -tag -width Ds
1.60 schwarze 56: .It Fl a
57: If the standard output is a terminal device and
58: .Fl c
59: is not specified, use
60: .Xr more 1
61: to paginate the output, just like
62: .Xr man 1
63: would.
64: .It Fl c
65: Copy the formatted manual pages to the standard output without using
66: .Xr more 1
67: to paginate them.
68: This is the default.
69: It can be specified to override
70: .Fl a .
1.61 schwarze 71: .It Fl f
72: A synonym for
73: .Xr whatis 1 .
74: This overrides any earlier
75: .Fl k
76: and
77: .Fl l
78: options.
1.54 schwarze 79: .Sm off
80: .It Fl I Cm os Li = Ar name
81: .Sm on
82: Override the default operating system
83: .Ar name
84: for the
85: .Xr mdoc 7
86: .Sq \&Os
87: macro.
1.62 ! schwarze 88: .It Fl h
! 89: Display only the SYNOPSIS lines.
! 90: Implies
! 91: .Fl a .
1.61 schwarze 92: .It Fl k
93: A synonym for
94: .Xr apropos 1 .
95: This overrides any earlier
96: .Fl f
97: and
98: .Fl l
99: options.
100: .It Fl l
101: A synonym for
102: .Fl a .
103: Also reverts any earlier
104: .Fl f
105: and
106: .Fl k
107: options.
1.1 kristaps 108: .It Fl m Ns Ar format
1.25 jmc 109: Input format.
110: See
1.1 kristaps 111: .Sx Input Formats
1.25 jmc 112: for available formats.
113: Defaults to
1.26 jmc 114: .Fl m Ns Cm andoc .
115: .It Fl O Ns Ar option
1.25 jmc 116: Comma-separated output options.
1.1 kristaps 117: .It Fl T Ns Ar output
1.25 jmc 118: Output format.
119: See
1.1 kristaps 120: .Sx Output Formats
1.25 jmc 121: for available formats.
122: Defaults to
1.26 jmc 123: .Fl T Ns Cm ascii .
1.4 schwarze 124: .It Fl V
125: Print version and exit.
1.38 schwarze 126: .It Fl W Ns Ar level
127: Specify the minimum message
128: .Ar level
129: to be reported on the standard error output and to affect the exit status.
130: The
131: .Ar level
132: can be
133: .Cm warning ,
134: .Cm error ,
135: or
136: .Cm fatal .
137: The default is
138: .Fl W Ns Cm fatal ;
1.26 jmc 139: .Fl W Ns Cm all
1.38 schwarze 140: is an alias for
141: .Fl W Ns Cm warning .
142: See
143: .Sx EXIT STATUS
144: and
145: .Sx DIAGNOSTICS
146: for details.
147: .Pp
148: The special option
149: .Fl W Ns Cm stop
150: tells
151: .Nm
152: to exit after parsing a file that causes warnings or errors of at least
153: the requested level.
154: No formatted output will be produced from that file.
155: If both a
156: .Ar level
157: and
158: .Cm stop
159: are requested, they can be joined with a comma, for example
160: .Fl W Ns Cm error , Ns Cm stop .
1.26 jmc 161: .It Ar file
162: Read input from zero or more files.
1.25 jmc 163: If unspecified, reads from stdin.
164: If multiple files are specified,
1.1 kristaps 165: .Nm
166: will halt with the first failed parse.
167: .El
1.61 schwarze 168: .Pp
169: In
170: .Fl f
171: and
172: .Fl k
173: mode,
174: .Nm
175: also supports the options
176: .Fl CMmOSsw
177: described in the
178: .Xr apropos 1
179: manual.
1.1 kristaps 180: .Ss Input Formats
181: The
182: .Nm
183: utility accepts
184: .Xr mdoc 7
185: and
186: .Xr man 7
187: input with
1.26 jmc 188: .Fl m Ns Cm doc
1.1 kristaps 189: and
1.26 jmc 190: .Fl m Ns Cm an ,
1.25 jmc 191: respectively.
192: The
1.1 kristaps 193: .Xr mdoc 7
194: format is
195: .Em strongly
1.10 schwarze 196: recommended;
1.1 kristaps 197: .Xr man 7
198: should only be used for legacy manuals.
199: .Pp
200: A third option,
1.26 jmc 201: .Fl m Ns Cm andoc ,
1.1 kristaps 202: which is also the default, determines encoding on-the-fly: if the first
1.10 schwarze 203: non-comment macro is
1.11 schwarze 204: .Sq \&Dd
1.1 kristaps 205: or
1.11 schwarze 206: .Sq \&Dt ,
1.10 schwarze 207: the
1.1 kristaps 208: .Xr mdoc 7
209: parser is used; otherwise, the
210: .Xr man 7
211: parser is used.
212: .Pp
213: If multiple
1.10 schwarze 214: files are specified with
1.26 jmc 215: .Fl m Ns Cm andoc ,
1.25 jmc 216: each has its file-type determined this way.
217: If multiple files are
1.1 kristaps 218: specified and
1.26 jmc 219: .Fl m Ns Cm doc
1.1 kristaps 220: or
1.26 jmc 221: .Fl m Ns Cm an
1.1 kristaps 222: is specified, then this format is used exclusively.
223: .Ss Output Formats
224: The
225: .Nm
226: utility accepts the following
227: .Fl T
1.34 schwarze 228: arguments, which correspond to output modes:
1.48 jmc 229: .Bl -tag -width "-Tlocale"
1.26 jmc 230: .It Fl T Ns Cm ascii
1.42 schwarze 231: Produce 7-bit ASCII output.
1.25 jmc 232: This is the default.
233: See
1.20 schwarze 234: .Sx ASCII Output .
1.26 jmc 235: .It Fl T Ns Cm html
1.42 schwarze 236: Produce strict CSS1/HTML-4.01 output.
1.25 jmc 237: See
1.20 schwarze 238: .Sx HTML Output .
1.26 jmc 239: .It Fl T Ns Cm lint
240: Parse only: produce no output.
241: Implies
1.38 schwarze 242: .Fl W Ns Cm warning .
1.48 jmc 243: .It Fl T Ns Cm locale
244: Encode output using the current locale.
245: See
246: .Sx Locale Output .
1.46 schwarze 247: .It Fl T Ns Cm man
1.49 schwarze 248: Produce
1.46 schwarze 249: .Xr man 7
1.49 schwarze 250: format output.
251: See
252: .Sx Man Output .
1.36 schwarze 253: .It Fl T Ns Cm pdf
254: Produce PDF output.
255: See
256: .Sx PDF Output .
1.31 schwarze 257: .It Fl T Ns Cm ps
258: Produce PostScript output.
259: See
260: .Sx PostScript Output .
1.26 jmc 261: .It Fl T Ns Cm tree
262: Produce an indented parse tree.
1.48 jmc 263: .It Fl T Ns Cm utf8
264: Encode output in the UTF\-8 multi-byte format.
265: See
266: .Sx UTF\-8 Output .
1.26 jmc 267: .It Fl T Ns Cm xhtml
1.42 schwarze 268: Produce strict CSS1/XHTML-1.0 output.
1.25 jmc 269: See
1.21 schwarze 270: .Sx XHTML Output .
1.1 kristaps 271: .El
272: .Pp
273: If multiple input files are specified, these will be processed by the
274: corresponding filter in-order.
1.34 schwarze 275: .Ss ASCII Output
276: Output produced by
277: .Fl T Ns Cm ascii ,
278: which is the default, is rendered in standard 7-bit ASCII documented in
279: .Xr ascii 7 .
280: .Pp
281: Font styles are applied by using back-spaced encoding such that an
282: underlined character
283: .Sq c
284: is rendered as
285: .Sq _ Ns \e[bs] Ns c ,
286: where
287: .Sq \e[bs]
288: is the back-space character number 8.
289: Emboldened characters are rendered as
290: .Sq c Ns \e[bs] Ns c .
291: .Pp
292: The special characters documented in
293: .Xr mandoc_char 7
294: are rendered best-effort in an ASCII equivalent.
1.44 schwarze 295: If no equivalent is found,
296: .Sq \&?
297: is used instead.
1.34 schwarze 298: .Pp
299: Output width is limited to 78 visible columns unless literal input lines
300: exceed this limit.
301: .Pp
302: The following
303: .Fl O
304: arguments are accepted:
1.5 schwarze 305: .Bl -tag -width Ds
1.51 schwarze 306: .It Cm indent Ns = Ns Ar indent
307: The left margin for normal text is set to
308: .Ar indent
309: blank characters instead of the default of five for
310: .Xr mdoc 7
311: and seven for
312: .Xr man 7 .
313: Increasing this is not recommended; it may result in degraded formatting,
1.52 jmc 314: for example overfull lines or ugly line breaks.
1.34 schwarze 315: .It Cm width Ns = Ns Ar width
316: The output width is set to
317: .Ar width ,
318: which will normalise to \(>=60.
1.1 kristaps 319: .El
1.34 schwarze 320: .Ss HTML Output
321: Output produced by
322: .Fl T Ns Cm html
323: conforms to HTML-4.01 strict.
324: .Pp
1.30 schwarze 325: The
1.34 schwarze 326: .Pa example.style.css
1.42 schwarze 327: file documents style-sheet classes available for customising output.
328: If a style-sheet is not specified with
329: .Fl O Ns Ar style ,
330: .Fl T Ns Cm html
331: defaults to simple output readable in any graphical or text-based web
332: browser.
1.34 schwarze 333: .Pp
1.45 schwarze 334: Special characters are rendered in decimal-encoded UTF\-8.
1.34 schwarze 335: .Pp
336: The following
1.33 schwarze 337: .Fl O
1.34 schwarze 338: arguments are accepted:
1.17 schwarze 339: .Bl -tag -width Ds
1.49 schwarze 340: .It Cm fragment
1.50 schwarze 341: Omit the
342: .Aq !DOCTYPE
343: declaration and the
344: .Aq html ,
345: .Aq head ,
346: and
347: .Aq body
348: elements and only emit the subtree below the
349: .Aq body
350: element.
1.49 schwarze 351: The
352: .Cm style
1.50 schwarze 353: argument will be ignored.
1.49 schwarze 354: This is useful when embedding manual content within existing documents.
1.33 schwarze 355: .It Cm includes Ns = Ns Ar fmt
1.17 schwarze 356: The string
357: .Ar fmt ,
1.21 schwarze 358: for example,
1.17 schwarze 359: .Ar ../src/%I.html ,
360: is used as a template for linked header files (usually via the
361: .Sq \&In
1.25 jmc 362: macro).
363: Instances of
1.17 schwarze 364: .Sq \&%I
1.25 jmc 365: are replaced with the include filename.
366: The default is not to present a
1.17 schwarze 367: hyperlink.
1.33 schwarze 368: .It Cm man Ns = Ns Ar fmt
1.17 schwarze 369: The string
370: .Ar fmt ,
1.21 schwarze 371: for example,
1.17 schwarze 372: .Ar ../html%S/%N.%S.html ,
373: is used as a template for linked manuals (usually via the
374: .Sq \&Xr
1.25 jmc 375: macro).
376: Instances of
1.17 schwarze 377: .Sq \&%N
378: and
379: .Sq %S
380: are replaced with the linked manual's name and section, respectively.
1.25 jmc 381: If no section is included, section 1 is assumed.
382: The default is not to
1.17 schwarze 383: present a hyperlink.
1.33 schwarze 384: .It Cm style Ns = Ns Ar style.css
1.26 jmc 385: The file
386: .Ar style.css
387: is used for an external style-sheet.
388: This must be a valid absolute or
389: relative URI.
1.30 schwarze 390: .El
1.48 jmc 391: .Ss Locale Output
392: Locale-depending output encoding is triggered with
393: .Fl T Ns Cm locale .
394: This option is not available on all systems: systems without locale
395: support, or those whose internal representation is not natively UCS-4,
396: will fall back to
397: .Fl T Ns Cm ascii .
398: See
399: .Sx ASCII Output
400: for font style specification and available command-line arguments.
1.49 schwarze 401: .Ss Man Output
402: Translate input format into
403: .Xr man 7
404: output format.
1.55 jmc 405: This is useful for distributing manual sources to legacy systems
1.49 schwarze 406: lacking
407: .Xr mdoc 7
408: formatters.
409: .Pp
410: If
411: .Xr mdoc 7
412: is passed as input, it is translated into
1.50 schwarze 413: .Xr man 7 .
414: If the input format is
1.49 schwarze 415: .Xr man 7 ,
1.50 schwarze 416: the input is copied to the output, expanding any
1.49 schwarze 417: .Xr roff 7
418: .Sq so
1.50 schwarze 419: requests.
420: The parser is also run, and as usual, the
421: .Fl W
422: level controls which
423: .Sx DIAGNOSTICS
424: are displayed before copying the input to the output.
1.48 jmc 425: .Ss PDF Output
426: PDF-1.1 output may be generated by
427: .Fl T Ns Cm pdf .
428: See
429: .Sx PostScript Output
430: for
431: .Fl O
432: arguments and defaults.
1.31 schwarze 433: .Ss PostScript Output
1.33 schwarze 434: PostScript
435: .Qq Adobe-3.0
436: Level-2 pages may be generated by
1.31 schwarze 437: .Fl T Ns Cm ps .
1.35 schwarze 438: Output pages default to letter sized and are rendered in the Times font
439: family, 11-point.
440: Margins are calculated as 1/9 the page length and width.
441: Line-height is 1.4m.
1.34 schwarze 442: .Pp
443: Special characters are rendered as in
444: .Sx ASCII Output .
445: .Pp
446: The following
447: .Fl O
448: arguments are accepted:
449: .Bl -tag -width Ds
450: .It Cm paper Ns = Ns Ar name
451: The paper size
452: .Ar name
453: may be one of
1.35 schwarze 454: .Ar a3 ,
455: .Ar a4 ,
456: .Ar a5 ,
457: .Ar legal ,
1.34 schwarze 458: or
459: .Ar letter .
1.35 schwarze 460: You may also manually specify dimensions as
461: .Ar NNxNN ,
462: width by height in millimetres.
463: If an unknown value is encountered,
464: .Ar letter
465: is used.
1.34 schwarze 466: .El
1.48 jmc 467: .Ss UTF\-8 Output
468: Use
469: .Fl T Ns Cm utf8
470: to force a UTF\-8 locale.
1.36 schwarze 471: See
1.48 jmc 472: .Sx Locale Output
473: for details and options.
1.21 schwarze 474: .Ss XHTML Output
475: Output produced by
1.26 jmc 476: .Fl T Ns Cm xhtml
1.21 schwarze 477: conforms to XHTML-1.0 strict.
478: .Pp
479: See
480: .Sx HTML Output
481: for details; beyond generating XHTML tags instead of HTML tags, these
482: output modes are identical.
1.60 schwarze 483: .Sh ENVIRONMENT
484: .Bl -tag -width MANPAGER
485: .It Ev MANPAGER
486: Any non-empty value of the environment variable
487: .Ev MANPAGER
488: will be used instead of the standard pagination program,
489: .Xr more 1 .
490: .It Ev PAGER
491: Specifies the pagination program to use when
492: .Ev MANPAGER
493: is not defined.
494: If neither PAGER nor MANPAGER is defined,
495: .Pa /usr/bin/more Fl s
496: will be used.
497: .El
1.38 schwarze 498: .Sh EXIT STATUS
499: The
500: .Nm
501: utility exits with one of the following values, controlled by the message
502: .Ar level
503: associated with the
504: .Fl W
505: option:
506: .Pp
507: .Bl -tag -width Ds -compact
508: .It 0
509: No warnings or errors occurred, or those that did were ignored because
510: they were lower than the requested
511: .Ar level .
512: .It 2
513: At least one warning occurred, but no error, and
514: .Fl W Ns Cm warning
515: was specified.
516: .It 3
517: At least one parsing error occurred, but no fatal error, and
518: .Fl W Ns Cm error
519: or
520: .Fl W Ns Cm warning
521: was specified.
522: .It 4
523: A fatal parsing error occurred.
524: .It 5
525: Invalid command line arguments were specified.
526: No input files have been read.
527: .It 6
528: An operating system error occurred, for example memory exhaustion or an
529: error accessing input files.
530: Such errors cause
531: .Nm
532: to exit at once, possibly in the middle of parsing or formatting a file.
533: .El
534: .Pp
535: Note that selecting
536: .Fl T Ns Cm lint
537: output mode implies
538: .Fl W Ns Cm warning .
1.1 kristaps 539: .Sh EXAMPLES
540: To page manuals to the terminal:
541: .Pp
1.42 schwarze 542: .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
543: .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.12 schwarze 544: .Pp
1.17 schwarze 545: To produce HTML manuals with
546: .Ar style.css
547: as the style-sheet:
548: .Pp
1.42 schwarze 549: .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
1.17 schwarze 550: .Pp
1.12 schwarze 551: To check over a large set of manuals:
552: .Pp
1.38 schwarze 553: .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
1.34 schwarze 554: .Pp
555: To produce a series of PostScript manuals for A4 paper:
556: .Pp
1.42 schwarze 557: .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
1.46 schwarze 558: .Pp
559: Convert a modern
560: .Xr mdoc 7
561: manual to the older
562: .Xr man 7
563: format, for use on systems lacking an
564: .Xr mdoc 7
565: parser:
566: .Pp
567: .Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man
1.38 schwarze 568: .Sh DIAGNOSTICS
1.59 schwarze 569: Messages displayed by
570: .Nm
571: follow this format:
1.38 schwarze 572: .Pp
1.59 schwarze 573: .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
1.38 schwarze 574: .Pp
1.59 schwarze 575: Line and column numbers start at 1.
576: Both are omitted for messages referring to an input file as a whole.
577: Macro names and arguments are omitted where meaningless.
578: Fatal messages about invalid command line arguments
579: or operating system errors, for example when memory is exhausted,
580: may also omit the
581: .Ar file
1.57 schwarze 582: and
1.59 schwarze 583: .Ar level
584: fields.
1.57 schwarze 585: .Pp
1.38 schwarze 586: Message levels have the following meanings:
587: .Bl -tag -width "warning"
1.58 schwarze 588: .It Cm syserr
589: Opening or reading an input file failed, so the parser cannot
590: even be started and no output is produced from that input file.
1.38 schwarze 591: .It Cm fatal
592: The parser is unable to parse a given input file at all.
593: No formatted output is produced from that input file.
594: .It Cm error
595: An input file contains syntax that cannot be safely interpreted,
596: either because it is invalid or because
597: .Nm
598: does not implement it yet.
599: By discarding part of the input or inserting missing tokens,
600: the parser is able to continue, and the error does not prevent
601: generation of formatted output, but typically, preparing that
602: output involves information loss, broken document structure
603: or unintended formatting.
604: .It Cm warning
605: An input file uses obsolete, discouraged or non-portable syntax.
606: All the same, the meaning of the input is unambiguous and a correct
607: rendering can be produced.
608: Documents causing warnings may render poorly when using other
609: formatting tools instead of
610: .Nm .
611: .El
612: .Pp
613: Messages of the
614: .Cm warning
615: and
616: .Cm error
617: levels are hidden unless their level, or a lower level, is requested using a
618: .Fl W
619: option or
620: .Fl T Ns Cm lint
621: output mode.
1.6 schwarze 622: .Sh COMPATIBILITY
1.10 schwarze 623: This section summarises
1.6 schwarze 624: .Nm
1.39 schwarze 625: compatibility with GNU troff.
1.14 schwarze 626: Each input and output format is separately noted.
1.20 schwarze 627: .Ss ASCII Compatibility
1.6 schwarze 628: .Bl -bullet -compact
1.13 schwarze 629: .It
1.44 schwarze 630: Unrenderable unicode codepoints specified with
631: .Sq \e[uNNNN]
632: escapes are printed as
633: .Sq \&?
634: in mandoc.
635: In GNU troff, these raise an error.
636: .It
1.21 schwarze 637: The
1.14 schwarze 638: .Sq \&Bd \-literal
1.21 schwarze 639: and
1.14 schwarze 640: .Sq \&Bd \-unfilled
641: macros of
642: .Xr mdoc 7
643: in
1.26 jmc 644: .Fl T Ns Cm ascii
1.14 schwarze 645: are synonyms, as are \-filled and \-ragged.
646: .It
1.44 schwarze 647: In historic GNU troff, the
1.14 schwarze 648: .Sq \&Pa
649: .Xr mdoc 7
650: macro does not underline when scoped under an
651: .Sq \&It
1.25 jmc 652: in the FILES section.
653: This behaves correctly in
1.14 schwarze 654: .Nm .
1.10 schwarze 655: .It
1.26 jmc 656: A list or display following the
1.11 schwarze 657: .Sq \&Ss
1.14 schwarze 658: .Xr mdoc 7
659: macro in
1.26 jmc 660: .Fl T Ns Cm ascii
1.6 schwarze 661: does not assert a prior vertical break, just as it doesn't with
1.11 schwarze 662: .Sq \&Sh .
1.6 schwarze 663: .It
1.14 schwarze 664: The
665: .Sq \&na
666: .Xr man 7
1.16 schwarze 667: macro in
1.26 jmc 668: .Fl T Ns Cm ascii
1.16 schwarze 669: has no effect.
1.6 schwarze 670: .It
671: Words aren't hyphenated.
672: .El
1.21 schwarze 673: .Ss HTML/XHTML Compatibility
1.17 schwarze 674: .Bl -bullet -compact
675: .It
676: The
1.20 schwarze 677: .Sq \efP
678: escape will revert the font to the previous
679: .Sq \ef
680: escape, not to the last rendered decoration, which is now dictated by
1.25 jmc 681: CSS instead of hard-coded.
682: It also will not span past the current scope,
683: for the same reason.
684: Note that in
1.20 schwarze 685: .Sx ASCII Output
686: mode, this will work fine.
687: .It
688: The
1.17 schwarze 689: .Xr mdoc 7
690: .Sq \&Bl \-hang
691: and
692: .Sq \&Bl \-tag
693: list types render similarly (no break following overreached left-hand
694: side) due to the expressive constraints of HTML.
695: .It
696: The
697: .Xr man 7
698: .Sq IP
699: and
700: .Sq TP
701: lists render similarly.
702: .El
1.1 kristaps 703: .Sh SEE ALSO
1.47 schwarze 704: .Xr eqn 7 ,
1.25 jmc 705: .Xr man 7 ,
1.1 kristaps 706: .Xr mandoc_char 7 ,
1.43 schwarze 707: .Xr mdoc 7 ,
708: .Xr roff 7 ,
709: .Xr tbl 7
1.1 kristaps 710: .Sh AUTHORS
711: The
712: .Nm
1.10 schwarze 713: utility was written by
1.56 schwarze 714: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.17 schwarze 715: .Sh CAVEATS
716: In
1.26 jmc 717: .Fl T Ns Cm html
1.21 schwarze 718: and
1.26 jmc 719: .Fl T Ns Cm xhtml ,
1.17 schwarze 720: the maximum size of an element attribute is determined by
721: .Dv BUFSIZ ,
1.25 jmc 722: which is usually 1024 bytes.
723: Be aware of this when setting long link
1.26 jmc 724: formats such as
725: .Fl O Ns Cm style Ns = Ns Ar really/long/link .
1.22 schwarze 726: .Pp
727: Nesting elements within next-line element scopes of
1.26 jmc 728: .Fl m Ns Cm an ,
1.22 schwarze 729: such as
730: .Sq br
731: within an empty
732: .Sq B ,
733: will confuse
1.26 jmc 734: .Fl T Ns Cm html
1.22 schwarze 735: and
1.26 jmc 736: .Fl T Ns Cm xhtml
1.23 schwarze 737: and cause them to forget the formatting of the prior next-line scope.
738: .Pp
1.24 schwarze 739: The
740: .Sq \(aq
741: control character is an alias for the standard macro control character
742: and does not emit a line-break as stipulated in GNU troff.
![[BACK]](/icons/back.gif){kind=icon}
Return to mandoc.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / mandoc