From owner-svn-src-head@freebsd.org Sat Dec 29 23:00:21 2018 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 51BC5142FD62; Sat, 29 Dec 2018 23:00:21 +0000 (UTC) (envelope-from 0mp@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id EAC4988F18; Sat, 29 Dec 2018 23:00:20 +0000 (UTC) (envelope-from 0mp@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id CAFD219B7F; Sat, 29 Dec 2018 23:00:20 +0000 (UTC) (envelope-from 0mp@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id wBTN0K0Z015009; Sat, 29 Dec 2018 23:00:20 GMT (envelope-from 0mp@FreeBSD.org) Received: (from 0mp@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id wBTN0Kk3015008; Sat, 29 Dec 2018 23:00:20 GMT (envelope-from 0mp@FreeBSD.org) Message-Id: <201812292300.wBTN0Kk3015008@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: 0mp set sender to 0mp@FreeBSD.org using -f From: Mateusz Piotrowski <0mp@FreeBSD.org> Date: Sat, 29 Dec 2018 23:00:20 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r342600 - head/share/man/man5 X-SVN-Group: head X-SVN-Commit-Author: 0mp X-SVN-Commit-Paths: head/share/man/man5 X-SVN-Commit-Revision: 342600 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Rspamd-Queue-Id: EAC4988F18 X-Spamd-Bar: -- Authentication-Results: mx1.freebsd.org X-Spamd-Result: default: False [-2.95 / 15.00]; local_wl_from(0.00)[FreeBSD.org]; NEURAL_HAM_MEDIUM(-1.00)[-0.999,0]; NEURAL_HAM_SHORT(-0.95)[-0.955,0]; NEURAL_HAM_LONG(-1.00)[-0.998,0]; ASN(0.00)[asn:11403, ipnet:2610:1c1:1::/48, country:US] X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 29 Dec 2018 23:00:21 -0000 Author: 0mp (ports committer) Date: Sat Dec 29 23:00:20 2018 New Revision: 342600 URL: https://svnweb.freebsd.org/changeset/base/342600 Log: 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 Modified: head/share/man/man5/style.mdoc.5 Modified: head/share/man/man5/style.mdoc.5 ============================================================================== --- head/share/man/man5/style.mdoc.5 Sat Dec 29 21:36:02 2018 (r342599) +++ head/share/man/man5/style.mdoc.5 Sat Dec 29 23:00:20 2018 (r342600) @@ -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