=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.244 retrieving revision 1.262 diff -u -p -r1.244 -r1.262 --- mandoc/mandoc.1 2020/06/15 18:05:18 1.244 +++ mandoc/mandoc.1 2022/07/03 14:36:00 1.262 @@ -1,6 +1,6 @@ -.\" $OpenBSD: mandoc.1,v 1.244 2020/06/15 18:05:18 schwarze Exp $ +.\" $Id: mandoc.1,v 1.262 2022/07/03 14:36:00 schwarze Exp $ .\" -.\" Copyright (c) 2012, 2014-2020 Ingo Schwarze +.\" Copyright (c) 2012, 2014-2022 Ingo Schwarze .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 15 2020 $ +.Dd $Mdocdate: July 3 2022 $ .Dt MANDOC 1 .Os .Sh NAME @@ -52,13 +52,13 @@ The options are as follows: If the standard output is a terminal device and .Fl c is not specified, use -.Xr more 1 +.Xr less 1 to paginate the output, just like .Xr man 1 would. .It Fl c Copy the formatted manual pages to the standard output without using -.Xr more 1 +.Xr less 1 to paginate them. This is the default. It can be specified to override @@ -301,8 +301,8 @@ Format input files in .Xr mdoc 7 output style. -Specifically, this suppresses the two additional blank lines near the -top and the bottom of each page, and it implies +This prints the operating system name rather than the page title +on the right side of the footer line, and it implies .Fl O Cm indent Ns =5 . One useful application is for checking that .Fl T Cm man @@ -342,7 +342,6 @@ and may exceed the output width. Output produced by .Fl T Cm html conforms to HTML5 using optional self-closing tags. -Default styles use only CSS1. Equations rendered from .Xr eqn 7 blocks use MathML. @@ -423,10 +422,17 @@ MANPAGER='lynx -force_html' man -T html -O tag=MANPAGE MANPAGER='w3m -T text/html' man -T html -O tag=toc mandoc .Ed .Pp -This argument does not work with +Consequently, for HTML output, this argument does not work with .Xr more 1 or .Xr less 1 . +For example, +.Ql MANPAGER=less man -T html -O tag=toc mandoc +does not work because +.Xr less 1 +does not support +.Ic file:// +URIs. .It Cm toc If an input file contains at least two non-standard sections, print a table of contents near the beginning of the output. @@ -468,10 +474,7 @@ code is not supported. .Pp If the input format of a file is .Xr man 7 , -the input is copied to the output, expanding any -.Xr roff 7 -.Ic so -requests. +the input is copied to the output. The parser is also run, and as usual, the .Fl W level controls which @@ -483,10 +486,10 @@ Use to translate .Xr mdoc 7 input to the markdown format conforming to -.Lk http://daringfireball.net/projects/markdown/syntax.text\ +.Lk https://daringfireball.net/projects/markdown/syntax.text\ "John Gruber's 2004 specification" . The output also almost conforms to the -.Lk http://commonmark.org/ CommonMark +.Lk https://commonmark.org/ CommonMark specification. .Pp The character set used for the markdown output is ASCII. @@ -650,7 +653,7 @@ It never affects the interpretation of input files. Any non-empty value of the environment variable .Ev MANPAGER is used instead of the standard pagination program, -.Xr more 1 ; +.Xr less 1 ; see .Xr man 1 for details. @@ -664,8 +667,7 @@ Specifies the pagination program to use when .Ev MANPAGER is not defined. If neither PAGER nor MANPAGER is defined, -.Xr more 1 -.Fl s +.Xr less 1 is used. Only used if .Fl a @@ -732,7 +734,7 @@ output mode implies .Sh EXAMPLES To page manuals to the terminal: .Pp -.Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8 +.Dl $ mandoc -a mandoc.1 man.1 apropos.1 makewhatis.8 .Pp To produce HTML manuals with .Pa /usr/share/misc/mandoc.css @@ -832,7 +834,7 @@ message levels, the .Cm style level tries to reduce the probability that issues go unnoticed, so it may occasionally issue bogus suggestions. -Please use your good judgement to decide whether any particular +Use your judgement to decide whether any particular .Cm style suggestion really justifies a change to the input file. .It Cm base @@ -919,14 +921,6 @@ generated by CVS or .Ic NetBSD keyword substitution as conventionally used in these operating systems. -.It Sy "referenced manual not found" -.Pq mdoc -An -.Ic \&Xr -macro references a manual page that is not found in the base system. -The path to look for base system manuals is configurable at compile -time and defaults to -.Pa /usr/share/man : /usr/X11R6/man . .El .Ss Style suggestions .Bl -ohang @@ -1013,6 +1007,35 @@ list contains two consecutive entries describing the same .Ic \&Er number. +.It Sy "referenced manual not found" +.Pq mdoc +An +.Ic \&Xr +macro references a manual page that was not found. +When running with +.Fl W Cm base , +the search is restricted to the base system, by default to +.Pa /usr/share/man : Ns Pa /usr/X11R6/man . +This path can be configured at compile time using the +.Dv MANPATH_BASE +preprocessor macro. +When running with +.Fl W Cm style , +the search is done along the full search path as described in the +.Xr man 1 +manual page, respecting the +.Fl m +and +.Fl M +command line options, the +.Ev MANPATH +environment variable, the +.Xr man.conf 5 +file and falling back to the default of +.Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man , +also configurable at compile time using the +.Dv MANPATH_DEFAULT +preprocessor macro. .It Sy "trailing delimiter" .Pq mdoc The last argument of an @@ -1042,6 +1065,9 @@ An request occurs even though the document already switched to no-fill mode and did not switch back to fill mode yet. It has no effect. +.It Sy "input text line longer than 80 bytes" +Consider breaking the input text line +at one of the blank characters before column 80. .It Sy "verbatim \(dq--\(dq, maybe consider using \e(em" .Pq mdoc Even though the ASCII output device renders an em-dash as @@ -1727,6 +1753,15 @@ request or a layout modifier has an unknown .Ar font argument. +.It Sy "ignoring distance argument" +.Pq roff +In addition to the margin character, an +.Ic \&mc +request has a second argument supposed to represent a distance, but the +.Nm +implementation of +.Ic \&mc +always ignores the second argument. .It Sy "odd number of characters in request" .Pq roff A @@ -1761,23 +1796,10 @@ it is hard to predict which tab stop position the tab .Pq mdoc A new sentence starts in the middle of a text line. Start it on a new input line to help formatters produce correct spacing. -.It Sy "invalid escape sequence" +.It Sy "invalid escape sequence argument" .Pq roff -An escape sequence has an invalid opening argument delimiter, lacks the -closing argument delimiter, the argument is of an invalid form, or it is -a character escape sequence with an invalid name. -If the argument is incomplete, -.Ic \e* -and -.Ic \en -expand to an empty string, -.Ic \eB -to the digit -.Sq 0 , -and -.Ic \ew -to the length of the incomplete argument. -All other invalid escape sequences are ignored. +The argument of an escape sequence is of an invalid form. +Invalid escape sequences are ignored. .It Sy "undefined escape, printing literally" .Pq roff In an escape sequence, the first character @@ -1847,6 +1869,10 @@ The invalid character is discarded. A table layout specification contains an opening parenthesis, but no matching closing parenthesis. The rest of the input line, starting from the parenthesis, has no effect. +.It Sy "ignoring excessive spacing in tbl layout" +.Pq tbl +A spacing modifier in a table layout is unreasonably large. +The default spacing of 3n is used instead. .It Sy "tbl without any data cells" .Pq tbl A table does not contain any data cells. @@ -2051,6 +2077,13 @@ and expands to the empty string. .Pq roff The argument of the escape sequence \e$ is not a digit; the escape sequence expands to the empty string. +.It Sy "negative argument, using 0" +.Pq roff +A +.Ic \&shift +request has a negative argument +or an argument that is negative due to integer overflow. +Macro argument numbering remains unchanged. .It Sy "NOT IMPLEMENTED: Bd -file" .Pq mdoc For security reasons, the @@ -2086,6 +2119,13 @@ The first argument of a request is neither a single ASCII character nor a single character escape sequence. The request is ignored including all its arguments. +.It Sy "skipping unusable escape sequence" +.Pq roff +The first argument of an +.Ic mc +request is neither a single ASCII character +nor a single character escape sequence. +All arguments are ignored and printing of a margin character is disabled. .It Sy "missing manual name, using \(dq\(dq" .Pq mdoc The first call to @@ -2231,6 +2271,60 @@ with invalid arguments .El The excess arguments are ignored. .El +.Ss "Errors related to escape sequences" +.Bl -ohang +.It Sy "incomplete escape sequence" +.Pq roff +The end of the input line is encountered +while parsing the argument of an escape sequence. +In this case, +.Ic \e* +and +.Ic \en +expand to an empty string, +.Ic \eB +to the digit +.Sq 0 , +and +.Ic \ew +to the length of the incomplete argument. +All other incomplete escape sequences are ignored. +.It Sy "invalid special character" +.Pq roff +A special character escape sequence is invalid, +for example a Unicode sequence pointing to a surrogate +or beyond the Unicode range, a \e[char...] escape sequence +representing a control character or pointing beyond the +.Vt unsigned char +range, or an invalid variable-length form +of a single-byte character escape sequence, for example writing +.Qq \e[e] +or +.Qq \e[~] +instead of +.Qq \ee +or +.Qq \e~ , +respectively. +The escape sequence is ignored. +.It Sy "unknown special character" +.Pq roff +The name given in a special character escape sequence is not known to +.Nm . +The escape sequence is ignored. +.It Sy "invalid escape argument delimiter" +.Pq roff +An escape sequence that expects a numerical argument +attempts to employ one of the characters +.Qq " %&()*+-./0123456789:<=>" +as an argument delimiter. +The escape sequence is ignored including the invalid opening delimiter +and the rest of the argument may appear as output text. +While various characters can be used as argument delimiters, +using the apostrophe-quote character +.Pq Sq \(aq +is recommended for readability and robustness. +.El .Ss Unsupported features .Bl -ohang .It Sy "input too large" @@ -2283,6 +2377,26 @@ or macro or of an undefined macro. The macro is ignored, and its arguments are handled as if they were a text line. +.It Sy "skipping tbl in -Tman mode" +.Pq mdoc , tbl +An input file contains the +.Ic \&TS +macro. +This message is only generated in +.Fl T Cm man +output mode, where +.Xr tbl 7 +input is not supported. +.It Sy "skipping eqn in -Tman mode" +.Pq mdoc , eqn +An input file contains the +.Ic \&EQ +macro. +This message is only generated in +.Fl T Cm man +output mode, where +.Xr eqn 7 +input is not supported. .El .Ss Bad command line arguments .Bl -ohang @@ -2320,6 +2434,14 @@ The .Fl O Cm tag option was specified but the tag was not found in any of the displayed manual pages. +.It Sy "\-Tmarkdown unsupported for man(7) input" +.Pq man +The +.Fl T Cm markdown +option was specified but an input file uses the +.Xr man 7 +language. +No output is produced for that input file. .El .Sh SEE ALSO .Xr apropos 1 ,