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

Mon Oct 24 01:35:38 UTC 2016

Author: bjk
Date: Mon Oct 24 01:35:36 2016
New Revision: 49557
URL: https://svnweb.freebsd.org/changeset/doc/49557

Log:
  Add entry on documenting the history of /bin and /sbin from sevan

Modified:
  head/en_US.ISO8859-1/htdocs/news/status/report-2016-07-2016-09.xml

Modified: head/en_US.ISO8859-1/htdocs/news/status/report-2016-07-2016-09.xml
==============================================================================

--- head/en_US.ISO8859-1/htdocs/news/status/report-2016-07-2016-09.xml	Mon Oct 24 01:08:55 2016	(r49556)
+++ head/en_US.ISO8859-1/htdocs/news/status/report-2016-07-2016-09.xml	Mon Oct 24 01:35:36 2016	(r49557)
@@ -934,4 +934,76 @@
       Semihalf
     </sponsor>
   </project>
+
+  <project cat='doc'>
+    <title>Documenting the History of Utilities in /bin and /sbin</title>
+
+    <contact>
+      <person>
+	<name>
+	  <given>Sevan</given>
+	  <common>Janiyan</common>
+	</name>
+	<email>sevan at FreeBSD.org</email>
+      </person>
+    </contact>
+
+    <links>
+      <url href="http://svnweb.FreeBSD.org/ports/head/textproc/igor">The <tt>igor</tt> Port.</url>
+      <url href="https://svnweb.FreeBSD.org/base/head/share/misc/bsd-family-tree?view=log">BSD Family Tree in Subversion</url>
+      <url href="http://www.tuhs.org">The UNIX Heritage Society</url>
+      <url href="http://man.cat-v.org">Cat-V Manual Library</url>
+    </links>
+
+    <body>
+      <p>For EuroBSDcon, I began looking into inconsistencies within
+	components inside our family of operating systems.  My workflow
+	consisted of reading the documentation for a given utility and
+	checking the history in the revision control system for missing
+	fixes or functionality in the trees of NetBSD, &os;, OpenBSD, and
+	DragonFly BSD.</p>
+
+      <p>One thing which became obvious very quickly, was the
+	inconsistency between operating systems about where and/or which
+	version a utility originated in, despite our common heritage.</p>
+
+      <p>I began with working through the man pages in &os;, verifying the
+	details in pages which already had a history section and making
+	patches for those which did not.</p>
+
+      <p>From there, changes were propogated out to NetBSD, OpenBSD and
+	Dragonfly BSD where applicable (not all utilities originated from
+	the same source or implimentation, for example).</p>
+
+      <p>This was a good exercise in:</p>
+
+      <ul>
+	<li>Becoming familiar with
+	  <a href="http://mdocml.bsd.lv/man">mandoc</a>.</li>
+
+	<li>Using tools such as the linting functionality in mandoc and
+	  the <tt>igor</tt> documentation script.</li>
+
+	<li>Becoming familiar with the locations where things are
+	  documented and with external sources of historical information,
+	  such as the BSD Family Tree which is included in the &os; base
+	  system, and projects like <a href="http://www.tuhs.org">The UNIX
+	    Heritage Society</a> and the <a href="http://man.cat-v.org">manual
+	    library</a> on <a href="http://cat-v.org">cat-v.org</a> which
+	  hosts copies of manuals such as those shipped with
+	  <a href="https://en.wikipedia.org/wiki/Research_Unix">Research
+	    UNIX</a>.  These manuals are not commonly available
+	  elsewhere.</li>
+      </ul>
+    </body>
+
+    <help>
+      <task>Cover the remaining manuals for userland utilities, and maybe
+	expand onto library and syscall APIs, though I say that without
+	estimating the feasibility — components originating from a
+	closed-source operating system are tricky to document the history
+	of, due to the lack of availability of sources or sometimes even
+	headers.</task>
+    </help>
+  </project>
 </report>
