Changeset View
Changeset View
Standalone View
Standalone View
en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml
| Show First 20 Lines • Show All 109 Lines • ▼ Show 20 Lines | <sect1 xml:id="manpages-markup"> | ||||
| <para>Manual page source is usually interpreted and displayed to | <para>Manual page source is usually interpreted and displayed to | ||||
| the screen interactively. The source files can be ordinary text | the screen interactively. The source files can be ordinary text | ||||
| files or compressed with &man.gzip.1; to save space.</para> | files or compressed with &man.gzip.1; to save space.</para> | ||||
| <para>Manual pages can also be rendered to other formats, | <para>Manual pages can also be rendered to other formats, | ||||
| including PostScript for printing or <acronym>PDF</acronym> | including PostScript for printing or <acronym>PDF</acronym> | ||||
| generation. See &man.man.1;.</para> | 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"> | <sect2 xml:id="manpages-markup-sections"> | ||||
| <title>Manual Page Sections</title> | <title>Manual Page Sections</title> | ||||
| <para>Manual pages are composed of several standard sections. | <para>Manual pages are composed of several standard sections. | ||||
| Each section has a title in upper case, and the sections for a | Each section has a title in upper case, and the sections for a | ||||
| particular type of manual page appear in a specific order. | particular type of manual page appear in a specific order. | ||||
| For a category 1 General Command manual page, the sections | For a category 1 General Command manual page, the sections | ||||
| are:</para> | are:</para> | ||||
| ▲ Show 20 Lines • Show All 497 Lines • ▼ Show 20 Lines | |||||
| .Sh DESCRIPTION | .Sh DESCRIPTION | ||||
| .Nm | .Nm | ||||
| is an example configuration file. | is an example configuration file. | ||||
| .Sh SEE ALSO | .Sh SEE ALSO | ||||
| .Xr example 8 | .Xr example 8 | ||||
| .Sh AUTHORS | .Sh AUTHORS | ||||
| .An Firstname Lastname Aq Mt flastname@example.com</programlisting> | .An Firstname Lastname Aq Mt flastname@example.com</programlisting> | ||||
| </sect2> | </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 backspaces 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> | |||||
| </sect1> | </sect1> | ||||
| <sect1 xml:id="manpages-examples-as-templates"> | <sect1 xml:id="manpages-examples-as-templates"> | ||||
| <title>Example Manual Pages to Use as Templates</title> | <title>Example Manual Pages to Use as Templates</title> | ||||
| <para>Some manual pages are suitable as in-depth examples.</para> | <para>Some manual pages are suitable as in-depth examples.</para> | ||||
| <informaltable> | <informaltable> | ||||
| ▲ Show 20 Lines • Show All 65 Lines • Show Last 20 Lines | |||||