os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

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

Browse source
This commit is contained in:
Benjamin Kaduk 2016-10-24 01:35:36 +00:00
parent 5744e65d61
commit d66690f369
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=49557
1 changed files with 72 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
en_US.ISO8859-1/htdocs/news/status/report-2016-07-2016-09.xml
View file

@ -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@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 &mdash; 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>