path: root/en_US.ISO8859-1/books
diff options
authorGuangyuan Yang <ygy@FreeBSD.org>2020-11-28 06:38:37 +0000
committerGuangyuan Yang <ygy@FreeBSD.org>2020-11-28 06:38:37 +0000
commit59e3915e5ca57b7a1be87a01f909929d554d6626 (patch)
treea1751a3017a64e7f89e462ff99f5826749fdcae6 /en_US.ISO8859-1/books
parent45e8327411442d5fc6b130d6ac579e224ab9f285 (diff)
Add a Testing section for manpages in the FDP Primer.
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
Notes: svn path=/head/; revision=54717
Diffstat (limited to 'en_US.ISO8859-1/books')
1 files changed, 43 insertions, 15 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
index e866470d81..44cf03be22 100644
--- a/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml
@@ -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.
+ <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>