=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.263 retrieving revision 1.266 diff -u -p -r1.263 -r1.266 --- mandoc/mandoc.1 2022/08/02 12:02:28 1.263 +++ mandoc/mandoc.1 2023/10/24 20:53:12 1.266 @@ -1,6 +1,6 @@ -.\" $Id: mandoc.1,v 1.263 2022/08/02 12:02:28 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: August 2 2022 $ +.Dd $Mdocdate: October 24 2023 $ .Dt MANDOC 1 .Os .Sh NAME @@ -345,17 +345,6 @@ conforms to HTML5 using optional self-closing tags. 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 @@ -406,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 . @@ -738,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 @@ -765,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 @@ -785,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 @@ -1268,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 @@ -1589,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 @@ -2125,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 @@ -2256,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