Date: Sat, 28 Nov 2020 06:38:37 +0000 (UTC) From: Guangyuan Yang <ygy@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r54717 - head/en_US.ISO8859-1/books/fdp-primer/manpages Message-ID: <202011280638.0AS6cbWn096383@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: ygy Date: Sat Nov 28 06:38:37 2020 New Revision: 54717 URL: https://svnweb.freebsd.org/changeset/doc/54717 Log: 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 Modified: head/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml Thu Nov 26 19:15:09 2020 (r54716) +++ head/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml Sat Nov 28 06:38:37 2020 (r54717) @@ -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> @@ -643,6 +628,49 @@ is an example configuration file. .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com</programlisting> </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">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202011280638.0AS6cbWn096383>