From owner-svn-doc-all@freebsd.org Sun Dec 10 04:02:27 2017 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 9DBBAE812C6; Sun, 10 Dec 2017 04:02:27 +0000 (UTC) (envelope-from bjk@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 mx1.freebsd.org (Postfix) with ESMTPS id 680933108; Sun, 10 Dec 2017 04:02:27 +0000 (UTC) (envelope-from bjk@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id vBA42QFv006860; Sun, 10 Dec 2017 04:02:26 GMT (envelope-from bjk@FreeBSD.org) Received: (from bjk@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id vBA42Q7o006859; Sun, 10 Dec 2017 04:02:26 GMT (envelope-from bjk@FreeBSD.org) Message-Id: <201712100402.vBA42Q7o006859@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: bjk set sender to bjk@FreeBSD.org using -f From: Benjamin Kaduk Date: Sun, 10 Dec 2017 04:02:26 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r51273 - head/en_US.ISO8859-1/htdocs/news/status X-SVN-Group: doc-head X-SVN-Commit-Author: bjk X-SVN-Commit-Paths: head/en_US.ISO8859-1/htdocs/news/status X-SVN-Commit-Revision: 51273 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.25 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: Sun, 10 Dec 2017 04:02:27 -0000 Author: bjk Date: Sun Dec 10 04:02:26 2017 New Revision: 51273 URL: https://svnweb.freebsd.org/changeset/doc/51273 Log: Add 2017Q3 man page entry from wblock Modified: head/en_US.ISO8859-1/htdocs/news/status/report-2017-07-2017-09.xml Modified: head/en_US.ISO8859-1/htdocs/news/status/report-2017-07-2017-09.xml ============================================================================== --- head/en_US.ISO8859-1/htdocs/news/status/report-2017-07-2017-09.xml Sun Dec 10 03:54:46 2017 (r51272) +++ head/en_US.ISO8859-1/htdocs/news/status/report-2017-07-2017-09.xml Sun Dec 10 04:02:26 2017 (r51273) @@ -1224,4 +1224,56 @@ + + + Manual Pages + + + + + Warren + Block + wblock@FreeBSD.org + + + + + + &os; Documentation Project Primer + + + +

Over the last year, interest has increased in manual pages, in + large part due to excellent infrastructure work by Baptiste + Daroussin and others, and promotion by George Neville-Neil and + others. This increased interest has been both gratifying and + problematic. Our man pages are underappreciated gems, but we + have sadly lacked any substantial documentation on how to write + new ones.

+ +

In September, I added a new chapter to the + &os;Documentation + Project Primer describing the basics of creating a man + page. It includes descriptions of the markup, section + structure, recommended optional material such as examples, + and sample templates for the most common types of man pages. + The Resources section includes links to several external + resources, including the excellent Practical UNIX + Manuals: mdoc.

+ +

While this chapter is not a full tutorial, it does begin to fill + in a large gap in our documentation resources and provide a + starting point from which to grow.

+ + + + Add more explanation and examples of markup. + + Expand the sample templates with additional desired standard + features, like an EXAMPLES section. + + Add more sample templates. + +