1 .\" $Id: mandoc.1,v 1.217 2017/07/20 15:26:41 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
5 .\"
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
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.
17 .\"
18 .Dd $Mdocdate: July 20 2017 $
19 .Dt MANDOC 1
20 .Os
21 .Sh NAME
22 .Nm mandoc
23 .Nd format manual pages
24 .Sh SYNOPSIS
25 .Nm mandoc
26 .Op Fl ac
27 .Op Fl I Cm os Ns = Ns Ar name
28 .Op Fl K Ar encoding
29 .Op Fl mdoc | man
30 .Op Fl O Ar options
31 .Op Fl T Ar output
32 .Op Fl W Ar level
33 .Op Ar
34 .Sh DESCRIPTION
35 The
36 .Nm
37 utility formats
38 .Ux
39 manual pages for display.
40 .Pp
41 By default,
42 .Nm
43 reads
44 .Xr mdoc 5
45 or
46 .Xr man 5
47 text from stdin and produces
48 .Fl T Cm locale
49 output.
50 .Pp
51 The options are as follows:
52 .Bl -tag -width Ds
53 .It Fl a
54 If the standard output is a terminal device and
55 .Fl c
56 is not specified, use
57 .Xr more 1
58 to paginate the output, just like
59 .Xr man 1
101 then input is interpreted according to
102 .Ar encoding .
103 .It
104 If the first non-ASCII byte in the file introduces a valid UTF-8
105 sequence, input is interpreted as
106 .Cm utf-8 .
107 .It
108 Otherwise, input is interpreted as
109 .Cm iso-8859-1 .
110 .El
111 .It Fl mdoc | man
112 With
113 .Fl mdoc ,
114 all input files are interpreted as
115 .Xr mdoc 5 .
116 With
117 .Fl man ,
118 all input files are interpreted as
119 .Xr man 5 .
120 By default, the input language is automatically detected for each file:
121 if the the first macro is
122 .Ic \&Dd
123 or
124 .Ic \&Dt ,
125 the
126 .Xr mdoc 5
127 parser is used; otherwise, the
128 .Xr man 5
129 parser is used.
130 With other arguments,
131 .Fl m
132 is silently ignored.
133 .It Fl O Ar options
134 Comma-separated output options.
135 .It Fl T Ar output
136 Output format.
137 See
138 .Sx Output Formats
139 for available formats.
140 Defaults to
141 .Fl T Cm locale .
142 .It Fl W Ar level
143 Specify the minimum message
144 .Ar level
145 to be reported on the standard error output and to affect the exit status.
146 The
147 .Ar level
148 can be
149 .Cm base ,
150 .Cm style ,
151 .Cm warning ,
152 .Cm error ,
153 or
154 .Cm unsupp .
155 The
156 .Cm base
157 level automatically derives the operating system from the contents of the
158 .Ic \&Os
159 macro, from the
160 .Fl Ios
161 command line option, or from the
179 See
180 .Sx EXIT STATUS
181 and
182 .Sx DIAGNOSTICS
183 for details.
184 .Pp
185 The special option
186 .Fl W Cm stop
187 tells
188 .Nm
189 to exit after parsing a file that causes warnings or errors of at least
190 the requested level.
191 No formatted output will be produced from that file.
192 If both a
193 .Ar level
194 and
195 .Cm stop
196 are requested, they can be joined with a comma, for example
197 .Fl W Cm error , Ns Cm stop .
198 .It Ar file
199 Read input from zero or more files.
200 If unspecified, reads from stdin.
201 If multiple files are specified,
202 .Nm
203 will halt with the first failed parse.
204 .El
205 .Ss Output Formats
206 The
207 .Nm
208 utility accepts the following
209 .Fl T
210 arguments, which correspond to output modes:
211 .Bl -tag -width "-T markdown"
212 .It Fl T Cm ascii
213 Produce 7-bit ASCII output.
214 See
215 .Sx ASCII Output .
216 .It Fl T Cm html
217 Produce HTML5, CSS1, and MathML output.
218 See
219 .Sx HTML Output .
220 .It Fl T Ns Cm lint
221 Parse only: produce no output.
222 Implies
223 .Fl W Cm all
224 and redirects parser messages, which usually appear
225 on standard error output, to standard output.
226 .It Fl T Cm locale
227 Encode output using the current locale.
228 This is the default.
229 See
230 .Sx Locale Output .
231 .It Fl T Cm man
232 Produce
233 .Xr man 5
234 format output.
235 See
236 .Sx Man Output .
237 .It Fl T Cm markdown
238 Produce output in
239 .Sy markdown
240 format.
241 See
242 .Sx Markdown Output .
243 .It Fl T Cm pdf
244 Produce PDF output.
245 See
246 .Sx PDF Output .
247 .It Fl T Cm ps
248 Produce PostScript output.
249 See
250 .Sx PostScript Output .
251 .It Fl T Cm tree
252 Produce an indented parse tree.
253 .It Fl T Cm utf8
254 Encode output in the UTF\-8 multi-byte format.
255 See
256 .Sx UTF\-8 Output .
257 .El
258 .Pp
259 If multiple input files are specified, these will be processed by the
260 corresponding filter in-order.
261 .Ss ASCII Output
262 Output produced by
263 .Fl T Cm ascii
264 is rendered in standard 7-bit ASCII documented in
265 .Xr ascii 5 .
266 .Pp
267 Font styles are applied by using back-spaced encoding such that an
268 underlined character
269 .Sq c
270 is rendered as
271 .Sq _ Ns \e[bs] Ns c ,
272 where
273 .Sq \e[bs]
274 is the back-space character number 8.
275 Emboldened characters are rendered as
276 .Sq c Ns \e[bs] Ns c .
277 .Pp
278 The special characters documented in
279 .Xr mandoc_char 5
280 are rendered best-effort in an ASCII equivalent.
281 .Pp
282 Output width is limited to 78 visible columns unless literal input lines
283 exceed this limit.
284 .Pp
285 The following
286 .Fl O
287 arguments are accepted:
288 .Bl -tag -width Ds
289 .It Cm indent Ns = Ns Ar indent
290 The left margin for normal text is set to
291 .Ar indent
292 blank characters instead of the default of five for
293 .Xr mdoc 5
294 and seven for
295 .Xr man 5 .
296 Increasing this is not recommended; it may result in degraded formatting,
297 for example overfull lines or ugly line breaks.
298 .It Cm width Ns = Ns Ar width
299 The output width is set to
300 .Ar width .
301 .El
302 .Ss HTML Output
303 Output produced by
304 .Fl T Cm html
305 conforms to HTML5 using optional self-closing tags.
306 Default styles use only CSS1.
307 Equations rendered from
308 .Xr eqn 5
309 blocks use MathML.
310 .Pp
311 The
312 .Pa mandoc.css
313 file documents style-sheet classes available for customising output.
314 If a style-sheet is not specified with
315 .Fl O Cm style ,
316 .Fl T Cm html
317 defaults to simple output (via an embedded style-sheet)
318 readable in any graphical or text-based web
319 browser.
320 .Pp
321 Special characters are rendered in decimal-encoded UTF\-8.
322 .Pp
323 The following
324 .Fl O
325 arguments are accepted:
326 .Bl -tag -width Ds
327 .It Cm fragment
328 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
329 elements and only emit the subtree below the <body> element.
330 The
331 .Cm style
332 argument will be ignored.
333 This is useful when embedding manual content within existing documents.
334 .It Cm includes Ns = Ns Ar fmt
335 The string
336 .Ar fmt ,
337 for example,
338 .Ar ../src/%I.html ,
339 is used as a template for linked header files (usually via the
340 .Ic \&In
341 macro).
351 .Ar ../html%S/%N.%S.html ,
352 is used as a template for linked manuals (usually via the
353 .Ic \&Xr
354 macro).
355 Instances of
356 .Sq \&%N
357 and
358 .Sq %S
359 are replaced with the linked manual's name and section, respectively.
360 If no section is included, section 1 is assumed.
361 The default is not to
362 present a hyperlink.
363 .It Cm style Ns = Ns Ar style.css
364 The file
365 .Ar style.css
366 is used for an external style-sheet.
367 This must be a valid absolute or
368 relative URI.
369 .El
370 .Ss Locale Output
371 Locale-depending output encoding is triggered with
372 .Fl T Cm locale .
373 This is the default.
374 .Ss Man Output
375 Translate input format into
376 .Xr man 5
377 output format.
378 This is useful for distributing manual sources to legacy systems
379 lacking
380 .Xr mdoc 5
381 formatters.
382 .Pp
383 If
384 .Xr mdoc 5
385 is passed as input, it is translated into
386 .Xr man 5 .
387 If the input format is
388 .Xr man 5 ,
389 the input is copied to the output, expanding any
390 .Xr mandoc_roff 5
391 .Ic so
392 requests.
393 The parser is also run, and as usual, the
394 .Fl W
395 level controls which
396 .Sx DIAGNOSTICS
397 are displayed before copying the input to the output.
398 .Ss Markdown Output
399 Translate
400 .Xr mdoc 5
401 input to the
402 .Sy markdown
403 format conforming to
404 .Lk http://daringfireball.net/projects/markdown/syntax.text\
405 "John Gruber's 2004 specification" .
406 The output also almost conforms to the
407 .Lk http://commonmark.org/ CommonMark
408 specification.
409 .Pp
410 The character set used for the markdown output is ASCII.
411 Non-ASCII characters are encoded as HTML entities.
412 Since that is not possible in literal font contexts, because these
413 are rendered as code spans and code blocks in the markdown output,
414 non-ASCII characters are transliterated to ASCII approximations in
415 these contexts.
416 .Pp
417 Markdown is a very weak markup language, so all semantic markup is
418 lost, and even part of the presentational markup may be lost.
419 Do not use this as an intermediate step in converting to HTML;
420 instead, use
421 .Fl T Cm html
422 directly.
423 .Pp
454 .Fl O
455 arguments are accepted:
456 .Bl -tag -width Ds
457 .It Cm paper Ns = Ns Ar name
458 The paper size
459 .Ar name
460 may be one of
461 .Ar a3 ,
462 .Ar a4 ,
463 .Ar a5 ,
464 .Ar legal ,
465 or
466 .Ar letter .
467 You may also manually specify dimensions as
468 .Ar NNxNN ,
469 width by height in millimetres.
470 If an unknown value is encountered,
471 .Ar letter
472 is used.
473 .El
474 .Ss UTF\-8 Output
475 Use
476 .Fl T Cm utf8
477 to force a UTF\-8 locale.
478 See
479 .Sx Locale Output
480 for details and options.
481 .Ss Syntax tree output
482 Use
483 .Fl T Cm tree
484 to show a human readable representation of the syntax tree.
485 It is useful for debugging the source code of manual pages.
486 The exact format is subject to change, so don't write parsers for it.
487 .Pp
488 The first paragraph shows meta data found in the
489 .Xr mdoc 5
490 prologue, on the
491 .Xr man 5
492 .Ic \&TH
493 line, or the fallbacks used.
494 .Pp
495 In the tree dump, each output line shows one syntax tree node.
496 Child nodes are indented with respect to their parent node.
497 The columns are:
498 .Pp
499 .Bl -enum -compact
500 .It
527 BROKEN if the node is a block broken by another block.
528 .It
529 NOSRC if the node is not in the input file,
530 but automatically generated from macros.
531 .It
532 NOPRT if the node is not supposed to generate output
533 for any output format.
534 .El
535 .El
536 .Pp
537 The following
538 .Fl O
539 argument is accepted:
540 .Bl -tag -width Ds
541 .It Cm noval
542 Skip validation and show the unvalidated syntax tree.
543 This can help to find out whether a given behaviour is caused by
544 the parser or by the validator.
545 Meta data is not available in this case.
546 .El
547 .Sh EXIT STATUS
548 The
549 .Nm
550 utility exits with one of the following values, controlled by the message
551 .Ar level
552 associated with the
553 .Fl W
554 option:
555 .Pp
556 .Bl -tag -width Ds -compact
557 .It 0
558 No base system convention violations, style suggestions, warnings,
559 or errors occurred, or those that did were ignored because they
560 were lower than the requested
561 .Ar level .
562 .It 1
563 At least one base system convention violation or style suggestion
564 occurred, but no warning or error, and
565 .Fl W Cm base
566 or
667 Indicates a risk of information loss or severe misformatting,
668 in most cases caused by serious syntax errors.
669 .It Cm warning
670 Indicates a risk that the information shown or its formatting
671 may mismatch the author's intent in minor ways.
672 Additionally, syntax errors are classified at least as warnings,
673 even if they do not usually cause misformatting.
674 .It Cm style
675 An input file uses dubious or discouraged style.
676 This is not a complaint about the syntax, and probably neither
677 formatting nor portability are in danger.
678 While great care is taken to avoid false positives on the higher
679 message levels, the
680 .Cm style
681 level tries to reduce the probability that issues go unnoticed,
682 so it may occasionally issue bogus suggestions.
683 Please use your good judgement to decide whether any particular
684 .Cm style
685 suggestion really justifies a change to the input file.
686 .It Cm base
687 A convertion used in the base system of a specific operating system
688 is not adhered to.
689 These are not markup mistakes, and neither the quality of formatting
690 nor portability are in danger.
691 Messages of the
692 .Cm base
693 level are printed with the more intuitive
694 .Cm style
695 .Ar level
696 tag.
697 .El
698 .Pp
699 Messages of the
700 .Cm base ,
701 .Cm style ,
702 .Cm warning ,
703 .Cm error ,
704 and
705 .Cm unsupp
706 levels except those about non-existent or unreadable input files
707 are hidden unless their level, or a lower level, is requested using a
775 macro references a manual page that is not found in the base system.
776 The path to look for base system manuals is configurable at compile
777 time and defaults to
778 .Pa /usr/share/man : /usr/X11R6/man .
779 .El
780 .Ss Style suggestions
781 .Bl -ohang
782 .It Sy "legacy man(7) date format"
783 .Pq mdoc
784 The
785 .Ic \&Dd
786 macro uses the legacy
787 .Xr man 5
788 date format
789 .Dq yyyy-dd-mm .
790 Consider using the conventional
791 .Xr mdoc 5
792 date format
793 .Dq "Month dd, yyyy"
794 instead.
795 .It Sy "lower case character in document title"
796 .Pq mdoc , man
797 The title is still used as given in the
798 .Ic \&Dt
799 or
800 .Ic \&TH
801 macro.
802 .It Sy "duplicate RCS id"
803 A single manual page contains two copies of the RCS identifier for
804 the same operating system.
805 Consider deleting the later instance and moving the first one up
806 to the top of the page.
807 .It Sy "typo in section name"
808 .Pq mdoc
809 Fuzzy string matching revealed that the argument of an
810 .Ic \&Sh
811 macro is similar, but not identical to a standard section name.
812 .It Sy "unterminated quoted argument"
813 .Pq roff
814 Macro arguments can be enclosed in double quote characters
815 such that space characters and macro names contained in the quoted
816 argument need not be escaped.
817 The closing quote of the last argument of a macro can be omitted.
818 However, omitting it is not recommended because it makes the code
819 harder to read.
820 .It Sy "useless macro"
821 .Pq mdoc
822 A
823 .Ic \&Bt ,
824 .Ic \&Tn ,
825 or
826 .Ic \&Ud
827 macro was found.
864 .It Sy "no blank before trailing delimiter"
865 .Pq mdoc
866 The last argument of a macro that supports trailing delimiter
867 arguments is longer than one byte and ends with a trailing delimiter.
868 Consider inserting a blank such that the delimiter becomes a separate
869 argument, thus moving it out of the scope of the macro.
870 .It Sy "fill mode already enabled, skipping"
871 .Pq man
872 A
873 .Ic \&fi
874 request occurs even though the document is still in fill mode,
875 or already switched back to fill mode.
876 It has no effect.
877 .It Sy "fill mode already disabled, skipping"
878 .Pq man
879 An
880 .Ic \&nf
881 request occurs even though the document already switched to no-fill mode
882 and did not switch back to fill mode yet.
883 It has no effect.
884 .It Sy "function name without markup"
885 .Pq mdoc
886 A word followed by an empty pair of parentheses occurs on a text line.
887 Consider using an
888 .Ic \&Fn
889 or
890 .Ic \&Xr
891 macro.
892 .It Sy "whitespace at end of input line"
893 .Pq mdoc , man , roff
894 Whitespace at the end of input lines is almost never semantically
895 significant \(em but in the odd case where it might be, it is
896 extremely confusing when reviewing and maintaining documents.
897 .It Sy "bad comment style"
898 .Pq roff
899 Comment lines start with a dot, a backslash, and a double-quote character.
900 The
901 .Nm
902 utility treats the line as a comment line even without the backslash,
903 but leaving out the backslash might not be portable.
|
1 .\" $Id: mandoc.1,v 1.226 2018/07/28 18:34:15 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2012, 2014-2018 Ingo Schwarze <schwarze@openbsd.org>
5 .\"
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
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.
17 .\"
18 .Dd $Mdocdate: July 28 2018 $
19 .Dt MANDOC 1
20 .Os
21 .Sh NAME
22 .Nm mandoc
23 .Nd format manual pages
24 .Sh SYNOPSIS
25 .Nm mandoc
26 .Op Fl ac
27 .Op Fl I Cm os Ns = Ns Ar name
28 .Op Fl K Ar encoding
29 .Op Fl mdoc | man
30 .Op Fl O Ar options
31 .Op Fl T Ar output
32 .Op Fl W Ar level
33 .Op Ar
34 .Sh DESCRIPTION
35 The
36 .Nm
37 utility formats manual pages for display.
38 .Pp
39 By default,
40 .Nm
41 reads
42 .Xr mdoc 5
43 or
44 .Xr man 5
45 text from stdin and produces
46 .Fl T Cm locale
47 output.
48 .Pp
49 The options are as follows:
50 .Bl -tag -width Ds
51 .It Fl a
52 If the standard output is a terminal device and
53 .Fl c
54 is not specified, use
55 .Xr more 1
56 to paginate the output, just like
57 .Xr man 1
99 then input is interpreted according to
100 .Ar encoding .
101 .It
102 If the first non-ASCII byte in the file introduces a valid UTF-8
103 sequence, input is interpreted as
104 .Cm utf-8 .
105 .It
106 Otherwise, input is interpreted as
107 .Cm iso-8859-1 .
108 .El
109 .It Fl mdoc | man
110 With
111 .Fl mdoc ,
112 all input files are interpreted as
113 .Xr mdoc 5 .
114 With
115 .Fl man ,
116 all input files are interpreted as
117 .Xr man 5 .
118 By default, the input language is automatically detected for each file:
119 if the first macro is
120 .Ic \&Dd
121 or
122 .Ic \&Dt ,
123 the
124 .Xr mdoc 5
125 parser is used; otherwise, the
126 .Xr man 5
127 parser is used.
128 With other arguments,
129 .Fl m
130 is silently ignored.
131 .It Fl O Ar options
132 Comma-separated output options.
133 See the descriptions of the individual output formats for supported
134 .Ar options .
135 .It Fl T Ar output
136 Select the output format.
137 Supported values for the
138 .Ar output
139 argument are
140 .Cm ascii ,
141 .Cm html ,
142 the default of
143 .Cm locale ,
144 .Cm man ,
145 .Cm markdown ,
146 .Cm pdf ,
147 .Cm ps ,
148 .Cm tree ,
149 and
150 .Cm utf8 .
151 .Pp
152 The special
153 .Fl T Cm lint
154 mode only parses the input and produces no output.
155 It implies
156 .Fl W Cm all
157 and redirects parser messages, which usually appear on standard
158 error output, to standard output.
159 .It Fl W Ar level
160 Specify the minimum message
161 .Ar level
162 to be reported on the standard error output and to affect the exit status.
163 The
164 .Ar level
165 can be
166 .Cm base ,
167 .Cm style ,
168 .Cm warning ,
169 .Cm error ,
170 or
171 .Cm unsupp .
172 The
173 .Cm base
174 level automatically derives the operating system from the contents of the
175 .Ic \&Os
176 macro, from the
177 .Fl Ios
178 command line option, or from the
196 See
197 .Sx EXIT STATUS
198 and
199 .Sx DIAGNOSTICS
200 for details.
201 .Pp
202 The special option
203 .Fl W Cm stop
204 tells
205 .Nm
206 to exit after parsing a file that causes warnings or errors of at least
207 the requested level.
208 No formatted output will be produced from that file.
209 If both a
210 .Ar level
211 and
212 .Cm stop
213 are requested, they can be joined with a comma, for example
214 .Fl W Cm error , Ns Cm stop .
215 .It Ar file
216 Read from the given input file.
217 If multiple files are specified, they are processed in the given order.
218 If unspecified,
219 .Nm
220 reads from standard input.
221 .El
222 .Ss ASCII Output
223 Use
224 .Fl T Cm ascii
225 to force text output in 7-bit ASCII character encoding documented in the
226 .Xr ascii 5
227 manual page, ignoring the
228 .Xr locale 1
229 set in the environment.
230 .Pp
231 Font styles are applied by using back-spaced encoding such that an
232 underlined character
233 .Sq c
234 is rendered as
235 .Sq _ Ns \e[bs] Ns c ,
236 where
237 .Sq \e[bs]
238 is the back-space character number 8.
239 Emboldened characters are rendered as
240 .Sq c Ns \e[bs] Ns c .
241 .Pp
242 The special characters documented in
243 .Xr mandoc_char 5
244 are rendered best-effort in an ASCII equivalent.
245 .Pp
246 The following
247 .Fl O
248 arguments are accepted:
249 .Bl -tag -width Ds
250 .It Cm indent Ns = Ns Ar indent
251 The left margin for normal text is set to
252 .Ar indent
253 blank characters instead of the default of five for
254 .Xr mdoc 5
255 and seven for
256 .Xr man 5 .
257 Increasing this is not recommended; it may result in degraded formatting,
258 for example overfull lines or ugly line breaks.
259 When output is to a pager on a terminal that is less than 66 columns
260 wide, the default is reduced to three columns.
261 .It Cm mdoc
262 Format
263 .Xr man 5
264 input files in
265 .Xr mdoc 5
266 output style.
267 Specifically, this suppresses the two additional blank lines near the
268 top and the bottom of each page, and it implies
269 .Fl O Cm indent Ns =5 .
270 One useful application is for checking that
271 .Fl T Cm man
272 output formats in the same way as the
273 .Xr mdoc 5
274 source it was generated from.
275 .It Cm width Ns = Ns Ar width
276 The output width is set to
277 .Ar width
278 instead of the default of 78.
279 When output is to a pager on a terminal that is less than 79 columns
280 wide, the default is reduced to one less than the terminal width.
281 In any case, lines that are output in literal mode are never wrapped
282 and may exceed the output width.
283 .El
284 .Ss HTML Output
285 Output produced by
286 .Fl T Cm html
287 conforms to HTML5 using optional self-closing tags.
288 Default styles use only CSS1.
289 Equations rendered from
290 .Xr eqn 5
291 blocks use MathML.
292 .Pp
293 The
294 .Pa mandoc.css
295 file documents style-sheet classes available for customising output.
296 If a style-sheet is not specified with
297 .Fl O Cm style ,
298 .Fl T Cm html
299 defaults to simple output (via an embedded style-sheet)
300 readable in any graphical or text-based web
301 browser.
302 .Pp
303 Non-ASCII characters are rendered
304 as hexadecimal Unicode character references.
305 .Pp
306 The following
307 .Fl O
308 arguments are accepted:
309 .Bl -tag -width Ds
310 .It Cm fragment
311 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
312 elements and only emit the subtree below the <body> element.
313 The
314 .Cm style
315 argument will be ignored.
316 This is useful when embedding manual content within existing documents.
317 .It Cm includes Ns = Ns Ar fmt
318 The string
319 .Ar fmt ,
320 for example,
321 .Ar ../src/%I.html ,
322 is used as a template for linked header files (usually via the
323 .Ic \&In
324 macro).
334 .Ar ../html%S/%N.%S.html ,
335 is used as a template for linked manuals (usually via the
336 .Ic \&Xr
337 macro).
338 Instances of
339 .Sq \&%N
340 and
341 .Sq %S
342 are replaced with the linked manual's name and section, respectively.
343 If no section is included, section 1 is assumed.
344 The default is not to
345 present a hyperlink.
346 .It Cm style Ns = Ns Ar style.css
347 The file
348 .Ar style.css
349 is used for an external style-sheet.
350 This must be a valid absolute or
351 relative URI.
352 .El
353 .Ss Locale Output
354 By default,
355 .Nm
356 automatically selects UTF-8 or ASCII output according to the current
357 .Xr locale 1 .
358 If any of the environment variables
359 .Ev LC_ALL ,
360 .Ev LC_CTYPE ,
361 or
362 .Ev LANG
363 are set and the first one that is set
364 selects the UTF-8 character encoding, it produces
365 .Sx UTF-8 Output ;
366 otherwise, it falls back to
367 .Sx ASCII Output .
368 This output mode can also be selected explicitly with
369 .Fl T Cm locale .
370 .Ss Man Output
371 Use
372 .Fl T Cm man
373 to translate
374 .Xr mdoc 5
375 input into
376 .Xr man 5
377 output format.
378 This is useful for distributing manual sources to legacy systems
379 lacking
380 .Xr mdoc 5
381 formatters.
382 .Pp
383 If the input format of a file is
384 .Xr man 5 ,
385 the input is copied to the output, expanding any
386 .Xr mandoc_roff 5
387 .Ic so
388 requests.
389 The parser is also run, and as usual, the
390 .Fl W
391 level controls which
392 .Sx DIAGNOSTICS
393 are displayed before copying the input to the output.
394 .Ss Markdown Output
395 Use
396 .Fl T Cm markdown
397 to translate
398 .Xr mdoc 5
399 input to the markdown format conforming to
400 .Lk http://daringfireball.net/projects/markdown/syntax.text\
401 "John Gruber's 2004 specification" .
402 The output also almost conforms to the
403 .Lk http://commonmark.org/ CommonMark
404 specification.
405 .Pp
406 The character set used for the markdown output is ASCII.
407 Non-ASCII characters are encoded as HTML entities.
408 Since that is not possible in literal font contexts, because these
409 are rendered as code spans and code blocks in the markdown output,
410 non-ASCII characters are transliterated to ASCII approximations in
411 these contexts.
412 .Pp
413 Markdown is a very weak markup language, so all semantic markup is
414 lost, and even part of the presentational markup may be lost.
415 Do not use this as an intermediate step in converting to HTML;
416 instead, use
417 .Fl T Cm html
418 directly.
419 .Pp
450 .Fl O
451 arguments are accepted:
452 .Bl -tag -width Ds
453 .It Cm paper Ns = Ns Ar name
454 The paper size
455 .Ar name
456 may be one of
457 .Ar a3 ,
458 .Ar a4 ,
459 .Ar a5 ,
460 .Ar legal ,
461 or
462 .Ar letter .
463 You may also manually specify dimensions as
464 .Ar NNxNN ,
465 width by height in millimetres.
466 If an unknown value is encountered,
467 .Ar letter
468 is used.
469 .El
470 .Ss UTF-8 Output
471 Use
472 .Fl T Cm utf8
473 to force text output in UTF-8 multi-byte character encoding,
474 ignoring the
475 .Xr locale 1
476 settings in the environment.
477 See
478 .Sx ASCII Output
479 regarding font styles and
480 .Fl O
481 arguments.
482 .Pp
483 On operating systems lacking locale or wide character support, and
484 on those where the internal character representation is not UCS-4,
485 .Nm
486 always falls back to
487 .Sx ASCII Output .
488 .Ss Syntax tree output
489 Use
490 .Fl T Cm tree
491 to show a human readable representation of the syntax tree.
492 It is useful for debugging the source code of manual pages.
493 The exact format is subject to change, so don't write parsers for it.
494 .Pp
495 The first paragraph shows meta data found in the
496 .Xr mdoc 5
497 prologue, on the
498 .Xr man 5
499 .Ic \&TH
500 line, or the fallbacks used.
501 .Pp
502 In the tree dump, each output line shows one syntax tree node.
503 Child nodes are indented with respect to their parent node.
504 The columns are:
505 .Pp
506 .Bl -enum -compact
507 .It
534 BROKEN if the node is a block broken by another block.
535 .It
536 NOSRC if the node is not in the input file,
537 but automatically generated from macros.
538 .It
539 NOPRT if the node is not supposed to generate output
540 for any output format.
541 .El
542 .El
543 .Pp
544 The following
545 .Fl O
546 argument is accepted:
547 .Bl -tag -width Ds
548 .It Cm noval
549 Skip validation and show the unvalidated syntax tree.
550 This can help to find out whether a given behaviour is caused by
551 the parser or by the validator.
552 Meta data is not available in this case.
553 .El
554 .Sh ENVIRONMENT
555 .Bl -tag -width Ev
556 .It Ev LC_CTYPE
557 The character encoding
558 .Xr locale 1 .
559 When
560 .Sx Locale Output
561 is selected, it decides whether to use ASCII or UTF-8 output format.
562 It never affects the interpretation of input files.
563 .El
564 .Sh EXIT STATUS
565 The
566 .Nm
567 utility exits with one of the following values, controlled by the message
568 .Ar level
569 associated with the
570 .Fl W
571 option:
572 .Pp
573 .Bl -tag -width Ds -compact
574 .It 0
575 No base system convention violations, style suggestions, warnings,
576 or errors occurred, or those that did were ignored because they
577 were lower than the requested
578 .Ar level .
579 .It 1
580 At least one base system convention violation or style suggestion
581 occurred, but no warning or error, and
582 .Fl W Cm base
583 or
684 Indicates a risk of information loss or severe misformatting,
685 in most cases caused by serious syntax errors.
686 .It Cm warning
687 Indicates a risk that the information shown or its formatting
688 may mismatch the author's intent in minor ways.
689 Additionally, syntax errors are classified at least as warnings,
690 even if they do not usually cause misformatting.
691 .It Cm style
692 An input file uses dubious or discouraged style.
693 This is not a complaint about the syntax, and probably neither
694 formatting nor portability are in danger.
695 While great care is taken to avoid false positives on the higher
696 message levels, the
697 .Cm style
698 level tries to reduce the probability that issues go unnoticed,
699 so it may occasionally issue bogus suggestions.
700 Please use your good judgement to decide whether any particular
701 .Cm style
702 suggestion really justifies a change to the input file.
703 .It Cm base
704 A convention used in the base system of a specific operating system
705 is not adhered to.
706 These are not markup mistakes, and neither the quality of formatting
707 nor portability are in danger.
708 Messages of the
709 .Cm base
710 level are printed with the more intuitive
711 .Cm style
712 .Ar level
713 tag.
714 .El
715 .Pp
716 Messages of the
717 .Cm base ,
718 .Cm style ,
719 .Cm warning ,
720 .Cm error ,
721 and
722 .Cm unsupp
723 levels except those about non-existent or unreadable input files
724 are hidden unless their level, or a lower level, is requested using a
792 macro references a manual page that is not found in the base system.
793 The path to look for base system manuals is configurable at compile
794 time and defaults to
795 .Pa /usr/share/man : /usr/X11R6/man .
796 .El
797 .Ss Style suggestions
798 .Bl -ohang
799 .It Sy "legacy man(7) date format"
800 .Pq mdoc
801 The
802 .Ic \&Dd
803 macro uses the legacy
804 .Xr man 5
805 date format
806 .Dq yyyy-dd-mm .
807 Consider using the conventional
808 .Xr mdoc 5
809 date format
810 .Dq "Month dd, yyyy"
811 instead.
812 .It Sy "normalizing date format to" : No ...
813 .Pq mdoc , man
814 The
815 .Ic \&Dd
816 or
817 .Ic \&TH
818 macro provides an abbreviated month name or a day number with a
819 leading zero.
820 In the formatted output, the month name is written out in full
821 and the leading zero is omitted.
822 .It Sy "lower case character in document title"
823 .Pq mdoc , man
824 The title is still used as given in the
825 .Ic \&Dt
826 or
827 .Ic \&TH
828 macro.
829 .It Sy "duplicate RCS id"
830 A single manual page contains two copies of the RCS identifier for
831 the same operating system.
832 Consider deleting the later instance and moving the first one up
833 to the top of the page.
834 .It Sy "possible typo in section name"
835 .Pq mdoc
836 Fuzzy string matching revealed that the argument of an
837 .Ic \&Sh
838 macro is similar, but not identical to a standard section name.
839 .It Sy "unterminated quoted argument"
840 .Pq roff
841 Macro arguments can be enclosed in double quote characters
842 such that space characters and macro names contained in the quoted
843 argument need not be escaped.
844 The closing quote of the last argument of a macro can be omitted.
845 However, omitting it is not recommended because it makes the code
846 harder to read.
847 .It Sy "useless macro"
848 .Pq mdoc
849 A
850 .Ic \&Bt ,
851 .Ic \&Tn ,
852 or
853 .Ic \&Ud
854 macro was found.
891 .It Sy "no blank before trailing delimiter"
892 .Pq mdoc
893 The last argument of a macro that supports trailing delimiter
894 arguments is longer than one byte and ends with a trailing delimiter.
895 Consider inserting a blank such that the delimiter becomes a separate
896 argument, thus moving it out of the scope of the macro.
897 .It Sy "fill mode already enabled, skipping"
898 .Pq man
899 A
900 .Ic \&fi
901 request occurs even though the document is still in fill mode,
902 or already switched back to fill mode.
903 It has no effect.
904 .It Sy "fill mode already disabled, skipping"
905 .Pq man
906 An
907 .Ic \&nf
908 request occurs even though the document already switched to no-fill mode
909 and did not switch back to fill mode yet.
910 It has no effect.
911 .It Sy "verbatim \(dq--\(dq, maybe consider using \e(em"
912 .Pq mdoc
913 Even though the ASCII output device renders an em-dash as
914 .Qq \-\- ,
915 that is not a good way to write it in an input file
916 because it renders poorly on all other output devices.
917 .It Sy "function name without markup"
918 .Pq mdoc
919 A word followed by an empty pair of parentheses occurs on a text line.
920 Consider using an
921 .Ic \&Fn
922 or
923 .Ic \&Xr
924 macro.
925 .It Sy "whitespace at end of input line"
926 .Pq mdoc , man , roff
927 Whitespace at the end of input lines is almost never semantically
928 significant \(em but in the odd case where it might be, it is
929 extremely confusing when reviewing and maintaining documents.
930 .It Sy "bad comment style"
931 .Pq roff
932 Comment lines start with a dot, a backslash, and a double-quote character.
933 The
934 .Nm
935 utility treats the line as a comment line even without the backslash,
936 but leaving out the backslash might not be portable.
|