Documenting the History of Utilities in /bin and /sbin

From owner-svn-doc-all@freebsd.org Mon Oct 24 01:35:38 2016 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 15CE2C1F734; Mon, 24 Oct 2016 01:35:38 +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 E416D61C; Mon, 24 Oct 2016 01:35:37 +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 u9O1Zbov065802; Mon, 24 Oct 2016 01:35:37 GMT (envelope-from bjk@FreeBSD.org) Received: (from bjk@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id u9O1ZbPD065801; Mon, 24 Oct 2016 01:35:37 GMT (envelope-from bjk@FreeBSD.org) Message-Id: <201610240135.u9O1ZbPD065801@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: bjk set sender to bjk@FreeBSD.org using -f From: Benjamin Kaduk Date: Mon, 24 Oct 2016 01:35:37 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r49557 - head/en_US.ISO8859-1/htdocs/news/status X-SVN-Group: doc-head 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.23 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: Mon, 24 Oct 2016 01:35:38 -0000 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 + + + Documenting the History of Utilities in /bin and /sbin + + + + + Sevan + Janiyan + + sevan@FreeBSD.org + + + + + The igor Port. + BSD Family Tree in Subversion + The UNIX Heritage Society + Cat-V Manual Library + + + +

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.

+ +

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.

+ +

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.

+ +

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).

+ +

This was a good exercise in:

+ +

Becoming familiar with + mandoc.
Using tools such as the linting functionality in mandoc and + the igor documentation script.
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 The UNIX + Heritage Society and the manual + library on cat-v.org which + hosts copies of manuals such as those shipped with + Research + UNIX. These manuals are not commonly available + elsewhere.

+ + + + 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. + +