From owner-svn-doc-head@freebsd.org Fri Sep 29 20:47:44 2017 Return-Path: Delivered-To: svn-doc-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id BD239E34EFB; Fri, 29 Sep 2017 20:47:44 +0000 (UTC) (envelope-from wblock@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 mx1.freebsd.org (Postfix) with ESMTPS id 72A2D74E1D; Fri, 29 Sep 2017 20:47:44 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v8TKlh5n044848; Fri, 29 Sep 2017 20:47:43 GMT (envelope-from wblock@FreeBSD.org) Received: (from wblock@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v8TKlhTt044844; Fri, 29 Sep 2017 20:47:43 GMT (envelope-from wblock@FreeBSD.org) Message-Id: <201709292047.v8TKlhTt044844@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: wblock set sender to wblock@FreeBSD.org using -f From: Warren Block Date: Fri, 29 Sep 2017 20:47:43 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r50998 - in head/en_US.ISO8859-1/books/fdp-primer: . manpages X-SVN-Group: doc-head X-SVN-Commit-Author: wblock X-SVN-Commit-Paths: in head/en_US.ISO8859-1/books/fdp-primer: . manpages X-SVN-Commit-Revision: 50998 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 29 Sep 2017 20:47:44 -0000 Author: wblock Date: Fri Sep 29 20:47:43 2017 New Revision: 50998 URL: https://svnweb.freebsd.org/changeset/doc/50998 Log: Add an initial chapter about creating man pages. Much remains to be added, but at least there will be a place to add it. And of course there are bound to be numerous corrections, to which I say the quintessential BSD response: patches welcome! Sponsored by: iXsystems Added: head/en_US.ISO8859-1/books/fdp-primer/manpages/ head/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml (contents, props changed) Modified: head/en_US.ISO8859-1/books/fdp-primer/Makefile head/en_US.ISO8859-1/books/fdp-primer/book.xml head/en_US.ISO8859-1/books/fdp-primer/chapters.ent Modified: head/en_US.ISO8859-1/books/fdp-primer/Makefile ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/Makefile Fri Sep 29 11:19:08 2017 (r50997) +++ head/en_US.ISO8859-1/books/fdp-primer/Makefile Fri Sep 29 20:47:43 2017 (r50998) @@ -32,6 +32,7 @@ SRCS+= docbook-markup/chapter.xml SRCS+= stylesheets/chapter.xml SRCS+= translations/chapter.xml SRCS+= po-translations/chapter.xml +SRCS+= manpages/chapter.xml SRCS+= writing-style/chapter.xml SRCS+= editor-config/chapter.xml SRCS+= see-also/chapter.xml @@ -44,6 +45,10 @@ IMAGES_LIB+= callouts/2.png IMAGES_LIB+= callouts/3.png IMAGES_LIB+= callouts/4.png IMAGES_LIB+= callouts/5.png +IMAGES_LIB+= callouts/6.png +IMAGES_LIB+= callouts/7.png +IMAGES_LIB+= callouts/8.png +IMAGES_LIB+= callouts/9.png # Entities SRCS+= chapters.ent Modified: head/en_US.ISO8859-1/books/fdp-primer/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/book.xml Fri Sep 29 11:19:08 2017 (r50997) +++ head/en_US.ISO8859-1/books/fdp-primer/book.xml Fri Sep 29 20:47:43 2017 (r50998) @@ -261,6 +261,7 @@ The time is 09:18 &chap.stylesheets; &chap.translations; &chap.po-translations; + &chap.manpages; &chap.writing-style; &chap.editor-config; &chap.see-also; Modified: head/en_US.ISO8859-1/books/fdp-primer/chapters.ent ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/chapters.ent Fri Sep 29 11:19:08 2017 (r50997) +++ head/en_US.ISO8859-1/books/fdp-primer/chapters.ent Fri Sep 29 20:47:43 2017 (r50998) @@ -22,6 +22,7 @@ + Added: head/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml Fri Sep 29 20:47:43 2017 (r50998) @@ -0,0 +1,718 @@ + + + + + Manual Pages + + + Introduction + + Manual pages, commonly shortened to + man pages, were conceived as + readily-available reminders for command syntax, device driver + details, or configuration file formats. They have become an + extremely valuable quick-reference from the command line for + users, system administrators, and programmers. + + Although intended as reference material rather than + tutorials, the EXAMPLES sections of manual pages often + provide detailed use case. + + Manual pages are generally shown interactively by the + &man.man.1; command. When the user types + man ls, a search is performed for a manual + page matching ls. The first matching result + is displayed. + + + + Sections + + Manual pages are grouped into sections. + Each section contains manual pages for a specific category of + documentation: + + + + + + Section Number + Category + + + + + + 1 + General Commands + + + + 2 + System Calls + + + + 3 + Library Functions + + + + 4 + Kernel Interfaces + + + + 5 + File Formats + + + + 6 + Games + + + + 7 + Miscellaneous + + + + 8 + System Manager + + + + 9 + Kernel Developer + + + + + + + + Markup + + Various markup forms and rendering programs have been used + for manual pages. &os; has used &man.groff.7; and the newer + &man.mandoc.1;. Most existing &os; manual pages, and all new + ones, use the &man.mdoc.7; form of markup. This is a simple + line-based markup that is reasonably expressive. It is mostly + semantic: parts of text are marked up for what they are, rather + than for they should appear when rendered. There is some + appearance-based markup which is usually best avoided. + + Manual page source is usually interpreted and displayed to + the screen interactively. The source files can be ordinary text + files or compressed with &man.gzip.1; to save space. + + Manual pages can also be rendered to other formats, + including PostScript for printing or PDF + generation. See &man.man.1;. + + + Testing a new manual page can be challenging when it is + not located in the normal manual page search path. + &man.man.1; also does not look in the current directory. If + the new manual page is in the current directory, prefix + the filename with a ./: + + &prompt.user; man ./mynewmanpage.8 + + An absolute path can also be used: + + &prompt.user; man /home/xsmith/mynewmanpage.8 + + + + + Manual Page Sections + + Manual pages are composed of several standard sections. + Each section has a title in upper case, and the sections for a + particular type of manual page appear in a specific order. + For a category 1 General Command manual page, the sections + are: + + + + + + Section Name + Description + + + + + + NAME + Name of the command + + + + SYNOPSIS + Format of options and arguments + + + + DESCRIPTION + Description of purpose and usage + + + + ENVIRONMENT + Environment settings that affect + operation + + + + EXIT STATUS + Error codes returned on exit + + + + EXAMPLES + Examples of usage + + + + COMPATIBILITY + Compatibility with other implementations + + + + SEE ALSO + Cross-reference to related manual pages + + + + STANDARDS + Compatibility with standards like POSIX + + + + HISTORY + History of implementation + + + + BUGS + Known bugs + + + + AUTHORS + People who created the command or wrote the + manual page. + + + + + + Some sections are optional, and the combination of + sections for a specific type of manual page vary. Examples of + the most common types are shown later in this chapter. + + + + Macros + + &man.mdoc.7; markup is based on + macros. Lines that begin with a dot + contain macro commands, each two or three letters long. For + example, consider this portion of the &man.ls.1; manual + page: + + +.Dd December 1, 2015 +.Dt LS 1 +.Sh NAME +.Nm ls +.Nd list directory contents +.Sh SYNOPSIS +.Nm +.Op Fl -libxo +.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1, +.Op Fl D Ar format +.Op Ar +.Sh DESCRIPTION +For each operand that names a +.Ar file +of a type other than +directory, +.Nm +displays its name as well as any requested, +associated information. +For each operand that names a +.Ar file +of type directory, +.Nm +displays the names of files contained +within that directory, as well as any requested, associated +information. + + + + A Document date and + Document title are defined. + + + + A Section header for the NAME + section is defined. Then the Name + of the command and a one-line + Name description are defined. + + + + The SYNOPSIS section begins. This section describes + the command-line options and arguments accepted. + + + + Name (.Nm) has + already been defined, and repeating it here just displays + the defined value in the text. + + + + An Optional + Flag called -libxo + is shown. The Fl macro adds a dash to + the beginning of flags, so this appears in the manual + page as --libxo. + + + + A long list of optional single-character flags are + shown. + + + + An optional -D flag is defined. If + the -D flag is given, it must be + followed by an Argument. The + argument is a format, a string that + tells &man.ls.1; what to display and how to display it. + Details on the format string are given later in the manual + page. + + + + A final optional argument is defined. Because no name + is specified for the argument, the default of + file ... is used. + + + + The Section header for the + DESCRIPTION section is defined. + + + + When rendered with the command man ls, + the result displayed on the screen looks like this: + + LS(1) FreeBSD General Commands Manual LS(1) + +NAME + ls — list directory contents + +SYNOPSIS + ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format] + [file ...] + +DESCRIPTION + For each operand that names a file of a type other than directory, ls + displays its name as well as any requested, associated information. For + each operand that names a file of type directory, ls displays the names + of files contained within that directory, as well as any requested, + associated information. + + Optional values are shown inside square brackets. + + + + Markup Guidelines + + The &man.mdoc.7; markup language is not very strict. For + clarity and consistency, the &os; Documentation project adds + some additional style guidelines: + + + + Only the first letter of macros is upper case + + + Always use upper case for the first letter of a + macro and lower case for the remaining letters. + + + + + Begin new sentences on new lines + + + Start a new sentence on a new line, do not begin it + on the same line as an existing sentence. + + + + + Update .Dd when making non-trivial + changes to a manual page + + + The Document date informs the + reader about the last time the manual page was updated. + It is important to update whenever non-trivial changes + are made to the manual pages. Trivial changes like + spelling or punctuation fixes that do not affect usage + can be made without updating + .Dd. + + + + + Give examples + + + Show the reader examples when possible. Even + trivial examples are valuable, because what is trivial + to the writer is not necessarily trivial to the reader. + Three examples are a good goal. A trivial example shows + the minimal requirements, a serious example shows actual + use, and an in-depth example demonstrates unusual or + non-obvious functionality. + + + + + Include the BSD license + + + Include the BSD license on new manual pages. The + preferred license is available from the Committer's + Guide. + + + + + + + Markup Tricks + + Add a space before punctuation on a line with + macros. Example: + + .Sh SEE ALSO +.Xr geom 4 , +.Xr boot0cfg 8 , +.Xr geom 8 , +.Xr gptboot 8 + + Note how the commas at the end of the + .Xr lines have been placed after a space. + The .Xr macro expects two parameters to + follow it, the name of an external manual page, and a section + number. The space separates the punctuation from the section + number. Without the spacee, the external links would + incorrectly point to section 4, or + 8,. + + + + Important Macros + + Some very common macros will be shown here. For + more usage examples, see &man.mdoc.7;, &man.groff.mdoc.7;, or + search for actual use in + /usr/share/man/man* directories. For + example, to search for examples of the .Bd + Begin display macro: + + &prompt.user; find /usr/share/man/man* | xargs zgrep '.Bd' + + + Organizational Macros + + Some macros are used to define logical blocks of a + manual page. + + + + + + Organizational Macro + Use + + + + + + .Sh + Section header. Followed by the name of + the section, traditionally all upper case. + Think of these as chapter titles. + + + + .Ss + Subsection header. Followed by the name of + the subsection. Used to divide a + .Sh section into + subsections. + + + + .Bl + Begin list. Start a list of items. + + + + .El + End a list. + + + + .Bd + Begin display. Begin a special area of + text, like an indented area. + + + + .Ed + End display. + + + + + + + + Inline Macros + + Many macros are used to mark up inline text. + + + + + + Inline Macro + Use + + + + + + .Nm + Name. Called with a name as a parameter on the + first use, then used later without the parameter to + display the name that has already been + defined. + + + + .Pa + Path to a file. Used to mark up filenames and + directory paths. + + + + + + + + + + Sample Manual Page Structures + + This section shows minimal desired man page contents for + several common categories of manual pages. + + + Section 1 or 8 Command + + The preferred basic structure for a section 1 or 8 + command: + + .Dd August 25, 2017 +.Dt EXAMPLECMD 8 +.Os +.Sh NAME +.Nm examplecmd +.Nd "command to demonstrate section 1 and 8 man pages" +.Sh SYNOPSIS +.Nm +.Op Fl v +.Sh DESCRIPTION +The +.Nm +utility does nothing except demonstrate a trivial but complete +manual page for a section 1 or 8 command. +.Sh SEE ALSO +.Xr exampleconf 5 +.Sh AUTHORS +.An Firstname Lastname Aq Mt flastname@example.com + + + + Section 4 Device Driver + + The preferred basic structure for a section 4 device + driver: + + .Dd August 25, 2017 +.Dt EXAMPLEDRIVER 4 +.Os +.Sh NAME +.Nm exampledriver +.Nd "driver to demonstrate section 4 man pages" +.Sh SYNOPSIS +To compile this driver into the kernel, add this line to the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device exampledriver" +.Ed +.Pp +To load the driver as a module at boot, add this line to +.Xr loader.conf 5 : +.Bd -literal -offset indent +exampledriver_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides an opportunity to show a skeleton or template +file for section 4 manual pages. +.Sh HARDWARE +The +.Nm +driver supports these cards from the aptly-named Nonexistent +Technologies: +.Pp +.Bl -bullet -compact +.It +NT X149.2 (single and dual port) +.It +NT X149.8 (single port) +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "flashing green light" +Something bad happened. +.It "flashing red light" +Something really bad happened. +.It "solid black light" +Power cord is unplugged. +.El +.Sh SEE ALSO +.Xr example 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 49.2 . +.Sh AUTHORS +.An Firstname Lastname Aq Mt flastname@example.com + + + + Section 5 Configuration File + + The preferred basic structure for a section 5 + configuration file: + + .Dd August 25, 2017 +.Dt EXAMPLECONF 5 +.Os +.Sh NAME +.Nm example.conf +.Nd "config file to demonstrate section 5 man pages" +.Sh DESCRIPTION +.Nm +is an example configuration file. +.Sh SEE ALSO +.Xr example 8 +.Sh AUTHORS +.An Firstname Lastname Aq Mt flastname@example.com + + + + + Example Manual Pages to use as Templates + + Some manual pages are suitable as in-depth examples. + + + + + + Manual Page + Path to Source Location + + + + + + &man.cp.1; + /usr/src/bin/cp/cp.1 + + + + &man.vt.4; + /usr/src/share/man/man4/vt.4 + + + + &man.crontab.5; + /usr/src/usr.sbin/cron/crontab/crontab.5 + + + + &man.gpart.8; + /usr/src/sbin/geom/class/part/gpart.8 + + + + + + + + Resources + + Resources for manual page writers: + + + + &man.man.1; + + + + &man.mandoc.1; + + + + &man.groff.mdoc.7; + + + + Practical + UNIX Manuals: mdoc + + + + History + of UNIX Manpages + + + +