From owner-svn-doc-all@freebsd.org Sat Nov 28 06:38:37 2020 Return-Path: Delivered-To: svn-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id B5B7F4782A7; Sat, 28 Nov 2020 06:38:37 +0000 (UTC) (envelope-from ygy@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Cjhf54mR4z3Gty; Sat, 28 Nov 2020 06:38:37 +0000 (UTC) (envelope-from ygy@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 967BA22CCC; Sat, 28 Nov 2020 06:38:37 +0000 (UTC) (envelope-from ygy@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id 0AS6cbq0096384; Sat, 28 Nov 2020 06:38:37 GMT (envelope-from ygy@FreeBSD.org) Received: (from ygy@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id 0AS6cbWn096383; Sat, 28 Nov 2020 06:38:37 GMT (envelope-from ygy@FreeBSD.org) Message-Id: <202011280638.0AS6cbWn096383@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: ygy set sender to ygy@FreeBSD.org using -f From: Guangyuan Yang Date: Sat, 28 Nov 2020 06:38:37 +0000 (UTC) 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 X-SVN-Group: doc-head X-SVN-Commit-Author: ygy X-SVN-Commit-Paths: head/en_US.ISO8859-1/books/fdp-primer/manpages X-SVN-Commit-Revision: 54717 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 28 Nov 2020 06:38:37 -0000 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 PDF generation. See &man.man.1;. - - 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 ./: - - &prompt.user; man ./mynewmanpage.8 - - An absolute path can also be used: - - &prompt.user; man /home/xsmith/mynewmanpage.8 - - - Manual Page Sections @@ -643,6 +628,49 @@ is an example configuration file. .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com + + + + Testing + + 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 ./ if + the new manual page is in the current directory. An absolute + path can also be used. + Use &man.mandoc.1;'s linter to check for parsing + errors: + + &prompt.user; mandoc -T lint ./mynewmanpage.8 + + Use textproc/igor to proofread the + manual page: + + &prompt.user; igor ./mynewmanpage.8 + + Use &man.man.1; to check the final result of your + changes: + + &prompt.user; man ./mynewmanpage.8 + + 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: + + &prompt.user; man ./mynewmanpage.8 | col -b | vim -R - + + Spell-checking with fully-featured dictionaries is + encouraged, and can be accomplished by using + textproc/hunspell or + textproc/aspell combined with + textproc/en-hunspell or + textproc/en-aspell, respectively. + For instance: + + &prompt.user; aspell check --lang=en --mode=nroff ./mynewmanpage.8 +