On Sat, 03 Nov 2018 14:00:51 -0700, Sean Whitton wrote: > Hence I am seeking seconds for this patch I've written: > > diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst > index e990f34..a9b297f 100644 > --- a/policy/ch-docs.rst > +++ b/policy/ch-docs.rst > @@ -61,6 +61,12 @@ by a note at the beginning of the manual page or by > showing the missing > or changed portions in the original language instead of the target > language. > > +It is recommended that manual pages contain an EXAMPLES section, > +containing working syntax that uses the functionality documented by > +the manual page. For example, command-line invocations of a utility > +for some of its standard usages, or an example call to an API > +function. > + > .. _s12.2: > > Info documents
No objections from me, just 2 nits: - The typical .3pm manpage (for perl modules) doesn't contain an EXAMPLES section but contains working and copypastable code in the SYNOPSIS section. [0] - I'm not really convinced that a "duty" to patch upstream manpages in order to add EXAMPLE sections, which would follow from this recommendation, is sustainable or desirable … Cheers, gregor [0] If you're interested in an amendment, maybe: "It is recommended that manual pages contain examples of working syntax that uses the functionality documented by the manual page. For example, …" or "It is recommended that manual pages contain examples of working syntax, e.g. in an EXAMPLES section, that uses the functionality documented by the manual page. For example, …" -- .''`. https://info.comodo.priv.at -- Debian Developer https://www.debian.org : :' : OpenPGP fingerprint D1E1 316E 93A7 60A8 104D 85FA BB3A 6801 8649 AA06 `. `' Member VIBE!AT & SPI Inc. -- Supporter Free Software Foundation Europe `- NP: Billy Joel: Captan Jack
signature.asc
Description: Digital Signature
