Index: head/share/man/man5/Makefile =================================================================== --- head/share/man/man5/Makefile (revision 342577) +++ head/share/man/man5/Makefile (revision 342578) @@ -1,114 +1,115 @@ # @(#)Makefile 8.1 (Berkeley) 6/5/93 # $FreeBSD$ .include PACKAGE=runtime-manuals #MISSING: dump.5 plot.5 MAN= acct.5 \ ar.5 \ a.out.5 \ ${_boot.config.5} \ cd9660.5 \ core.5 \ devfs.5 \ devfs.conf.5 \ devfs.rules.5 \ device.hints.5 \ dir.5 \ disktab.5 \ elf.5 \ ethers.5 \ eui64.5 \ ext2fs.5 \ fbtab.5 \ fdescfs.5 \ forward.5 \ fs.5 \ fstab.5 \ group.5 \ hosts.5 \ hosts.equiv.5 \ hosts.lpd.5 \ intro.5 \ libmap.conf.5 \ link.5 \ linprocfs.5 \ linsysfs.5 \ mailer.conf.5 \ make.conf.5 \ moduli.5 \ motd.5 \ mount.conf.5 \ mqueuefs.5 \ msdosfs.5 \ networks.5 \ nsmb.conf.5 \ nsswitch.conf.5 \ nullfs.5 \ passwd.5 \ pbm.5 \ periodic.conf.5 \ phones.5 \ portindex.5 \ portsnap.conf.5 \ procfs.5 \ protocols.5 \ quota.user.5 \ rc.conf.5 \ rctl.conf.5 \ regdomain.5 \ remote.5 \ resolver.5 \ services.5 \ shells.5 \ src.conf.5 \ stab.5 \ style.Makefile.5 \ + style.mdoc.5 \ sysctl.conf.5 \ tmpfs.5 MLINKS= dir.5 dirent.5 MLINKS+=fs.5 inode.5 MLINKS+=hosts.equiv.5 rhosts.5 MLINKS+=msdosfs.5 msdos.5 MLINKS+=passwd.5 master.passwd.5 MLINKS+=portindex.5 INDEX.5 MLINKS+=quota.user.5 quota.group.5 MLINKS+=rc.conf.5 rc.conf.local.5 MLINKS+=resolver.5 resolv.conf.5 MLINKS+=src.conf.5 src-env.conf.5 .if ${MK_AUTOFS} != "no" MAN+= autofs.5 .endif .if ${MK_BLUETOOTH} != "no" MAN+= bluetooth.device.conf.5 \ bluetooth.hosts.5 \ bluetooth.protocols.5 .endif .if ${MK_FREEBSD_UPDATE} != "no" MAN+= freebsd-update.conf.5 .endif .if ${MK_HESIOD} != "no" MAN+= hesiod.conf.5 .endif .if ${MK_NAND} != "no" MAN+= nandfs.5 .endif .if ${MK_PF} != "no" MAN+= pf.conf.5 \ pf.os.5 .endif .if ${MACHINE_CPUARCH} == "amd64" || ${MACHINE_CPUARCH} == "i386" _boot.config.5= boot.config.5 .endif .include Index: head/share/man/man5/style.mdoc.5 =================================================================== --- head/share/man/man5/style.mdoc.5 (nonexistent) +++ head/share/man/man5/style.mdoc.5 (revision 342578) @@ -0,0 +1,205 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD +.\" +.\" Copyright (c) 2018 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 28, 2018 +.Dt STYLE.MDOC 5 +.Os +.Sh NAME +.Nm style.mdoc +.Nd +.Fx +.Xr mdoc 7 +file style guide +.Sh DESCRIPTION +This file specifies the preferred style for manual pages in the +.Fx +source tree. +.Ss Code examples +.Bl -dash -width "" +.It +Use literal formatting for examples and literal shell commands, e.g.: +.Bd -literal -offset indent +Then run +\&.Dq Li make install clean . +.Ed +.Pp +which renders as: +.Bd -filled -offset indent +Then run +.Dq Li make install clean . +.Ed +.Pp +The incorrect way would be to use macros like +.Sy \&Nm +to stylize the command invocation: +.Bd -literal -offset indent +Then run +\&.Dq Nm make Cm install Cm clean . +.Ed +.Pp +which renders as: +.Bd -filled -offset indent +Then run +.Dq Nm make Cm install Cm clean . +.Ed +.El +.Ss Synopsis formatting +.Bl -dash -width "" +.It +Do not put whitespace between alternative parameters separated with a pipe +.Pq Dq | , +e.g.: +.Bd -literal -offset indent +\&.Cm compression Cm on Ns | Ns Cm off +\&.Cm install Fl -all Ns | Ns Ar portname Ar ... +.Ed +.Pp +which in the SYNOPSIS section is rendered as: +.Bd -unfilled -offset indent +.Cm compression Cm on Ns | Ns Cm off +.Cm install Fl -all Ns | Ns Ar portname Ar ... +.Ed +.It +Use +.Sy \&Cm +to stylize characters that are command modifiers +.Po e.g., +.Dq \&, , +.Dq @ +or +.Dq "=" +.Pc . +For example: +.Bd -literal -offset indent +\&.Sm off +\&.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where +\&.Sm on +.Ed +.Pp +which renders as: +.Bd -filled -offset indent +.Sm off +.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where +.Sm on +.Ed +.Pp +instead of: +.Bd -literal -offset indent +\&.Sm off +\&.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where +\&.Sm on +.Ed +.Pp +which would render as: +.Bd -filled -offset indent +.Sm off +.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where +.Sm on +.Ed +.Pp +It is important to realize that in the correct example, +.Dq \&, , +.Dq @ +and +.Dq = +are stylized with +.Sy \&Cm . +At the same time, the square brackets +.Pq Dq "[]" +are not stylized as they do not belong to the syntax of the +.Fl -meet +flag. +.El +.Ss Quoting +.Bl -dash -width "" +.It +Use the +.Sy \&Dq +.Pq Do Dc +macro +for quoting. +Use the +.Sy \&Sq +.Pq So Sc +macro for quoting inside quotes. +The use of the +.Sy \&Qq +.Pq Qo Qc +macro is usually not necessary. +.El +.Ss Variables +.Bl -dash -width "" +.It +Use +.Sy \&Va +instead of: +.Sy \&Dv +for +.Xr sysctl 8 +variables like +.Va kdb.enter.panic . +.It +Use the angle brackets +.Sy \&Aq +.Pq Dq "<>" +macro +for arguments +.Pq Sy \&Ar +when they are mixed with similarly stylized macros like +.Sy \&Pa +or +.Sy \&Va , +e.g.: +.Bd -literal -offset indent +\&.Va critical_filesystems_ Ns Aq Ar type +.Ed +.Pp +which renders as: +.Bd -filled -offset indent +.Va critical_filesystems_ Ns Aq Ar type +.Ed +.Pp +instead of: +.Bd -literal -offset indent +\&.Va critical_filesystems_ Ns Ar type +.Ed +.Pp +that would be rendered as: +.Bd -filled -offset indent +.Va critical_filesystems_ Ns Ar type +.Ed +.El +.Sh SEE ALSO +.Xr man 1 , +.Xr mandoc 1 , +.Xr mdoc 7 +.Sh HISTORY +This manual page first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org Property changes on: head/share/man/man5/style.mdoc.5 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property