=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.236 retrieving revision 1.248 diff -u -p -r1.236 -r1.248 --- mandoc/mandoc.1 2019/01/01 08:18:11 1.236 +++ mandoc/mandoc.1 2020/09/01 18:25:27 1.248 @@ -1,7 +1,7 @@ -.\" $Id: mandoc.1,v 1.236 2019/01/01 08:18:11 schwarze Exp $ +.\" $OpenBSD: mandoc.1,v 1.248 2020/09/01 18:25:27 schwarze Exp $ .\" +.\" Copyright (c) 2012, 2014-2020 Ingo Schwarze .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons -.\" Copyright (c) 2012, 2014-2018 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -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: January 1 2019 $ +.Dd $Mdocdate: September 1 2020 $ .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 @@ -222,7 +222,8 @@ reads from standard input. .Pp The options .Fl fhklw -are also supported and are documented in man(1). +are also supported and are documented in +.Xr man 1 . In .Fl f and @@ -267,6 +268,17 @@ instead. The special characters documented in .Xr mandoc_char 7 are rendered best-effort in an ASCII equivalent. +In particular, opening and closing +.Sq single quotes +are represented as characters number 0x60 and 0x27, respectively, +which agrees with all ASCII standards from 1965 to the latest +revision (2012) and which matches the traditional way in which +.Xr roff 7 +formatters represent single quotes in ASCII output. +This correct ASCII rendering may look strange with modern +Unicode-compatible fonts because contrary to ASCII, Unicode uses +the code point U+0060 for the grave accent only, never for an opening +quote. .Pp The following .Fl O @@ -398,6 +410,30 @@ The file is used for an external style-sheet. This must be a valid absolute or relative URI. +.It Cm tag Ns Op = Ns Ar term +Same syntax and semantics as for +.Sx ASCII Output . +This is implemented by passing a +.Ic file:// +URI ending in a fragment identifier to the pager +rather than passing merely a file name. +When using this argument, use a pager supporting such URIs, for example +.Bd -literal -offset 3n +MANPAGER='lynx -force_html' man -T html -O tag=MANPAGER man +MANPAGER='w3m -T text/html' man -T html -O tag=toc mandoc +.Ed +.Pp +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. @@ -431,13 +467,15 @@ This is useful for distributing manual sources to lega lacking .Xr mdoc 7 formatters. +Embedded +.Xr eqn 7 +and +.Xr tbl 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 @@ -616,7 +654,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. @@ -630,8 +668,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 @@ -686,7 +723,7 @@ No input files have been read. .It 6 An operating system error occurred, for example exhaustion of memory, file descriptors, or process table entries. -Such errors cause +Such errors may cause .Nm to exit at once, possibly in the middle of parsing or formatting a file. .El @@ -766,6 +803,13 @@ fields. .Pp Message levels have the following meanings: .Bl -tag -width "warning" +.It Cm syserr +An operating system error occurred. +There isn't necessarily anything wrong with the input files. +Output may all the same be missing or incomplete. +.It Cm badarg +Invalid command line arguments were specified. +No input files have been read and no output is produced. .It Cm unsupp An input file uses unsupported low-level .Xr roff 7 @@ -814,8 +858,7 @@ Messages of the .Cm error , and .Cm unsupp -levels except those about non-existent or unreadable input files -are hidden unless their level, or a lower level, is requested using a +levels are hidden unless their level, or a lower level, is requested using a .Fl W option or .Fl T Cm lint @@ -1055,7 +1098,21 @@ macro lacks the mandatory section argument. The section number in a .Ic \&Dt line is invalid, but still used. -.It Sy "missing date, using today's date" +.It Sy "filename/section mismatch" +.Pq mdoc , man +The name of the input file being processed is known and its file +name extension starts with a non-zero digit, but the +.Ic \&Dt +or +.Ic \&TH +macro contains a +.Ar section +argument that starts with a different non-zero digit. +The +.Ar section +argument is used as provided anyway. +Consider checking whether the file name or the argument need a correction. +.It Sy "missing date, using \(dq\(dq" .Pq mdoc, man The document was parsed as .Xr mdoc 7 @@ -1688,9 +1745,12 @@ The meaning of blank input lines is only well-defined In fill mode, line breaks of text input lines are not supposed to be significant. However, for compatibility with groff, blank lines in fill mode -are replaced with +are formatted like .Ic \&sp requests. +To request a paragraph break, use +.Ic \&Pp +instead of a blank line. .It Sy "tab in filled text" .Pq mdoc , man The meaning of tab characters is only well-defined in non-fill mode: @@ -1790,6 +1850,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. @@ -2226,6 +2290,43 @@ or macro or of an undefined macro. The macro is ignored, and its arguments are handled as if they were a text line. +.El +.Ss Bad command line arguments +.Bl -ohang +.It Sy "bad command line argument" +The argument following one of the +.Fl IKMmOTW +command line options is invalid, or a +.Ar file +given as a command line argument cannot be opened. +.It Sy "duplicate command line argument" +The +.Fl I +command line option was specified twice. +.It Sy "option has a superfluous value" +An argument to the +.Fl O +option has a value but does not accept one. +.It Sy "missing option value" +An argument to the +.Fl O +option has no argument but requires one. +.It Sy "bad option value" +An argument to the +.Fl O +.Cm indent +or +.Cm width +option has an invalid value. +.It Sy "duplicate option value" +The same +.Fl O +option is specified more than once. +.It Sy "no such tag" +The +.Fl O Cm tag +option was specified but the tag was not found in any of the displayed +manual pages. .El .Sh SEE ALSO .Xr apropos 1 ,