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