From 59e3915e5ca57b7a1be87a01f909929d554d6626 Mon Sep 17 00:00:00 2001
From: Guangyuan Yang <ygy@FreeBSD.org>
Date: Sat, 28 Nov 2020 06:38:37 +0000
Subject: 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
---
 .../books/fdp-primer/manpages/chapter.xml          | 58 ++++++++++++++++------
 1 file changed, 43 insertions(+), 15 deletions(-)

(limited to 'en_US.ISO8859-1/books')

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>
 
-- 
cgit v1.2.3