Lines Matching +full:ascii +full:. +full:d

1 .\" $Id: mandoc.1,v 1.267 2023/11/13 19:13:01 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2012, 2014-2023 Ingo Schwarze <schwarze@openbsd.org>
4 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
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: November 13 2023 $
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
36 .Nm
37 utility formats manual pages for display.
38 .Pp
40 .Nm
42 .Xr mdoc 7
44 .Xr man 7
46 .Fl T Cm locale
47 output.
48 .Pp
50 .Bl -tag -width Ds
51 .It Fl a
53 .Fl c
55 .Xr less 1
57 .Xr man 1
58 would.
59 .It Fl c
61 .Xr less 1
62 to paginate them.
63 This is the default.
65 .Fl a .
66 .It Fl I Cm os Ns = Ns Ar name
68 .Ar name
70 .Xr mdoc 7
71 .Ic \&Os
73 .Xr man 7
74 .Ic \&TH
75 macro.
76 .It Fl K Ar encoding
77 Specify the input encoding.
79 .Ar encoding
81 .Cm us-ascii ,
82 .Cm iso-8859-1 ,
84 .Cm utf-8 .
87 .Bl -enum
88 .It
91 .Cm utf-8 .
92 .It
94 .Sy emacs
96 .Pp
97 .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*-
98 .Pp
100 .Ar encoding .
101 .It
102 If the first non-ASCII byte in the file introduces a valid UTF-8
104 .Cm utf-8 .
105 .It
107 .Cm iso-8859-1 .
108 .El
109 .It Fl mdoc | man
111 .Fl mdoc ,
113 .Xr mdoc 7 .
115 .Fl man ,
117 .Xr man 7 .
120 .Ic \&Dd
122 .Ic \&Dt ,
124 .Xr mdoc 7
126 .Xr man 7
127 parser is used.
129 .Fl m
130 is silently ignored.
131 .It Fl O Ar options
132 Comma-separated output options.
134 .Ar options .
135 .It Fl T Ar output
136 Select the output format.
138 .Ar output
140 .Cm ascii ,
141 .Cm html ,
143 .Cm locale ,
144 .Cm man ,
145 .Cm markdown ,
146 .Cm pdf ,
147 .Cm ps ,
148 .Cm tree ,
150 .Cm utf8 .
151 .Pp
153 .Fl T Cm lint
154 mode only parses the input and produces no output.
156 .Fl W Cm all
158 error output, to standard output.
159 .It Fl W Ar level
161 .Ar level
162 to be reported on the standard error output and to affect the exit status.
164 .Ar level
166 .Cm base ,
167 .Cm style ,
168 .Cm warning ,
169 .Cm error ,
171 .Cm unsupp .
173 .Cm base
175 .Ic \&Os
177 .Fl Ios
179 .Xr uname 3
180 return value.
182 .Cm openbsd
184 .Cm netbsd
186 .Cm base
188 conventions for a particular operating system.
190 .Cm all
192 .Cm base .
194 .Nm
195 is silent.
197 .Sx EXIT STATUS
199 .Sx DIAGNOSTICS
200 for details.
201 .Pp
203 .Fl W Cm stop
205 .Nm
207 the requested level.
208 No formatted output will be produced from that file.
210 .Ar level
212 .Cm stop
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.
219 .Nm
220 reads from standard input.
221 .El
222 .Pp
224 .Fl fhklw
226 .Xr man 1 .
228 .Fl f
230 .Fl k
232 .Nm
234 .Fl CMmOSs
236 .Xr apropos 1
237 manual.
239 .Fl fkl
240 are mutually exclusive and override each other.
241 .Ss ASCII Output
243 .Fl T Cm ascii
244 to force text output in 7-bit ASCII character encoding documented in the
245 .Xr ascii 7
247 .Xr locale 1
248 set in the environment.
249 .Pp
252 .Sq c
254 .Sq _ Ns \e[bs] Ns c ,
256 .Sq \e[bs]
257 is the back-space character number 8.
259 .Sq c Ns \e[bs] Ns c .
262 .Xr ul 1 .
264 .Xr col 1
265 .Fl b
266 instead.
267 .Pp
269 .Xr mandoc_char 7
270 are rendered best-effort in an ASCII equivalent.
272 .Sq single quotes
274 which agrees with all ASCII standards from 1965 to the latest
276 .Xr roff 7
277 formatters represent single quotes in ASCII output.
278 This correct ASCII rendering may look strange with modern
279 Unicode-compatible fonts because contrary to ASCII, Unicode uses
281 quote.
282 .Pp
284 .Fl O
286 .Bl -tag -width Ds
287 .It Cm indent Ns = Ns Ar indent
289 .Ar indent
290 blank characters instead of the default of five.
292 for example overfull lines or ugly line breaks.
294 wide, the default is reduced to three columns.
295 .It Cm mdoc
297 .Xr man 7
299 .Xr mdoc 7
300 output style.
302 on the right side of the footer line.
304 .Fl T Cm man
306 .Xr mdoc 7
307 source it was generated from.
308 .It Cm tag Ns Op = Ns Ar term
311 .Ar term
312 rather than showing the manual page from the beginning.
314 .Ar term
316 .Ar section
317 number.
319 .Xr apropos 1
320 .Ar key Ns = Ns Ar val
322 .Ar val
323 is used rather than the argument as a whole.
325 .Ql man -akO tag Ic=ulimit
327 in the matching manual pages.
328 .It Cm width Ns = Ns Ar width
330 .Ar width
331 instead of the default of 78.
333 wide, the default is reduced to one less than the terminal width.
335 and may exceed the output width.
336 .El
337 .Ss HTML Output
339 .Fl T Cm html
340 conforms to HTML5 using optional self-closing tags.
342 .Xr eqn 7
343 blocks use MathML.
344 Non-ASCII characters are rendered
345 as hexadecimal Unicode character references.
346 .Pp
348 .Fl O
350 .Bl -tag -width Ds
351 .It Cm fragment
353 elements and only emit the subtree below the <body> element.
355 .Cm style
356 argument will be ignored.
357 This is useful when embedding manual content within existing documents.
358 .It Cm includes Ns = Ns Ar fmt
360 .Ar fmt ,
362 .Ar ../src/%I.html ,
364 .Ic \&In
365 macro).
367 .Sq \&%I
368 are replaced with the include filename.
370 hyperlink.
371 .It Cm man Ns = Ns Ar fmt Ns Op ; Ns Ar fmt
373 .Ar fmt ,
375 .Ar ../html%S/%N.%S.html ,
377 .Ic \&Xr
378 macro).
380 .Sq \&%N
382 .Sq %S
383 are replaced with the linked manual's name and section, respectively.
384 If no section is included, section 1 is assumed.
386 present a hyperlink.
388 .Ar %N.%S
390 otherwise, the second format is used.
391 .It Cm style Ns = Ns Ar style.css
393 .Ar style.css
394 is used as an external stylesheet.
396 relative URI.
397 .Pp
399 .Pa mandoc.css
401 .Nm
402 is recommended.
405 .Nm
410 providing simple support for users who prefer a dark color scheme.
411 .Pp
414 .Xr mdoc 7
416 .Nm Ns -specific
418 .Pa mandoc.css .
420 .Pa mandoc.css
422 .Nm
425 .Nm
426 is upgraded to a new version.
427 .Pp
429 .Fl O Cm style ,
430 .Fl T Cm html
432 adequate font-style and font-weight attributes for various macros.
434 but does not aim for looking similar to terminal output.
436 and to user settings in the browser configuration.
437 .It Cm tag Ns Op = Ns Ar term
439 .Sx ASCII Output .
441 .Ic file://
443 rather than passing merely a file name.
445 .Bd -literal -offset 3n
448 .Ed
449 .Pp
451 .Xr more 1
453 .Xr less 1 .
455 .Ql MANPAGER=less man -T html -O tag=toc mandoc
457 .Xr less 1
459 .Ic file://
460 URIs.
461 .It Cm toc
463 print a table of contents near the beginning of the output.
464 .El
465 .Ss Locale Output
467 .Nm
468 automatically selects UTF-8 or ASCII output according to the current
469 .Xr locale 1 .
471 .Ev LC_ALL ,
472 .Ev LC_CTYPE ,
474 .Ev LANG
477 .Sx UTF-8 Output ;
479 .Sx ASCII Output .
481 .Fl T Cm locale .
482 .Ss Man Output
484 .Fl T Cm man
486 .Xr mdoc 7
488 .Xr man 7
489 output format.
492 .Xr mdoc 7
493 formatters.
495 .Xr eqn 7
497 .Xr tbl 7
498 code is not supported.
499 .Pp
501 .Xr man 7 ,
502 the input is copied to the output.
504 .Fl W
506 .Sx DIAGNOSTICS
507 are displayed before copying the input to the output.
508 .Ss Markdown Output
510 .Fl T Cm markdown
512 .Xr mdoc 7
514 .Lk https://daringfireball.net/projects/markdown/syntax.text\
515  "John Gruber's 2004 specification" .
517 .Lk https://commonmark.org/ CommonMark
518 specification.
519 .Pp
520 The character set used for the markdown output is ASCII.
521 Non-ASCII characters are encoded as HTML entities.
524 non-ASCII characters are transliterated to ASCII approximations in
525 these contexts.
526 .Pp
528 lost, and even part of the presentational markup may be lost.
531 .Fl T Cm html
532 directly.
533 .Pp
535 .Xr man 7 ,
536 .Xr tbl 7 ,
538 .Xr eqn 7
540 .Fl T Cm markdown
541 output mode.
542 .Ss PDF Output
544 .Fl T Cm pdf .
546 .Sx PostScript Output
548 .Fl O
549 arguments and defaults.
550 .Ss PostScript Output
552 .Qq Adobe-3.0
554 .Fl T Cm ps .
556 family, 11-point.
557 Margins are calculated as 1/9 the page length and width.
558 Line-height is 1.4m.
559 .Pp
561 .Sx ASCII Output .
562 .Pp
564 .Fl O
566 .Bl -tag -width Ds
567 .It Cm paper Ns = Ns Ar name
569 .Ar name
571 .Ar a3 ,
572 .Ar a4 ,
573 .Ar a5 ,
574 .Ar legal ,
576 .Ar letter .
578 .Ar NNxNN ,
579 width by height in millimetres.
581 .Ar letter
582 is used.
583 .El
584 .Ss UTF-8 Output
586 .Fl T Cm utf8
589 .Xr locale 1
590 settings in the environment.
592 .Sx ASCII Output
594 .Fl O
595 arguments.
596 .Pp
599 .Nm
601 .Sx ASCII Output .
602 .Ss Syntax tree output
604 .Fl T Cm tree
605 to show a human readable representation of the syntax tree.
606 It is useful for debugging the source code of manual pages.
607 The exact format is subject to change, so don't write parsers for it.
608 .Pp
610 .Xr mdoc 7
612 .Xr man 7
613 .Ic \&TH
614 line, or the fallbacks used.
615 .Pp
616 In the tree dump, each output line shows one syntax tree node.
617 Child nodes are indented with respect to their parent node.
619 .Pp
620 .Bl -enum -compact
621 .It
623 .Xr tbl 7
624 nodes, the content.
626 .Xr eqn 7
627 nodes.
628 .It
629 Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
630 .It
632 .Bl -dash -compact
633 .It
634 An opening parenthesis if the node is an opening delimiter.
635 .It
636 An asterisk if the node starts a new input line.
637 .It
638 The input line number (starting at one).
639 .It
640 A colon.
641 .It
642 The input column number (starting at one).
643 .It
644 A closing parenthesis if the node is a closing delimiter.
645 .It
646 A full stop if the node ends a sentence.
647 .It
648 BROKEN if the node is a block broken by another block.
649 .It
651 but automatically generated from macros.
652 .It
654 for any output format.
655 .El
656 .El
657 .Pp
659 .Fl O
661 .Bl -tag -width Ds
662 .It Cm noval
663 Skip validation and show the unvalidated syntax tree.
665 the parser or by the validator.
666 Meta data is not available in this case.
667 .El
668 .Sh ENVIRONMENT
669 .Bl -tag -width MANPAGER
670 .It Ev LC_CTYPE
672 .Xr locale 1 .
674 .Sx Locale Output
675 is selected, it decides whether to use ASCII or UTF-8 output format.
676 It never affects the interpretation of input files.
677 .It Ev MANPAGER
679 .Ev MANPAGER
681 .Xr less 1 ;
683 .Xr man 1
684 for details.
686 .Fl a
688 .Fl l
689 is specified.
690 .It Ev PAGER
692 .Ev MANPAGER
693 is not defined.
695 .Xr less 1
696 is used.
698 .Fl a
700 .Fl l
701 is specified.
702 .El
703 .Sh EXIT STATUS
705 .Nm
707 .Ar level
709 .Fl W
711 .Pp
712 .Bl -tag -width Ds -compact
713 .It 0
717 .Ar level .
718 .It 1
721 .Fl W Cm base
723 .Fl W Cm style
724 was specified.
725 .It 2
727 .Fl W Cm warning
729 .Ar level
730 was requested.
731 .It 3
734 .Fl W Cm error
736 .Ar level
737 was requested.
738 .It 4
740 .Fl W Cm unsupp
742 .Ar level
743 was requested.
744 .It 5
745 Invalid command line arguments were specified.
746 No input files have been read.
747 .It 6
749 of memory, file descriptors, or process table entries.
751 .Nm
752 to exit at once, possibly in the middle of parsing or formatting a file.
753 .El
754 .Pp
756 .Fl T Cm lint
758 .Fl W Cm all .
759 .Sh EXAMPLES
761 .Pp
762 .Dl $ mandoc -a mandoc.1 man.1 apropos.1 makewhatis.8
763 .Pp
765 .Pa /usr/share/misc/mandoc.css
767 .Pp
768 .Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html
769 .Pp
771 .Pp
772 .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga
773 .Pp
775 .Pp
776 .Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 > manuals.ps
777 .Pp
779 .Xr mdoc 7
781 .Xr man 7
783 .Xr mdoc 7
785 .Pp
786 .Dl $ mandoc \-T man foo.mdoc > foo.man
787 .Sh DIAGNOSTICS
789 .Nm
791 .Bd -ragged -offset indent
792 .Nm :
793 .Ar file : Ns Ar line : Ns Ar column : level : message : macro argument ...
794 .Pq Ar os
795 .Ed
796 .Pp
798 .Ar file
800 .Ar line
802 .Ar column
803 number of the input file where the message was triggered.
804 The line and column numbers start at 1.
805 Both are omitted for messages referring to an input file as a whole.
807 .Ar level
809 .Ar message
810 strings are explained below.
812 .Ar macro
813 triggering the message and its arguments are omitted where meaningless.
815 .Ar os
817 for all operating systems.
821 .Ar file
823 .Ar level
824 fields.
825 .Pp
827 .Bl -tag -width "warning"
828 .It Cm syserr
829 An operating system error occurred.
830 There isn't necessarily anything wrong with the input files.
831 Output may all the same be missing or incomplete.
832 .It Cm badarg
833 Invalid command line arguments were specified.
834 No input files have been read and no output is produced.
835 .It Cm unsupp
837 .Xr roff 7
838 features.
841 .Nm
842 to process the file may be preferable.
843 .It Cm error
845 in most cases caused by serious syntax errors.
846 .It Cm warning
848 may mismatch the author's intent in minor ways.
850 even if they do not usually cause misformatting.
851 .It Cm style
852 An input file uses dubious or discouraged style.
854 formatting nor portability are in danger.
857 .Cm style
859 so it may occasionally issue bogus suggestions.
861 .Cm style
862 suggestion really justifies a change to the input file.
863 .It Cm base
865 is not adhered to.
867 nor portability are in danger.
869 .Cm base
871 .Cm style
872 .Ar level
873 tag.
874 .El
875 .Pp
877 .Cm base ,
878 .Cm style ,
879 .Cm warning ,
880 .Cm error ,
882 .Cm unsupp
884 .Fl W
886 .Fl T Cm lint
887 output mode.
888 .Pp
890 .Cm base
892 .Cm style
895 .Fl W
897 .Ic \&Os
899 .Fl Ios
902 .Xr uname 3
903 function.
904 .Ss Conventions for base system manuals
905 .Bl -ohang
906 .It Sy "Mdocdate found"
907 .Pq mdoc , Nx
909 .Ic \&Dd
911 .Ic Mdocdate
913 .Nx
914 base system.
916 .Dq "Month dd, yyyy"
917 format instead.
918 .It Sy "Mdocdate missing"
919 .Pq mdoc , Ox
921 .Ic \&Dd
923 .Ic Mdocdate
925 .Ox
926 base system.
927 .It Sy "unknown architecture"
928 .Pq mdoc , Ox , Nx
930 .Ic \&Dt
932 is running on.
933 .It Sy "operating system explicitly specified"
934 .Pq mdoc , Ox , Nx
936 .Ic \&Os
937 macro has an argument.
938 In the base system, it is conventionally left blank.
939 .It Sy "RCS id missing"
940 .Pq Ox , Nx
943 .Ic OpenBSD
945 .Ic NetBSD
946 keyword substitution as conventionally used in these operating systems.
947 .El
948 .Ss Style suggestions
949 .Bl -ohang
950 .It Sy "legacy man(7) date format"
951 .Pq mdoc
953 .Ic \&Dd
955 .Xr man 7
957 .Dq yyyy-dd-mm .
959 .Xr mdoc 7
961 .Dq "Month dd, yyyy"
962 instead.
963 .It Sy "normalizing date format to" : No ...
964 .Pq mdoc , man
966 .Ic \&Dd
968 .Ic \&TH
970 leading zero.
972 and the leading zero is omitted.
973 .It Sy "lower case character in document title"
974 .Pq mdoc , man
976 .Ic \&Dt
978 .Ic \&TH
979 macro.
980 .It Sy "duplicate RCS id"
982 the same operating system.
984 to the top of the page.
985 .It Sy "possible typo in section name"
986 .Pq mdoc
988 .Ic \&Sh
989 macro is similar, but not identical to a standard section name.
990 .It Sy "unterminated quoted argument"
991 .Pq roff
994 argument need not be escaped.
995 The closing quote of the last argument of a macro can be omitted.
997 harder to read.
998 .It Sy "useless macro"
999 .Pq mdoc
1001 .Ic \&Bt ,
1002 .Ic \&Tn ,
1004 .Ic \&Ud
1005 macro was found.
1006 Simply delete it: it serves no useful purpose.
1007 .It Sy "consider using OS macro"
1008 .Pq mdoc
1010 .Ic \&Bx
1012 .Ic \&Ox ,
1013 .Ic \&Nx ,
1014 .Ic \&Fx ,
1016 .Ic \&Dx .
1017 .It Sy "errnos out of order"
1018 .Pq mdoc, Nx
1020 .Ic \&Er
1022 .Ic \&Bl
1023 list are not in alphabetical order.
1024 .It Sy "duplicate errno"
1025 .Pq mdoc, Nx
1027 .Ic \&Bl
1029 .Ic \&It
1031 .Ic \&Er
1032 number.
1033 .It Sy "referenced manual not found"
1034 .Pq mdoc
1036 .Ic \&Xr
1037 macro references a manual page that was not found.
1039 .Fl W Cm base ,
1041 .Pa /usr/share/man : Ns Pa /usr/X11R6/man .
1043 .Dv MANPATH_BASE
1044 preprocessor macro.
1046 .Fl W Cm style ,
1048 .Xr man 1
1050 .Fl m
1052 .Fl M
1054 .Ev MANPATH
1056 .Xr man.conf 5
1058 .Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man ,
1060 .Dv MANPATH_DEFAULT
1061 preprocessor macro.
1062 .It Sy "trailing delimiter"
1063 .Pq mdoc
1065 .Ic \&Ex , \&Fo , \&Nd , \&Nm , \&Os , \&Sh , \&Ss , \&St ,
1067 .Ic \&Sx
1068 macro ends with a trailing delimiter.
1069 This is usually bad style and often indicates typos.
1070 Most likely, the delimiter can be removed.
1071 .It Sy "no blank before trailing delimiter"
1072 .Pq mdoc
1074 arguments is longer than one byte and ends with a trailing delimiter.
1076 argument, thus moving it out of the scope of the macro.
1077 .It Sy "fill mode already enabled, skipping"
1078 .Pq man
1080 .Ic \&fi
1082 or already switched back to fill mode.
1083 It has no effect.
1084 .It Sy "fill mode already disabled, skipping"
1085 .Pq man
1087 .Ic \&nf
1089 and did not switch back to fill mode yet.
1090 It has no effect.
1091 .It Sy "input text line longer than 80 bytes"
1093 at one of the blank characters before column 80.
1094 .It Sy "verbatim \(dq--\(dq, maybe consider using \e(em"
1095 .Pq mdoc
1096 Even though the ASCII output device renders an em-dash as
1097 .Qq \-\- ,
1099 because it renders poorly on all other output devices.
1100 .It Sy "function name without markup"
1101 .Pq mdoc
1102 A word followed by an empty pair of parentheses occurs on a text line.
1104 .Ic \&Fn
1106 .Ic \&Xr
1107 macro.
1108 .It Sy "whitespace at end of input line"
1109 .Pq mdoc , man , roff
1112 extremely confusing when reviewing and maintaining documents.
1113 .It Sy "bad comment style"
1114 .Pq roff
1115 Comment lines start with a dot, a backslash, and a double-quote character.
1117 .Nm
1119 but leaving out the backslash might not be portable.
1120 .El
1121 .Ss Warnings related to the document prologue
1122 .Bl -ohang
1123 .It Sy "missing manual title, using UNTITLED"
1124 .Pq mdoc
1126 .Ic \&Dt
1128 .Ic \&Dt
1129 macro before the first non-prologue macro.
1130 .It Sy "missing manual title, using \(dq\(dq"
1131 .Pq man
1133 .Ic \&TH
1134 macro, or it has no arguments.
1135 .It Sy "missing manual section, using \(dq\(dq"
1136 .Pq mdoc , man
1138 .Ic \&Dt
1140 .Ic \&TH
1141 macro lacks the mandatory section argument.
1142 .It Sy "unknown manual section"
1143 .Pq mdoc
1145 .Ic \&Dt
1146 line is invalid, but still used.
1147 .It Sy "filename/section mismatch"
1148 .Pq mdoc , man
1151 .Ic \&Dt
1153 .Ic \&TH
1155 .Ar section
1156 argument that starts with a different non-zero digit.
1158 .Ar section
1159 argument is used as provided anyway.
1160 Consider checking whether the file name or the argument need a correction.
1161 .It Sy "missing date, using \(dq\(dq"
1162 .Pq mdoc, man
1164 .Xr mdoc 7
1166 .Ic \&Dd
1168 .Ic \&Dd
1171 .Xr man 7
1173 .Ic \&TH
1175 .Ic \&TH
1176 macro has less than three arguments or its third argument is empty.
1177 .It Sy "cannot parse date, using it verbatim"
1178 .Pq mdoc , man
1180 .Ic \&Dd
1182 .Ic \&TH
1183 macro does not follow the conventional format.
1184 .It Sy "date in the future, using it anyway"
1185 .Pq mdoc , man
1187 .Ic \&Dd
1189 .Ic \&TH
1191 .Xr time 3 .
1192 .It Sy "missing Os macro, using \(dq\(dq"
1193 .Pq mdoc
1194 The default or current system is not shown in this case.
1195 .It Sy "late prologue macro"
1196 .Pq mdoc
1198 .Ic \&Dd
1200 .Ic \&Os
1201 macro occurs after some non-prologue macro, but still takes effect.
1202 .It Sy "prologue macros out of order"
1203 .Pq mdoc
1205 .Ic \&Dd ,
1206 .Ic \&Dt ,
1207 .Ic \&Os .
1208 All three macros are used even when given in another order.
1209 .El
1210 .Ss Warnings regarding document structure
1211 .Bl -ohang
1212 .It Sy ".so is fragile, better use ln(1)"
1213 .Pq roff
1215 current working directory.
1216 .It Sy "no document body"
1217 .Pq mdoc , man
1218 The document body contains neither text nor macros.
1219 An empty document is shown, consisting only of a header and a footer line.
1220 .It Sy "content before first section header"
1221 .Pq mdoc , man
1223 .Ic \&Sh
1225 .Ic \&SH
1226 section header.
1228 of the syntax tree, outside any section block.
1229 .It Sy "first section is not NAME"
1230 .Pq mdoc
1232 .Ic \&Sh
1234 .Sq NAME .
1236 .Xr makewhatis 8
1238 .Xr apropos 1 .
1239 .It Sy "NAME section without Nm before Nd"
1240 .Pq mdoc
1242 .Ic \&Nm
1244 .Ic \&Nd
1245 macro.
1246 .It Sy "NAME section without description"
1247 .Pq mdoc
1249 .Ic \&Nd
1250 child macro.
1251 .It Sy "description not at the end of NAME"
1252 .Pq mdoc
1254 .Ic \&Nd
1255 child macro, but other content follows it.
1256 .It Sy "bad NAME section content"
1257 .Pq mdoc
1259 .Ic \&Nm
1261 .Ic \&Nd .
1262 .It Sy "missing comma before name"
1263 .Pq mdoc
1265 .Ic \&Nm
1266 macro that is neither the first one nor preceded by a comma.
1267 .It Sy "missing description line, using \(dq\(dq"
1268 .Pq mdoc
1270 .Ic \&Nd
1271 macro lacks the required argument.
1272 The title line of the manual will end after the dash.
1273 .It Sy "description line outside NAME section"
1274 .Pq mdoc
1276 .Ic \&Nd
1277 macro appears outside the NAME section.
1279 .Xr apropos 1 ,
1280 but none of that behaviour is portable.
1281 .It Sy "sections out of conventional order"
1282 .Pq mdoc
1283 A standard section occurs after another section it usually precedes.
1285 and the order of sections is not changed.
1286 .It Sy "duplicate section title"
1287 .Pq mdoc
1288 The same standard section title occurs more than once.
1289 .It Sy "unexpected section"
1290 .Pq mdoc
1292 where it normally isn't useful.
1293 .It Sy "cross reference to self"
1294 .Pq mdoc , man
1296 .Ic \&Xr
1298 .Ic \&MR
1301 .Ic \&Nm
1303 .Ic \&Fn
1305 .Ic \&Fo
1306 macro in the SYNOPSIS.
1308 .Ic \&Nm
1310 .Ic \&Fn
1312 .Ic \&Xr .
1313 .It Sy "unusual Xr order"
1314 .Pq mdoc
1316 .Ic \&Xr
1319 .Ic \&Xr
1320 macros referring to the same section are out of alphabetical order.
1321 .It Sy "unusual Xr punctuation"
1322 .Pq mdoc
1324 .Ic \&Xr
1327 .Ic \&Xr
1328 macro.
1329 .It Sy "AUTHORS section without An macro"
1330 .Pq mdoc
1332 .Ic \&An
1333 macros, or only empty ones.
1334 Probably, there are author names lacking markup.
1335 .El
1336 .Ss "Warnings related to macros and nesting"
1337 .Bl -ohang
1338 .It Sy "obsolete macro"
1339 .Pq mdoc
1341 .Xr mdoc 7
1342 manual for replacements.
1343 .It Sy "macro neither callable nor escaped"
1344 .Pq mdoc
1345 The name of a macro that is not callable appears on a macro line.
1346 It is printed verbatim.
1349 .Sq \e& .
1350 .It Sy "skipping paragraph macro"
1352 .Xr mdoc 7
1354 .Bl -dash -compact
1355 .It
1357 .It
1359 .It
1361 .It
1362 and for multiple consecutive paragraph macros.
1363 .El
1365 .Xr man 7
1367 .Bl -dash -compact
1368 .It
1370 .Ic \&P ,
1371 .Ic \&PP ,
1373 .Ic \&LP
1375 .It
1377 .Ic \&IP
1379 .It
1381 .Ic \&br
1383 .Ic \&sp
1385 .Ic \&SH
1387 .Ic \&SS
1388 .El
1389 .It Sy "moving paragraph macro out of list"
1390 .Pq mdoc
1392 .Ic \&Bl
1393 list contains a trailing paragraph macro.
1394 The paragraph macro is moved after the end of the list.
1395 .It Sy "skipping no-space macro"
1396 .Pq mdoc
1398 .Ic \&Ns
1400 .Ic \&Ns
1401 macro is an isolated closing delimiter.
1402 The macro is ignored.
1403 .It Sy "blocks badly nested"
1404 .Pq mdoc
1405 If two blocks intersect, one should completely contain the other.
1409 blocks at all.
1411 .Qq Ic \&Ao \&Bo \&Ac \&Bc
1413 .Qq Ic \&Ao \&Bq \&Ac .
1415 .Ic \&Ac
1417 .Ic \&Bo
1419 .Ic \&Bq ,
1420 respectively.
1421 .It Sy "nested displays are not portable"
1422 .Pq mdoc
1424 .Ic \&Bd ,
1425 .Ic \&D1 ,
1427 .Ic \&Dl
1429 .Ic \&Bd
1430 display.
1432 .Nm ,
1433 but fails with most other implementations.
1434 .It Sy "moving content out of list"
1435 .Pq mdoc
1437 .Ic \&Bl
1439 .Ic \&It
1440 macro.
1441 The offending children are moved before the beginning of the list.
1442 .It Sy "first macro on line"
1444 .Ic \&Bl Fl column
1446 .Ic \&Ta
1447 macro occurs as the first macro on a line, which is not portable.
1448 .It Sy "line scope broken"
1449 .Pq man
1451 another macro is found that prematurely terminates the previous one.
1452 The previous, interrupted macro is deleted from the parse tree.
1453 .El
1454 .Ss "Warnings related to missing arguments"
1455 .Bl -ohang
1456 .It Sy "skipping empty request"
1457 .Pq roff , eqn
1460 .Xr eqn 7
1461 control statement or operation keyword lacks its required argument.
1462 .It Sy "conditional request controls empty scope"
1463 .Pq roff
1466 .Bl -dash -compact
1467 .It
1469 .Sq \e{
1470 keyword to open a multi-line scope.
1471 .It
1472 A request or macro or some text, resulting in a single-line scope.
1473 .It
1475 resulting in next-line scope.
1476 .El
1478 and there is no other content on its logical input line.
1481 .Sq \e
1482 line continuation characters.
1484 where trailing whitespace is syntactically significant.
1488 .Ic \&el
1489 clause.
1490 .It Sy "skipping empty macro"
1491 .Pq mdoc
1492 The indicated macro has no arguments and hence no effect.
1493 .It Sy "empty block"
1494 .Pq mdoc , man
1496 .Ic \&Bd ,
1497 .Ic \&Bk ,
1498 .Ic \&Bl ,
1499 .Ic \&D1 ,
1500 .Ic \&Dl ,
1502 .Ic \&RS
1503 block contains nothing in its body and will produce no output.
1504 .It Sy "empty argument, using 0n"
1505 .Pq mdoc
1507 .Ic \&Bd
1509 .Ic \&Bl
1510 .Fl offset
1512 .Fl width .
1513 .It Sy "missing display type, using -ragged"
1514 .Pq mdoc
1516 .Ic \&Bd
1517 macro is invoked without the required display type.
1518 .It Sy "list type is not the first argument"
1519 .Pq mdoc
1521 .Ic \&Bl
1522 macro, at least one other argument precedes the type argument.
1524 .Nm
1526 .Xr mdoc 7
1527 implementations do not.
1528 .It Sy "missing -width in -tag list, using 8n"
1529 .Pq mdoc
1531 .Ic \&Bl
1533 .Fl tag
1535 .Fl width ,
1536 too.
1537 .It Sy "missing utility name, using \(dq\(dq"
1538 .Pq mdoc
1540 .Ic \&Ex Fl std
1542 .Ic \&Nm
1543 has first been called with an argument.
1544 .It Sy "missing function name, using \(dq\(dq"
1545 .Pq mdoc
1547 .Ic \&Fo
1548 macro is called without an argument.
1549 No function name is printed.
1550 .It Sy "empty head in list item"
1551 .Pq mdoc
1553 .Ic \&Bl
1554 .Fl diag ,
1555 .Fl hang ,
1556 .Fl inset ,
1557 .Fl ohang ,
1559 .Fl tag
1561 .Ic \&It
1562 macro lacks the required argument.
1563 The item head is left empty.
1564 .It Sy "empty list item"
1565 .Pq mdoc
1567 .Ic \&Bl
1568 .Fl bullet ,
1569 .Fl dash ,
1570 .Fl enum ,
1572 .Fl hyphen
1574 .Ic \&It
1575 block is empty.
1576 An empty list item is shown.
1577 .It Sy "missing argument, using next line"
1578 .Pq mdoc
1580 .Ic \&It
1582 .Ic \&Bd Fl column
1583 list has no arguments.
1585 .Nm
1587 other formatters may misformat the list.
1588 .It Sy "missing font type, using \efR"
1589 .Pq mdoc
1591 .Ic \&Bf
1592 macro has no argument.
1593 It switches to the default font.
1594 .It Sy "unknown font type, using \efR"
1595 .Pq mdoc
1597 .Ic \&Bf
1598 argument is invalid.
1599 The default font is used instead.
1600 .It Sy "nothing follows prefix"
1601 .Pq mdoc
1603 .Ic \&Pf
1605 on the same input line.
1607 before the text or macros following on the next input line.
1608 .It Sy "empty reference block"
1609 .Pq mdoc
1611 .Ic \&Rs
1613 .Ic \&Re
1614 macro on the next input line.
1615 Such an empty block does not produce any output.
1616 .It Sy "missing section argument"
1617 .Pq mdoc , man
1619 .Ic \&Xr
1621 .Ic \&MR
1622 macro lacks its second, section number argument.
1623 The first argument, i.e. the name, is printed, but without a section number.
1625 .Ic \&Xr ,
1626 the parentheses are also omitted.
1627 .It Sy "missing -std argument, adding it"
1628 .Pq mdoc
1630 .Ic \&Ex
1632 .Ic \&Rv
1634 .Fl std
1635 argument.
1637 .Nm
1639 .Fl std
1640 even when it is not specified, but other implementations may not.
1641 .It Sy "missing option string, using \(dq\(dq"
1642 .Pq man
1644 .Ic \&OP
1645 macro is invoked without any argument.
1646 An empty pair of square brackets is shown.
1647 .It Sy "missing resource identifier, using \(dq\(dq"
1648 .Pq man
1650 .Ic \&MT
1652 .Ic \&UR
1653 macro is invoked without any argument.
1654 An empty pair of angle brackets is shown.
1655 .It Sy "missing eqn box, using \(dq\(dq"
1656 .Pq eqn
1658 but there is nothing to the left of it.
1659 An empty box is inserted.
1660 .El
1661 .Ss "Warnings related to bad macro arguments"
1662 .Bl -ohang
1663 .It Sy "duplicate argument"
1664 .Pq mdoc
1666 .Ic \&Bd
1668 .Ic \&Bl
1670 .Fl compact ,
1672 .Fl offset ,
1674 .Fl width
1675 argument.
1676 All but the last instances of these arguments are ignored.
1677 .It Sy "skipping duplicate argument"
1678 .Pq mdoc
1680 .Ic \&An
1682 .Fl split
1684 .Fl nosplit
1685 argument.
1686 All but the first of these arguments are ignored.
1687 .It Sy "skipping duplicate display type"
1688 .Pq mdoc
1690 .Ic \&Bd
1691 macro has more than one type argument; the first one is used.
1692 .It Sy "skipping duplicate list type"
1693 .Pq mdoc
1695 .Ic \&Bl
1696 macro has more than one type argument; the first one is used.
1697 .It Sy "skipping -width argument"
1698 .Pq mdoc
1700 .Ic \&Bl
1701 .Fl column ,
1702 .Fl diag ,
1703 .Fl ohang ,
1704 .Fl inset ,
1706 .Fl item
1708 .Fl width
1709 argument.
1710 That has no effect.
1711 .It Sy "wrong number of cells"
1713 .Ic \&Bl Fl column
1715 .Ic \&Ta
1717 or exceeds the expected number by more than one.
1719 columns are joined into one single cell.
1720 .It Sy "unknown AT&T UNIX version"
1721 .Pq mdoc
1723 .Ic \&At
1724 macro has an invalid argument.
1726 .Qq "AT&T UNIX "
1727 prefixed to it.
1728 .It Sy "comma in function argument"
1729 .Pq mdoc
1731 .Ic \&Fa
1733 .Ic \&Fn
1734 macro contains a comma; it should probably be split into two arguments.
1735 .It Sy "parenthesis in function name"
1736 .Pq mdoc
1738 .Ic \&Fc
1740 .Ic \&Fn
1742 parentheses are added automatically.
1743 .It Sy "unknown library name"
1744 .Pq mdoc, not on Ox
1746 .Ic \&Lb
1748 .Qq library Dq Ar name .
1749 .It Sy "invalid content in Rs block"
1750 .Pq mdoc
1752 .Ic \&Rs
1753 block contains plain text or non-% macros.
1754 The bogus content is left in the syntax tree.
1755 Formatting may be poor.
1756 .It Sy "invalid Boolean argument"
1757 .Pq mdoc
1759 .Ic \&Sm
1761 .Cm on
1763 .Cm off .
1765 empty, causing it to toggle the spacing mode.
1766 .It Sy "argument contains two font escapes"
1767 .Pq roff
1769 .Ic char
1770 request contains more than one font escape sequence.
1771 A wrong font may remain active after using the character.
1772 .It Sy "unknown font, skipping request"
1773 .Pq man , tbl
1775 .Xr roff 7
1776 .Ic \&ft
1778 .Xr tbl 7
1779 .Ic \&f
1781 .Ar font
1782 argument.
1783 .It Sy "ignoring distance argument"
1784 .Pq roff
1786 .Ic \&mc
1788 .Nm
1790 .Ic \&mc
1791 always ignores the second argument.
1792 .It Sy "odd number of characters in request"
1793 .Pq roff
1795 .Ic \&tr
1796 request contains an odd number of characters.
1797 The last character is mapped to the blank character.
1798 .El
1799 .Ss "Warnings related to plain text"
1800 .Bl -ohang
1801 .It Sy "blank line in fill mode, using .sp"
1802 .Pq mdoc
1805 significant.
1808 .Ic \&sp
1809 requests.
1811 .Ic \&Pp
1812 instead of a blank line.
1813 .It Sy "tab in filled text"
1814 .Pq mdoc , man
1817 on text input lines.
1819 are passed through to the formatters in any case.
1821 it is hard to predict which tab stop position the tab will advance to.
1822 .It Sy "new sentence, new line"
1823 .Pq mdoc
1824 A new sentence starts in the middle of a text line.
1825 Start it on a new input line to help formatters produce correct spacing.
1826 .It Sy "invalid escape sequence argument"
1827 .Pq roff
1828 The argument of an escape sequence is of an invalid form.
1829 Invalid escape sequences are ignored.
1830 .It Sy "undefined escape, printing literally"
1831 .Pq roff
1833 right after the leading backslash is invalid.
1835 which is equivalent to ignoring the backslash.
1836 .It Sy "undefined string, using \(dq\(dq"
1837 .Pq roff
1839 its value is implicitly set to the empty string.
1841 keeps the code more readable.
1842 .El
1843 .Ss "Warnings related to tables"
1844 .Bl -ohang
1845 .It Sy "tbl line starts with span"
1846 .Pq tbl
1848 .Pq Sq Cm s .
1849 Data provided for this cell is ignored, and nothing is printed in the cell.
1850 .It Sy "tbl column starts with span"
1851 .Pq tbl
1854 .Pq Sq Cm ^ .
1855 Data provided for this cell is ignored, and nothing is printed in the cell.
1856 .It Sy "skipping vertical bar in tbl layout"
1857 .Pq tbl
1858 A table layout specification contains more than two consecutive vertical bars.
1859 A double bar is printed, all additional bars are discarded.
1860 .El
1861 .Ss "Errors related to tables"
1862 .Bl -ohang
1863 .It Sy "non-alphabetic character in tbl options"
1864 .Pq tbl
1866 blank, or comma where the beginning of an option name is expected.
1867 The character is ignored.
1868 .It Sy "skipping unknown tbl option"
1869 .Pq tbl
1871 match any known option name.
1872 The word is ignored.
1873 .It Sy "missing tbl option argument"
1874 .Pq tbl
1877 followed by a closing parenthesis.
1878 The option is ignored.
1879 .It Sy "wrong tbl option argument size"
1880 .Pq tbl
1881 A table option argument contains an invalid number of characters.
1882 Both the option and the argument are ignored.
1883 .It Sy "empty tbl layout"
1884 .Pq tbl
1886 specifying zero lines and zero columns.
1887 As a fallback, a single left-justified column is used.
1888 .It Sy "invalid character in tbl layout"
1889 .Pq tbl
1892 or a modifier precedes the first key.
1893 The invalid character is discarded.
1894 .It Sy "unmatched parenthesis in tbl layout"
1895 .Pq tbl
1897 but no matching closing parenthesis.
1898 The rest of the input line, starting from the parenthesis, has no effect.
1899 .It Sy "ignoring excessive spacing in tbl layout"
1900 .Pq tbl
1901 A spacing modifier in a table layout is unreasonably large.
1902 The default spacing of 3n is used instead.
1903 .It Sy "tbl without any data cells"
1904 .Pq tbl
1905 A table does not contain any data cells.
1906 It will probably produce no output.
1907 .It Sy "ignoring data in spanned tbl cell"
1908 .Pq tbl
1910 .Pq Sq Cm s
1912 .Pq Sq Cm ^
1913 in the table layout, but it contains data.
1914 The data is ignored.
1915 .It Sy "ignoring extra tbl data cells"
1916 .Pq tbl
1917 A data line contains more cells than the corresponding layout line.
1918 The data in the extra cells is ignored.
1919 .It Sy "data block open at end of tbl"
1920 .Pq tbl
1922 .Cm T{ ,
1924 .Cm T} .
1926 and any remaining cells stay empty.
1927 .El
1928 .Ss "Errors related to roff, mdoc, and man code"
1929 .Bl -ohang
1930 .It Sy "duplicate prologue macro"
1931 .Pq mdoc
1932 One of the prologue macros occurs more than once.
1933 The last instance overrides all previous ones.
1934 .It Sy "skipping late title macro"
1935 .Pq mdoc
1937 .Ic \&Dt
1938 macro appears after the first non-prologue macro.
1940 they write the page header before parsing the document body.
1942 .Nm ,
1943 traditional semantics is preserved.
1944 The late macro is discarded including its arguments.
1945 .It Sy "input stack limit exceeded, infinite loop?"
1946 .Pq roff
1949 .Bl -dash -compact
1950 .It
1953 .It
1955 .It
1957 .Ic \&so
1958 file inclusion.
1959 .El
1961 some content, but the parser can continue.
1962 .It Sy "skipping bad character"
1963 .Pq mdoc , man , roff
1965 .Xr ascii 7
1966 character.
1967 The message mentions the character number.
1969 .Pq Sq \&? .
1970 Consider editing the input file to replace the byte with an ASCII
1971 transliteration of the intended character.
1972 .It Sy "skipping unknown macro"
1973 .Pq mdoc , man , roff
1975 .Xr roff 7
1977 .Xr mdoc 7
1979 .Xr man 7
1980 macro.
1981 It may be mistyped or unsupported.
1982 The request or macro is discarded including its arguments.
1983 .It Sy "skipping request outside macro"
1984 .Pq roff
1986 .Ic shift
1988 .Ic return
1989 request occurs outside any macro definition and has no effect.
1990 .It Sy "skipping insecure request"
1991 .Pq roff
1993 or to read or write an external file.
1994 Such attempts are denied for security reasons.
1995 .It Sy "skipping item outside list"
1996 .Pq mdoc , eqn
1998 .Ic \&It
2000 .Ic \&Bl
2002 .Xr eqn 7
2003 .Ic above
2004 delimiter occurs outside any pile.
2005 It is discarded including its arguments.
2006 .It Sy "skipping column outside column list"
2007 .Pq mdoc
2009 .Ic \&Ta
2011 .Ic \&Bl Fl column
2012 block.
2013 It is discarded including its arguments.
2014 .It Sy "skipping end of block that is not open"
2015 .Pq mdoc , man , eqn , tbl , roff
2017 that have previously been opened.
2019 .Xr mdoc 7
2021 .Xr man 7
2022 .Ic \&ME , \&RE
2024 .Ic \&UE
2026 .Xr eqn 7
2028 .Xr roff 7
2029 conditional request is encountered but no matching block is open.
2030 The offending request or macro is discarded.
2031 .It Sy "fewer RS blocks open, skipping"
2032 .Pq man
2034 .Ic \&RE
2036 .Ic \&RS
2037 blocks is open.
2039 .Ic \&RE
2040 macro is discarded.
2041 .It Sy "inserting missing end of block"
2042 .Pq mdoc , tbl
2044 .Xr mdoc 7
2045 macros as well as tables require explicit closing by dedicated macros.
2047 ends before all of its children are properly closed.
2048 The open child nodes are closed implicitly.
2049 .It Sy "appending missing end of block"
2050 .Pq mdoc , man , eqn , tbl , roff
2052 .Xr mdoc 7
2054 .Xr man 7
2056 .Ic \&MT , \&RS
2058 .Ic \&UR
2060 .Xr roff 7
2061 conditional or ignore block is still open.
2062 The open block is closed implicitly.
2063 .It Sy "escaped character not allowed in a name"
2064 .Pq roff
2066 non-whitespace ASCII characters.
2068 cannot form part of a name.
2070 .Ic \&am ,
2071 .Ic \&as ,
2072 .Ic \&de ,
2073 .Ic \&ds ,
2074 .Ic \&nr ,
2076 .Ic \&rr
2078 .Ic \&rm
2080 is terminated by an escape sequence.
2082 .Ic \&as ,
2083 .Ic \&ds ,
2085 .Ic \&nr ,
2086 the request has no effect at all.
2088 .Ic \&am ,
2089 .Ic \&de ,
2090 .Ic \&rr ,
2092 .Ic \&rm ,
2094 and the rest of the input line is discarded including the escape sequence.
2096 only the escape sequence is discarded.
2098 the characters following it are used as the arguments to the request or macro.
2099 .It Sy "using macro argument outside macro"
2100 .Pq roff
2102 and expands to the empty string.
2103 .It Sy "argument number is not numeric"
2104 .Pq roff
2106 the escape sequence expands to the empty string.
2107 .It Sy "negative argument, using 0"
2108 .Pq roff
2110 .Ic \&shift
2112 or an argument that is negative due to integer overflow.
2113 Macro argument numbering remains unchanged.
2114 .It Sy "NOT IMPLEMENTED: Bd -file"
2115 .Pq mdoc
2117 .Ic \&Bd
2119 .Fl file
2120 argument.
2123 the file on the screen, revealing the file content to bystanders.
2124 The argument is ignored including the file name following it.
2125 .It Sy "skipping display without arguments"
2126 .Pq mdoc
2128 .Ic \&Bd
2129 block macro does not have any arguments.
2131 whatever mode was active before the block.
2132 .It Sy "missing list type, using -item"
2133 .Pq mdoc
2135 .Ic \&Bl
2136 macro fails to specify the list type.
2137 .It Sy "argument is not numeric, using 1"
2138 .Pq roff
2140 .Ic \&ce
2141 request is not a number.
2142 .It Sy "argument is not a character"
2143 .Pq roff
2145 .Ic char
2146 request is neither a single ASCII character
2147 nor a single character escape sequence.
2148 The request is ignored including all its arguments.
2149 .It Sy "skipping unusable escape sequence"
2150 .Pq roff
2152 .Ic mc
2153 request is neither a single ASCII character
2154 nor a single character escape sequence.
2155 All arguments are ignored and printing of a margin character is disabled.
2156 .It Sy "missing manual name, using \(dq\(dq"
2157 .Pq mdoc , man
2159 .Ic \&Nm ,
2161 .Ic \&MR
2162 is called without any argument.
2163 .It Sy "uname(3) system call failed, using UNKNOWN"
2164 .Pq mdoc
2166 .Ic \&Os
2168 .Xr uname 3
2169 system call failed.
2171 .Nm
2173 .Sm off
2174 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
2175 .Sm on
2176 .It Sy "unknown standard specifier"
2177 .Pq mdoc
2179 .Ic \&St
2180 macro has an unknown argument and is discarded.
2181 .It Sy "skipping request without numeric argument"
2182 .Pq roff , eqn
2184 .Ic \&it
2186 .Xr eqn 7
2187 .Ic \&size
2189 .Ic \&gsize
2190 statement has a non-numeric or negative argument or no argument at all.
2191 The invalid request or statement is ignored.
2192 .It Sy "excessive shift"
2193 .Pq roff
2195 .Ic shift
2197 currently being executed.
2198 All macro arguments are deleted and \en(.$ is set to zero.
2199 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
2200 .Pq roff
2202 .Nm
2204 .Ic \&so
2206 and only without ascending to any parent directory.
2209 the file on the screen, revealing the file content to bystanders.
2210 .Nm
2212 .Ic \&so .
2213 .It Sy ".so request failed"
2214 .Pq roff
2216 .Ic \&so
2218 opened.
2219 .Nm
2221 .Ic \&so .
2222 .It Sy "skipping all arguments"
2223 .Pq mdoc , man , eqn , roff
2225 .Xr mdoc 7
2226 .Ic \&Bt ,
2227 .Ic \&Ed ,
2228 .Ic \&Ef ,
2229 .Ic \&Ek ,
2230 .Ic \&El ,
2231 .Ic \&Lp ,
2232 .Ic \&Pp ,
2233 .Ic \&Re ,
2234 .Ic \&Rs ,
2236 .Ic \&Ud
2238 .Ic \&It
2240 .Xr man 7
2241 .Ic \&LP ,
2242 .Ic \&P ,
2244 .Ic \&PP
2246 .Xr eqn 7
2247 .Ic \&EQ
2249 .Ic \&EN
2251 .Xr roff 7
2252 .Ic \&br ,
2253 .Ic \&fi ,
2255 .Ic \&nf
2257 .Sq \&..
2258 block closing request is invoked with at least one argument.
2259 All arguments are ignored.
2260 .It Sy "skipping excess arguments"
2261 .Pq mdoc , man , roff
2263 .Bl -dash -offset 2n -width 2n -compact
2264 .It
2265 .Ic \&Fo ,
2266 .Ic \&MT ,
2267 .Ic \&PD ,
2268 .Ic \&RS ,
2269 .Ic \&UR ,
2270 .Ic \&ft ,
2272 .Ic \&sp
2274 .It
2275 .Ic \&An
2277 .Fl split
2279 .Fl nosplit
2280 .It
2281 .Ic \&RE
2283 .It
2284 .Ic \&OP
2286 .Ic \&de
2288 .It
2289 .Ic \&Dt
2291 .Ic \&MR
2293 .It
2294 .Ic \&TH
2296 .It
2297 .Ic \&Bd ,
2298 .Ic \&Bk ,
2300 .Ic \&Bl
2302 .El
2303 The excess arguments are ignored.
2304 .El
2305 .Ss "Errors related to escape sequences"
2306 .Bl -ohang
2307 .It Sy "incomplete escape sequence"
2308 .Pq roff
2310 while parsing the argument of an escape sequence.
2312 .Ic \e*
2314 .Ic \en
2316 .Ic \eB
2318 .Sq 0 ,
2320 .Ic \ew
2321 to the length of the incomplete argument.
2322 All other incomplete escape sequences are ignored.
2323 .It Sy "invalid special character"
2324 .Pq roff
2327 or beyond the Unicode range, a \e[char...] escape sequence
2329 .Vt unsigned char
2332 .Qq \e[e]
2334 .Qq \e[~]
2336 .Qq \ee
2338 .Qq \e~ ,
2339 respectively.
2340 The escape sequence is ignored.
2341 .It Sy "unknown special character"
2342 .Pq roff
2344 .Nm .
2345 The escape sequence is ignored.
2346 .It Sy "invalid escape argument delimiter"
2347 .Pq roff
2350 .Qq " %&()*+-./0123456789:<=>"
2351 as an argument delimiter.
2353 and the rest of the argument may appear as output text.
2356 .Pq Sq \(aq
2357 is recommended for readability and robustness.
2358 .El
2359 .Ss Unsupported features
2360 .Bl -ohang
2361 .It Sy "input too large"
2362 .Pq mdoc , man
2364 .Nm
2366 of 2^31 bytes (2 Gigabytes).
2367 Since useful manuals are always small, this is not a problem in practice.
2368 Parsing is aborted as soon as the condition is detected.
2369 .It Sy "unsupported control character"
2370 .Pq roff
2371 An ASCII control character supported by other
2372 .Xr roff 7
2374 .Nm
2375 was found in an input file.
2376 It is replaced by a question mark.
2377 .It Sy "unsupported escape sequence"
2378 .Pq roff
2381 .Nm ,
2383 or considerable misformatting.
2384 .It Sy "unsupported roff request"
2385 .Pq roff
2387 .Xr roff 7
2389 .Nm ,
2391 or considerable misformatting.
2392 .It Sy "eqn delim option in tbl"
2393 .Pq eqn , tbl
2394 The options line of a table defines equation delimiters.
2395 Any equation source code contained in the table will be printed unformatted.
2396 .It Sy "unsupported table layout modifier"
2397 .Pq tbl
2399 .Sq Cm m
2400 modifier.
2401 The modifier is discarded.
2402 .It Sy "ignoring macro in table"
2403 .Pq tbl , mdoc , man
2405 .Xr mdoc 7
2407 .Xr man 7
2408 macro or of an undefined macro.
2410 as if they were a text line.
2411 .It Sy "skipping tbl in -Tman mode"
2412 .Pq mdoc , tbl
2414 .Ic \&TS
2415 macro.
2417 .Fl T Cm man
2419 .Xr tbl 7
2420 input is not supported.
2421 .It Sy "skipping eqn in -Tman mode"
2422 .Pq mdoc , eqn
2424 .Ic \&EQ
2425 macro.
2427 .Fl T Cm man
2429 .Xr eqn 7
2430 input is not supported.
2431 .El
2432 .Ss Bad command line arguments
2433 .Bl -ohang
2434 .It Sy "bad command line argument"
2436 .Fl IKMmOTW
2438 .Ar file
2439 given as a command line argument cannot be opened.
2440 .It Sy "duplicate command line argument"
2442 .Fl I
2443 command line option was specified twice.
2444 .It Sy "option has a superfluous value"
2446 .Fl O
2447 option has a value but does not accept one.
2448 .It Sy "missing option value"
2450 .Fl O
2451 option has no argument but requires one.
2452 .It Sy "bad option value"
2454 .Fl O
2455 .Cm indent
2457 .Cm width
2458 option has an invalid value.
2459 .It Sy "duplicate option value"
2461 .Fl O
2462 option is specified more than once.
2463 .It Sy "no such tag"
2465 .Fl O Cm tag
2467 manual pages.
2468 .It Sy "\-Tmarkdown unsupported for man(7) input"
2469 .Pq man
2471 .Fl T Cm markdown
2473 .Xr man 7
2474 language.
2475 No output is produced for that input file.
2476 .El
2477 .Sh SEE ALSO
2478 .Xr apropos 1 ,
2479 .Xr man 1 ,
2480 .Xr eqn 7 ,
2481 .Xr man 7 ,
2482 .Xr mandoc_char 7 ,
2483 .Xr mdoc 7 ,
2484 .Xr roff 7 ,
2485 .Xr tbl 7
2486 .Sh HISTORY
2488 .Nm
2490 .Ox 4.8 .
2492 .Fl I
2494 .Ox 5.2 ,
2496 .Fl aCcfhKklMSsw
2498 .Ox 5.7 .
2499 .Sh AUTHORS
2500 .An -nosplit
2502 .Nm
2504 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
2506 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .