=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.234 retrieving revision 1.243 diff -u -p -r1.234 -r1.243 --- mandoc/mandoc.1 2018/12/24 23:37:22 1.234 +++ mandoc/mandoc.1 2020/04/24 12:02:33 1.243 @@ -1,7 +1,7 @@ -.\" $Id: mandoc.1,v 1.234 2018/12/24 23:37:22 schwarze Exp $ +.\" $OpenBSD: mandoc.1,v 1.243 2020/04/24 12:02:33 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: December 24 2018 $ +.Dd $Mdocdate: April 24 2020 $ .Dt MANDOC 1 .Os .Sh NAME @@ -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 @@ -256,10 +257,28 @@ where is the back-space character number 8. Emboldened characters are rendered as .Sq c Ns \e[bs] Ns c . +This markup is typically converted to appropriate terminal sequences by +the pager or +.Xr ul 1 . +To remove the markup, pipe the output to +.Xr col 1 +.Fl b +instead. .Pp 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 @@ -300,8 +319,16 @@ If no is specified, reuse the first command line argument that is not a .Ar section number. -This is useful when it is the name of a manual page, -in particular the name of a library function. +If that argument is in +.Xr apropos 1 +.Ar key Ns = Ns Ar val +format, only the +.Ar val +is used rather than the argument as a whole. +This is useful for commands like +.Ql man -akO tag Ic=ulimit +to search for a keyword and jump right to its definition +in the matching manual pages. .It Cm width Ns = Ns Ar width The output width is set to .Ar width @@ -416,6 +443,11 @@ 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 , @@ -671,7 +703,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 @@ -751,6 +783,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 @@ -799,8 +838,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 @@ -1040,7 +1078,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 @@ -1673,9 +1725,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: @@ -2211,6 +2266,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 ,