svn commit: r50998 - in head/en_US.ISO8859-1/books/fdp-primer: . manpages
Warren Block <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
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</screen></entry> &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 @@ <!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml"> <!ENTITY chap.translations SYSTEM "translations/chapter.xml"> <!ENTITY chap.po-translations SYSTEM "po-translations/chapter.xml"> +<!ENTITY chap.manpages SYSTEM "manpages/chapter.xml"> <!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml"> <!ENTITY chap.editor-config SYSTEM "editor-config/chapter.xml"> <!ENTITY chap.see-also SYSTEM "see-also/chapter.xml"> 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 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- + The FreeBSD Documentation Project +--> +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:id="manpages"> + + <title>Manual Pages</title> + + <sect1 xml:id="manpages-introduction"> + <title>Introduction</title> + + <para><emphasis>Manual pages</emphasis>, commonly shortened to + <emphasis>man pages</emphasis>, 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.</para> + + <para>Although intended as reference material rather than + tutorials, the EXAMPLES sections of manual pages often + provide detailed use case.</para> + + <para>Manual pages are generally shown interactively by the + &man.man.1; command. When the user types + <command>man ls</command>, a search is performed for a manual + page matching <literal>ls</literal>. The first matching result + is displayed.</para> + </sect1> + + <sect1 xml:id="manpages-sections"> + <title>Sections</title> + + <para>Manual pages are grouped into <emphasis>sections</emphasis>. + Each section contains manual pages for a specific category of + documentation:</para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Section Number</entry> + <entry>Category</entry> + </row> + </thead> + + <tbody> + <row> + <entry>1</entry> + <entry>General Commands</entry> + </row> + + <row> + <entry>2</entry> + <entry>System Calls</entry> + </row> + + <row> + <entry>3</entry> + <entry>Library Functions</entry> + </row> + + <row> + <entry>4</entry> + <entry>Kernel Interfaces</entry> + </row> + + <row> + <entry>5</entry> + <entry>File Formats</entry> + </row> + + <row> + <entry>6</entry> + <entry>Games</entry> + </row> + + <row> + <entry>7</entry> + <entry>Miscellaneous</entry> + </row> + + <row> + <entry>8</entry> + <entry>System Manager</entry> + </row> + + <row> + <entry>9</entry> + <entry>Kernel Developer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1 xml:id="manpages-markup"> + <title>Markup</title> + + <para>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.</para> + + <para>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.</para> + + <para>Manual pages can also be rendered to other formats, + including PostScript for printing or <acronym>PDF</acronym> + generation. See &man.man.1;.</para> + + <tip> + <para>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 <literal>./</literal>:</para> + + <screen>&prompt.user; <userinput>man ./mynewmanpage.8</userinput></screen> + + <para>An absolute path can also be used:</para> + + <screen>&prompt.user; <userinput>man /home/xsmith/mynewmanpage.8</userinput></screen> + </tip> + + + <sect2 xml:id="manpages-markup-sections"> + <title>Manual Page Sections</title> + + <para>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:</para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Section Name</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry>NAME</entry> + <entry>Name of the command</entry> + </row> + + <row> + <entry>SYNOPSIS</entry> + <entry>Format of options and arguments</entry> + </row> + + <row> + <entry>DESCRIPTION</entry> + <entry>Description of purpose and usage</entry> + </row> + + <row> + <entry>ENVIRONMENT</entry> + <entry>Environment settings that affect + operation</entry> + </row> + + <row> + <entry>EXIT STATUS</entry> + <entry>Error codes returned on exit</entry> + </row> + + <row> + <entry>EXAMPLES</entry> + <entry>Examples of usage</entry> + </row> + + <row> + <entry>COMPATIBILITY</entry> + <entry>Compatibility with other implementations</entry> + </row> + + <row> + <entry>SEE ALSO</entry> + <entry>Cross-reference to related manual pages</entry> + </row> + + <row> + <entry>STANDARDS</entry> + <entry>Compatibility with standards like POSIX</entry> + </row> + + <row> + <entry>HISTORY</entry> + <entry>History of implementation</entry> + </row> + + <row> + <entry>BUGS</entry> + <entry>Known bugs</entry> + </row> + + <row> + <entry>AUTHORS</entry> + <entry>People who created the command or wrote the + manual page.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>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.</para> + </sect2> + + <sect2 xml:id="manpages-markup-macros"> + <title>Macros</title> + + <para>&man.mdoc.7; markup is based on + <emphasis>macros</emphasis>. 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:</para> + + <programlisting xml:id="manpages-markup-macros-example-ls"> +.Dd December 1, 2015 <co xml:id="co-manpages-macro-example-ls-1"/> +.Dt LS 1 +.Sh NAME <co xml:id="co-manpages-macro-example-ls-2"/> +.Nm ls +.Nd list directory contents +.Sh SYNOPSIS <co xml:id="co-manpages-macro-example-ls-3"/> +.Nm <co xml:id="co-manpages-macro-example-ls-4"/> +.Op Fl -libxo <co xml:id="co-manpages-macro-example-ls-5"/> +.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1, <co xml:id="co-manpages-macro-example-ls-6"/> +.Op Fl D Ar format <co xml:id="co-manpages-macro-example-ls-7"/> +.Op Ar <co xml:id="co-manpages-macro-example-ls-8"/> +.Sh DESCRIPTION <co xml:id="co-manpages-macro-example-ls-9"/> +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.</programlisting> + + <calloutlist> + <callout arearefs="co-manpages-macro-example-ls-1"> + <para>A <emphasis>Document date</emphasis> and + <emphasis>Document title</emphasis> are defined.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-2"> + <para>A <emphasis>Section header</emphasis> for the NAME + section is defined. Then the <emphasis>Name</emphasis> + of the command and a one-line + <emphasis>Name description</emphasis> are defined.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-3"> + <para>The SYNOPSIS section begins. This section describes + the command-line options and arguments accepted.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-4"> + <para><emphasis>Name</emphasis> (<literal>.Nm</literal>) has + already been defined, and repeating it here just displays + the defined value in the text.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-5"> + <para>An <emphasis>Optional</emphasis> + <emphasis>Flag</emphasis> called <literal>-libxo</literal> + is shown. The <literal>Fl</literal> macro adds a dash to + the beginning of flags, so this appears in the manual + page as <literal>--libxo</literal>.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-6"> + <para>A long list of optional single-character flags are + shown.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-7"> + <para>An optional <literal>-D</literal> flag is defined. If + the <literal>-D</literal> flag is given, it must be + followed by an <emphasis>Argument</emphasis>. The + argument is a <emphasis>format</emphasis>, 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.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-8"> + <para>A final optional argument is defined. Because no name + is specified for the argument, the default of + <literal>file ...</literal> is used.</para> + </callout> + + <callout arearefs="co-manpages-macro-example-ls-9"> + <para>The <emphasis>Section header</emphasis> for the + DESCRIPTION section is defined.</para> + </callout> + </calloutlist> + + <para>When rendered with the command <command>man ls</command>, + the result displayed on the screen looks like this:</para> + + <programlisting>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.</programlisting> + + <para>Optional values are shown inside square brackets.</para> + </sect2> + + <sect2 xml:id="manpages-markup-guidelines"> + <title>Markup Guidelines</title> + + <para>The &man.mdoc.7; markup language is not very strict. For + clarity and consistency, the &os; Documentation project adds + some additional style guidelines:</para> + + <variablelist> + <varlistentry> + <term>Only the first letter of macros is upper case</term> + + <listitem> + <para>Always use upper case for the first letter of a + macro and lower case for the remaining letters.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Begin new sentences on new lines</term> + + <listitem> + <para>Start a new sentence on a new line, do not begin it + on the same line as an existing sentence.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Update <literal>.Dd</literal> when making non-trivial + changes to a manual page</term> + + <listitem> + <para>The <emphasis>Document date</emphasis> 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 + <literal>.Dd</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Give examples</term> + + <listitem> + <para>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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Include the BSD license</term> + + <listitem> + <para>Include the BSD license on new manual pages. The + preferred license is available from the <link + xlink:href="&url.articles.committers-guide;pref-license">Committer's + Guide</link>.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 xml:id="manpages-markup-tricks"> + <title>Markup Tricks</title> + + <para>Add a space before punctuation on a line with + macros. Example:</para> + + <programlisting>.Sh SEE ALSO +.Xr geom 4 , +.Xr boot0cfg 8 , +.Xr geom 8 , +.Xr gptboot 8</programlisting> + + <para>Note how the commas at the end of the + <literal>.Xr</literal> lines have been placed after a space. + The <literal>.Xr</literal> 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 <literal>4,</literal> or + <literal>8,</literal>.</para> + </sect2> + + <sect2 xml:id="manpages-markup-important-macros"> + <title>Important Macros</title> + + <para>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 + <filename>/usr/share/man/man*</filename> directories. For + example, to search for examples of the <literal>.Bd</literal> + <emphasis>Begin display</emphasis> macro:</para> + + <screen>&prompt.user; <userinput>find /usr/share/man/man* | xargs zgrep '.Bd'</userinput></screen> + + <sect3 xml:id="manpages-markup-important-macros-organizational"> + <title>Organizational Macros</title> + + <para>Some macros are used to define logical blocks of a + manual page.</para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Organizational Macro</entry> + <entry>Use</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>.Sh</literal></entry> + <entry>Section header. Followed by the name of + the section, traditionally all upper case. + Think of these as chapter titles.</entry> + </row> + + <row> + <entry><literal>.Ss</literal></entry> + <entry>Subsection header. Followed by the name of + the subsection. Used to divide a + <literal>.Sh</literal> section into + subsections.</entry> + </row> + + <row> + <entry><literal>.Bl</literal></entry> + <entry>Begin list. Start a list of items.</entry> + </row> + + <row> + <entry><literal>.El</literal></entry> + <entry>End a list.</entry> + </row> + + <row> + <entry><literal>.Bd</literal></entry> + <entry>Begin display. Begin a special area of + text, like an indented area.</entry> + </row> + + <row> + <entry><literal>.Ed</literal></entry> + <entry>End display.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect3> + + <sect3 xml:id="manpages-markup-important-macros-inline"> + <title>Inline Macros</title> + + <para>Many macros are used to mark up inline text.</para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Inline Macro</entry> + <entry>Use</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>.Nm</literal></entry> + <entry>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.</entry> + </row> + + <row> + <entry><literal>.Pa</literal></entry> + <entry>Path to a file. Used to mark up filenames and + directory paths.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="manpages-sample-structures"> + <title>Sample Manual Page Structures</title> + + <para>This section shows minimal desired man page contents for + several common categories of manual pages.</para> + + <sect2 xml:id="manpages-sample-structures-section-1-8"> + <title>Section 1 or 8 Command</title> + + <para>The preferred basic structure for a section 1 or 8 + command:</para> + + <programlisting xml:id="manpages-sample-structures-section-1-8-sample">.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 [email protected]</programlisting> + </sect2> + + <sect2 xml:id="manpages-sample-structures-section-4"> + <title>Section 4 Device Driver</title> + + <para>The preferred basic structure for a section 4 device + driver:</para> + + <programlisting xml:id="manpages-sample-structures-section-4-sample">.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 [email protected]</programlisting> + </sect2> + + <sect2 xml:id="manpages-sample-structures-section-5"> + <title>Section 5 Configuration File</title> + + <para>The preferred basic structure for a section 5 + configuration file:</para> + + <programlisting xml:id="manpages-sample-structures-section-5-sample">.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 [email protected]</programlisting> + </sect2> + </sect1> + + <sect1 xml:id="manpages-examples-as-templates"> + <title>Example Manual Pages to use as Templates</title> + + <para>Some manual pages are suitable as in-depth examples.</para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Manual Page</entry> + <entry>Path to Source Location</entry> + </row> + </thead> + + <tbody> + <row> + <entry>&man.cp.1;</entry> + <entry><filename>/usr/src/bin/cp/cp.1</filename></entry> + </row> + + <row> + <entry>&man.vt.4;</entry> + <entry><filename>/usr/src/share/man/man4/vt.4</filename></entry> + </row> + + <row> + <entry>&man.crontab.5;</entry> + <entry><filename>/usr/src/usr.sbin/cron/crontab/crontab.5</filename></entry> + </row> + + <row> + <entry>&man.gpart.8;</entry> + <entry><filename>/usr/src/sbin/geom/class/part/gpart.8</filename></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1 xml:id="manpages-resources"> + <title>Resources</title> + + <para>Resources for manual page writers:</para> + + <itemizedlist> + <listitem> + <para>&man.man.1;</para> + </listitem> + + <listitem> + <para>&man.mandoc.1;</para> + </listitem> + + <listitem> + <para>&man.groff.mdoc.7;</para> + </listitem> + + <listitem> + <para><link + xlink:href="http://manpages.bsd.lv/mdoc.html">Practical + UNIX Manuals: mdoc</link></para> + </listitem> + + <listitem> + <para><link + xlink:href="http://manpages.bsd.lv/history.html">History + of UNIX Manpages</link></para> + </listitem> + </itemizedlist> + </sect1> +</chapter> _______________________________________________ [email protected] mailing list https://lists.freebsd.org/mailman/listinfo/svn-doc-all To unsubscribe, send any mail to "[email protected]"