os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add a Testing section for manpages in the FDP Primer.

Browse source 
Move the relative information from the Tip section about testing manpages to the new section, along with information about mandoc(1)'s linter, igor, etc. It now covers quite a few cases and common mistakes.

Submitted by:	fernape
Reviewed by:	debdrup, ygy
Differential Revision:	https://reviews.freebsd.org/D27386
This commit is contained in:
Guangyuan Yang 2020-11-28 06:38:37 +00:00
parent 45e8327411
commit 59e3915e5c
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=54717
1 changed files with 43 additions and 15 deletions

58
en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml
View file

@ -115,21 +115,6 @@
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>
@ -645,6 +630,49 @@ is an example configuration file.
</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>
<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>