summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorygy <ygy@c2e8774f-c49f-e111-b436-862b2bbc8956>2020-11-28 06:38:37 +0000
committerygy <ygy@c2e8774f-c49f-e111-b436-862b2bbc8956>2020-11-28 06:38:37 +0000
commitb904053048877dd79ae9f3a1d3d2211169f4c40f (patch)
treea1751a3017a64e7f89e462ff99f5826749fdcae6
parent401f787f49a4815f59c1a7842b25ebbbdbdbc085 (diff)
downloadfreebsd-doc-b904053048877dd79ae9f3a1d3d2211169f4c40f.tar.gz
freebsd-doc-b904053048877dd79ae9f3a1d3d2211169f4c40f.tar.bz2
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 git-svn-id: http://svn.freebsd.org/doc/head@54717 c2e8774f-c49f-e111-b436-862b2bbc8956
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml58
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.
</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>