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