From 56d99a3fbc92bde013f63372fca596d4070d877c Mon Sep 17 00:00:00 2001 From: schwarze Date: Sun, 28 Dec 2014 15:22:42 +0000 Subject: [PATCH] Improve documentation of the header/footer macros .Dt, .Os, .TH: * State the defaults for .Os and the fourth .TH argument. * Sync the section titles, and stop advertising obscure sections that aren't actually fully supported and certainly not recommended for use. --- share/man/man7/man.7 | 12 ++++++++--- share/man/man7/mdoc.7 | 50 ++++++++++++++++++++----------------------- 2 files changed, 32 insertions(+), 30 deletions(-) diff --git a/share/man/man7/man.7 b/share/man/man7/man.7 index f29616e337a..e1344a8948a 100644 --- a/share/man/man7/man.7 +++ b/share/man/man7/man.7 @@ -1,4 +1,4 @@ -.\" $OpenBSD: man.7,v 1.39 2014/06/22 16:39:07 schwarze Exp $ +.\" $OpenBSD: man.7,v 1.40 2014/12/28 15:22:42 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons .\" Copyright (c) 2011, 2012, 2013 Ingo Schwarze @@ -16,7 +16,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 22 2014 $ +.Dd $Mdocdate: December 28 2014 $ .Dt MAN 7 .Os .Sh NAME @@ -607,7 +607,8 @@ The scope of a sub-section is closed by a subsequent sub-section, section, or end of file. The paragraph left-margin width is reset to the default. .Ss \&TH -Sets the title of the manual page with the following syntax: +Sets the title of the manual page for use in the page header +and footer with the following syntax: .Bd -filled -offset indent .Pf \. Sx \&TH .Ar title section date @@ -629,6 +630,11 @@ is empty or not specified, the current date is used. The optional .Ar source string specifies the organisation providing the utility. +When unspecified, +.Xr mandoc 1 +uses its +.Fl Ios +argument. The .Ar volume string replaces the default rendered volume, which is dictated by the diff --git a/share/man/man7/mdoc.7 b/share/man/man7/mdoc.7 index f3ca5991d3e..029bc59d5b3 100644 --- a/share/man/man7/mdoc.7 +++ b/share/man/man7/mdoc.7 @@ -1,4 +1,4 @@ -.\" $OpenBSD: mdoc.7,v 1.126 2014/11/30 21:54:53 schwarze Exp $ +.\" $OpenBSD: mdoc.7,v 1.127 2014/12/28 15:22:42 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2010, 2011, 2013 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 30 2014 $ +.Dd $Mdocdate: December 28 2014 $ .Dt MDOC 7 .Os .Sh NAME @@ -1314,38 +1314,26 @@ it should by convention be all caps. The manual section. This may be one of .Cm 1 -.Pq utilities , +.Pq General Commands , .Cm 2 -.Pq system calls , +.Pq System Calls , .Cm 3 -.Pq libraries , +.Pq Library Functions , .Cm 3p -.Pq Perl libraries , +.Pq Perl Library , .Cm 4 -.Pq devices , +.Pq Device Drivers , .Cm 5 -.Pq file formats , +.Pq File Formats , .Cm 6 -.Pq games , +.Pq Games , .Cm 7 -.Pq miscellaneous , +.Pq Miscellaneous Information , .Cm 8 -.Pq system utilities , -.Cm 9 -.Pq kernel functions , -.Cm X11 -.Pq X Window System , -.Cm X11R6 -.Pq X Window System , -.Cm unass -.Pq unassociated , -.Cm local -.Pq local system , -.Cm draft -.Pq draft manual , +.Pq System Manager's Manual , or -.Cm paper -.Pq paper . +.Cm 9 +.Pq Kernel Developer's Manual . It should correspond to the manual's filename suffix and defaults to the empty string if unspecified. .It Ar arch @@ -2120,8 +2108,16 @@ Its syntax is as follows: The optional .Ar system parameter specifies the relevant operating system or environment. -Left unspecified, it defaults to the local operating system version. -This is the suggested form. +It is suggested to leave it unspecified, in which case +.Xr mandoc 1 +uses its +.Fl Ios +argument, or, if that isn't specified either, +.Fa sysname +and +.Fa release +as returned by +.Xr uname 3 . .Pp Examples: .Dl \&.Os -- 2.20.1