svn commit: r51273 - head/en_US.ISO8859-1/htdocs/news/status

Sun Dec 10 04:02:27 UTC 2017

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 @@
       </task>
     </help>
   </project>
+
+  <project cat='doc'>
+    <title>Manual Pages</title>
+
+    <contact>
+      <person>
+	<name>
+	  <given>Warren</given>
+	  <common>Block</common>
+	  <email>wblock at FreeBSD.org</email>
+	</name>
+      </person>
+    </contact>
+
+    <links>
+      <url href="https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/">&os; Documentation Project Primer</url>
+    </links>
+
+    <body>
+      <p>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.</p>
+
+      <p>In September, I added a new chapter to the
+	<a href="https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/">&os;Documentation
+	Project Primer</a> 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 <a
+	href="http://manpages.bsd.lv/mdoc.html">Practical UNIX
+	Manuals: mdoc</a>.</p>
+
+      <p>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.</p>
+    </body>
+
+    <help>
+      <task>Add more explanation and examples of markup.</task>
+
+      <task>Expand the sample templates with additional desired standard
+	features, like an EXAMPLES section.</task>
+
+      <task>Add more sample templates.</task>
+    </help>
+  </project>
 </report>
