diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml | 746 |
1 files changed, 0 insertions, 746 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml deleted file mode 100644 index c951cbd85e..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml +++ /dev/null @@ -1,746 +0,0 @@ -<?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 how 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> - - <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. Since 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 space, 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 flastname@example.com</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 flastname@example.com</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 flastname@example.com</programlisting> - </sect2> - </sect1> - - <sect1 xml:id="manpages-testing"> - <title>Testing</title> - - <para>Testing a new manual page can be challenging. Fortunately - there are some tools that can assist in the task. Some of them, - like &man.man.1;, do not look in the current directory. It is a - good idea to prefix the filename with <literal>./</literal> if - the new manual page is in the current directory. An absolute - path can also be used.</para> - <para>Use &man.mandoc.1;'s linter to check for parsing - errors:</para> - - <screen>&prompt.user; <userinput>mandoc -T lint ./mynewmanpage.8</userinput></screen> - - <para>Use <package>textproc/igor</package> to proofread the - manual page:</para> - - <screen>&prompt.user; <userinput>igor ./mynewmanpage.8</userinput></screen> - - <para>Use &man.man.1; to check the final result of your - changes:</para> - - <screen>&prompt.user; <userinput>man ./mynewmanpage.8</userinput></screen> - - <para>You can use &man.col.1; to filter the output of - &man.man.1; and get rid of the backspace characters before - loading the result in your favorite editor for - spell checking:</para> - - <screen>&prompt.user; <userinput>man ./mynewmanpage.8 | col -b | vim -R -</userinput></screen> - - <para>Spell-checking with fully-featured dictionaries is - encouraged, and can be accomplished by using - <package>textproc/hunspell</package> or - <package>textproc/aspell</package> combined with - <package>textproc/en-hunspell</package> or - <package>textproc/en-aspell</package>, respectively. - For instance:</para> - - <screen>&prompt.user; <userinput>aspell check --lang=en --mode=nroff ./mynewmanpage.8</userinput></screen> - - </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> |