=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.231 retrieving revision 1.238 diff -u -p -r1.231 -r1.238 --- mandoc/mandoc.1 2018/11/22 11:30:23 1.231 +++ mandoc/mandoc.1 2019/04/30 11:48:10 1.238 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.231 2018/11/22 11:30:23 schwarze Exp $ +.\" $Id: mandoc.1,v 1.238 2019/04/30 11:48:10 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2012, 2014-2018 Ingo Schwarze @@ -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: November 22 2018 $ +.Dd $Mdocdate: April 30 2019 $ .Dt MANDOC 1 .Os .Sh NAME @@ -256,10 +256,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 +318,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 @@ -320,9 +346,9 @@ Equations rendered from .Xr eqn 7 blocks use MathML. .Pp -The -.Pa mandoc.css -file documents style-sheet classes available for customising output. +The file +.Pa /usr/share/misc/mandoc.css +documents style-sheet classes available for customising output. If a style-sheet is not specified with .Fl O Cm style , .Fl T Cm html @@ -686,10 +712,10 @@ To page manuals to the terminal: .Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8 .Pp To produce HTML manuals with -.Pa mandoc.css +.Pa /usr/share/misc/mandoc.css as the style-sheet: .Pp -.Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html +.Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html .Pp To check over a large set of manuals: .Pp @@ -697,7 +723,7 @@ To check over a large set of manuals: .Pp To produce a series of PostScript manuals for A4 paper: .Pp -.Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps +.Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 > manuals.ps .Pp Convert a modern .Xr mdoc 7 @@ -707,20 +733,36 @@ format, for use on systems lacking an .Xr mdoc 7 parser: .Pp -.Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man +.Dl $ mandoc \-T man foo.mdoc > foo.man .Sh DIAGNOSTICS Messages displayed by .Nm follow this format: .Bd -ragged -offset indent .Nm : -.Ar file : Ns Ar line : Ns Ar column : level : message : macro args +.Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments .Pq Ar os .Ed .Pp -Line and column numbers start at 1. +The first three fields identify the +.Ar file +name, +.Ar line +number, and +.Ar column +number of the input file where the message was triggered. +The line and column numbers start at 1. Both are omitted for messages referring to an input file as a whole. -Macro names and arguments are omitted where meaningless. +All +.Ar level +and +.Ar message +strings are explained below. +The name of the +.Ar macro +triggering the message and its +.Ar arguments +are omitted where meaningless. The .Ar os operating system specifier is omitted for messages that are relevant @@ -1657,9 +1699,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: @@ -1676,7 +1721,8 @@ Start it on a new input line to help formatters produc .It Sy "invalid escape sequence" .Pq roff An escape sequence has an invalid opening argument delimiter, lacks the -closing argument delimiter, or the argument has too few characters. +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 @@ -1689,6 +1735,12 @@ and .Ic \ew to the length of the incomplete argument. All other invalid escape sequences are ignored. +.It Sy "undefined escape, printing literally" +.Pq roff +In an escape sequence, the first character +right after the leading backslash is invalid. +That character is printed literally, +which is equivalent to ignoring the backslash. .It Sy "undefined string, using \(dq\(dq" .Pq roff If a string is used without being defined before, @@ -2154,6 +2206,13 @@ implementations but not by .Nm was found in an input file. It is replaced by a question mark. +.It Sy "unsupported escape sequence" +.Pq roff +An input file contains an escape sequence supported by GNU troff +or Heirloom troff but not by +.Nm , +and it is likely that this will cause information loss +or considerable misformatting. .It Sy "unsupported roff request" .Pq roff An input file contains a