=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.260 retrieving revision 1.266 diff -u -p -r1.260 -r1.266 --- mandoc/mandoc.1 2022/06/07 09:54:40 1.260 +++ mandoc/mandoc.1 2023/10/24 20:53:12 1.266 @@ -1,6 +1,6 @@ -.\" $Id: mandoc.1,v 1.260 2022/06/07 09:54:40 schwarze Exp $ +.\" $Id: mandoc.1,v 1.266 2023/10/24 20:53:12 schwarze Exp $ .\" -.\" Copyright (c) 2012, 2014-2022 Ingo Schwarze +.\" Copyright (c) 2012, 2014-2023 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 7 2022 $ +.Dd $Mdocdate: October 24 2023 $ .Dt MANDOC 1 .Os .Sh NAME @@ -342,21 +342,9 @@ 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. -.Pp -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 -defaults to simple output (via an embedded style-sheet) -readable in any graphical or text-based web -browser. -.Pp Non-ASCII characters are rendered as hexadecimal Unicode character references. .Pp @@ -407,9 +395,49 @@ otherwise, the second format is used. .It Cm style Ns = Ns Ar style.css The file .Ar style.css -is used for an external style-sheet. +is used as an external stylesheet. This must be a valid absolute or relative URI. +.Pp +Using the file +.Pa mandoc.css +that is distributed with +.Nm +is recommended. +It provides an appearance similar to terminal output with some additional +features specific to +.Nm +HTML output, in particular making anchor locations that support +deep linking stand out visually by putting a dotted line under them, +providing tooltips showing the semantic function of elements (macro +names), providing some simple aspects of responsive web design, and +providing simple support for users who prefer a dark color scheme. +.Pp +Using a custom CSS file is possible, but writing it requires +proficiency in all of the languages HTML 5, CSS 4, and +.Xr mdoc 7 +and familiarity with the +.Nm Ns -specific +classes used in +.Pa mandoc.css . +Besides, while the file +.Pa mandoc.css +is always adapted to the HTML output generated by the +.Nm +version it is distributed with, maintaining a custom CSS file usually +requires adaptations each time +.Nm +is upgraded to a new version. +.Pp +If a stylesheet is not specified with +.Fl O Cm style , +.Fl T Cm html +embeds a minimal stylesheet into the HTML output, mostly to select +adequate font-style and font-weight attributes for various macros. +The result is readable in any graphical or text-based web browser, +but does not aim for looking similar to terminal output. +Instead, formatting is mostly left to browser defaults +and to user settings in the browser configuration. .It Cm tag Ns Op = Ns Ar term Same syntax and semantics as for .Sx ASCII Output . @@ -739,7 +767,7 @@ To page manuals to the terminal: .Pp To produce HTML manuals with .Pa /usr/share/misc/mandoc.css -as the style-sheet: +as the stylesheet: .Pp .Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html .Pp @@ -766,7 +794,7 @@ Messages displayed by follow this format: .Bd -ragged -offset indent .Nm : -.Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments +.Ar file : Ns Ar line : Ns Ar column : level : message : macro argument ... .Pq Ar os .Ed .Pp @@ -786,9 +814,7 @@ and strings are explained below. The name of the .Ar macro -triggering the message and its -.Ar arguments -are omitted where meaningless. +triggering the message and its arguments are omitted where meaningless. The .Ar os operating system specifier is omitted for messages that are relevant @@ -1269,9 +1295,11 @@ The same standard section title occurs more than once. A standard section header occurs in a section of the manual where it normally isn't useful. .It Sy "cross reference to self" -.Pq mdoc +.Pq mdoc , man An .Ic \&Xr +or +.Ic \&MR macro refers to a name and section matching the section of the present manual page and a name mentioned in an .Ic \&Nm @@ -1474,10 +1502,8 @@ A .Ic \&Bl , .Ic \&D1 , .Ic \&Dl , -.Ic \&MT , -.Ic \&RS , or -.Ic \&UR +.Ic \&RS block contains nothing in its body and will produce no output. .It Sy "empty argument, using 0n" .Pq mdoc @@ -1592,12 +1618,16 @@ macro is immediately followed by an macro on the next input line. Such an empty block does not produce any output. .It Sy "missing section argument" -.Pq mdoc +.Pq mdoc , man An .Ic \&Xr +or +.Ic \&MR macro lacks its second, section number argument. -The first argument, i.e. the name, is printed, but without subsequent -parentheses. +The first argument, i.e. the name, is printed, but without a section number. +In the case of +.Ic \&Xr , +the parentheses are also omitted. .It Sy "missing -std argument, adding it" .Pq mdoc An @@ -2128,10 +2158,12 @@ 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 +.Pq mdoc , man The first call to .Ic \&Nm , -or any call in the NAME section, lacks the required argument. +or any call in the NAME section, lacks the required argument, or +.Ic \&MR +is called without any argument. .It Sy "uname(3) system call failed, using UNKNOWN" .Pq mdoc The @@ -2259,6 +2291,8 @@ or a request of the family with more than two arguments .It .Ic \&Dt +or +.Ic \&MR with more than three arguments .It .Ic \&TH @@ -2321,7 +2355,7 @@ attempts to employ one of the characters 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 charcters can be used as argument delimiters, +While various characters can be used as argument delimiters, using the apostrophe-quote character .Pq Sq \(aq is recommended for readability and robustness.