diff options
| author | Mateusz Piotrowski <0mp@FreeBSD.org> | 2018-12-29 23:00:20 +0000 |
|---|---|---|
| committer | Mateusz Piotrowski <0mp@FreeBSD.org> | 2018-12-29 23:00:20 +0000 |
| commit | e84f64558443c2eab27edc69fe91f402adaaeaa8 (patch) | |
| tree | df2bc47bba11c7dc7582f66c1ef511959e666ba2 /share/man/man5 | |
| parent | 4ae4822d6ac27e9fe4deb63b8d3b1e3515565a64 (diff) | |
| download | src-e84f64558443c2eab27edc69fe91f402adaaeaa8.tar.gz src-e84f64558443c2eab27edc69fe91f402adaaeaa8.zip | |
style.mdoc.5: Suggest preferred formatting for EXAMPLES
Add an example of how to format examples in EXAMPLES sections. The
suggested format is heavily based on zfs.8.
While here, capitalize subsection titles.
Reviewed by: bcr
Approved by: bcr (doc),
Approved by: krion (mentor, implicit), mat (mentor, implicit)
Differential Revision: https://reviews.freebsd.org/D18681
Notes
Notes:
svn path=/head/; revision=342600
Diffstat (limited to 'share/man/man5')
| -rw-r--r-- | share/man/man5/style.mdoc.5 | 52 |
1 files changed, 49 insertions, 3 deletions
diff --git a/share/man/man5/style.mdoc.5 b/share/man/man5/style.mdoc.5 index 89f8ee7377f9..39c2961aefd6 100644 --- a/share/man/man5/style.mdoc.5 +++ b/share/man/man5/style.mdoc.5 @@ -26,7 +26,7 @@ .\" .\" $FreeBSD$ .\" -.Dd December 28, 2018 +.Dd December 29, 2018 .Dt STYLE.MDOC 5 .Os .Sh NAME @@ -39,7 +39,7 @@ file style guide This file specifies the preferred style for manual pages in the .Fx source tree. -.Ss Code examples +.Ss Code Examples .Bl -dash -width "" .It Use literal formatting for examples and literal shell commands, e.g.: @@ -68,7 +68,53 @@ Then run .Dq Nm make Cm install Cm clean . .Ed .El -.Ss Synopsis formatting +.Ss EXAMPLES Section +.Bl -dash -width "" +.It +Format the +.Sx EXAMPLES +section in the following way: +.Bd -literal -offset indent +\&.Bl -tag -width 0n +\&.It Sy Example 1\&: No Doing Something +\&.Pp +The following command does something. +\&.Bd -literal -offset 2n +\&.Li # Ic make -VLEGAL +\&.Ed +\&.It Sy Example 2\&: No Doing Something Different +\&.Pp +The following command does something different. +\&.Bd -literal -offset 2n +\&.Li # Ic bectl list +\&.Ed +\&.Pp +It is good to know this command. +\&.El +\&.El +.Ed +.Pp +which renders as: +.Bd -filled -offset indent +.Bl -tag -width 0n +.It Sy Example 1\&: No Doing Something +.Pp +The following command does something. +.Bd -literal -offset 2n +.Li # Ic make -VLEGAL +.Ed +.It Sy Example 2\&: No Doing Something Different +.Pp +The following command does something different. +.Bd -literal -offset 2n +.Li # Ic bectl list +.Ed +.Pp +It is good to know this command. +.El +.Ed +.El +.Ss Synopsis Formatting .Bl -dash -width "" .It Do not put whitespace between alternative parameters separated with a pipe |