Friday, September 18, 2015

FreeBSD Base System Upgrade - How To - and a question, DITA and FreeBSD ?

The FreeBSD Handbook is a really helpful resource. It contains a lot of really well organized information -- certainly, information that may be useful for FreeBSD system developers and system maintainers -- clearly, in a format of documentation written by authentic experts about the FreeBSD Kernel and broader FreeBSD Base System -- no imitations about UNIX expertise, in the FreeBSD handbook.

Towards rebuilding a FreeBSD operating system on a local area network -- such as for compiler optimizations, viz a viz /etc/make.conf, and for upgrading the operating system to a newer version, as for instance in upgrading from FreeBSD 10.1-RELEASE to 10.2-RELEASE -- there are a few references that would be useful, in the FreeBSD handbook.

As to augment the existing documentation, I'd like to add a few small annotations -- to highlight a small number of concepts addressed in  the conceptual topic repository of the FreeBSD handbook, and in an annotations sense, to add some augmentative information -- as follows
  • Building and Installing a Custom Kernel 
    • Concept: Kernel configuration
    • See also
      • Shell command:  `sysctl -n kern.conftxt`
      • Manual page config(5)
    • Ed. Notes - Misc
      • TBD: Cross-compiling the FreeBSD kernel (see documentation)
      • TBD: HOWTO FreeBSD Kernel Configuration GUI
        • See also: GNU/Linux kernel - `make menuconfig`, `make xconfig`, ...
      • TO DO: Produce an index of all kernel configuration parameters noted in the FreeBSD handbook
  • Rebuilding World
    • Concept: FreeBSD Base System
    • Ed. Notes - Misc.
      • See also: Previous link, as with regards to FreeBSD kernel configuration
      • TBD: Configurable parameters of the FreeBSD base system build
      • TBD: FreeBSD Base System Configuration GUI
        • See also: Poudriere; Augeas
        • Note: Licensing terms of FreeBSD base system components 
        • Note: Concepts, Licensing and Software Distribution
      • TBD: Cross-compiling the FreeBSD base system
      • TBD: Issue tracker integration
        • See also: Debian `reportbug`
  • Tracking for Multiple Machines
  • Ed. Notes (add'l)
    • TBD:  Handbook-wise documentation about files /etc/make.conf and  /etc/src.conf
      • Concept: Toolchains
      • Concept: Machine-specific optimizations 
        • e.g utilizing SSE machine instructions on later Intel architectures
      • See also: 
        • LLVM
        • Manual pages
          • make.conf(5)
            • Context: all system builds, including ports, kernel, and base system
          • src.conf(5)
            • Context: kernel and base system (?)
        • /usr/share/examples/etc/make.conf
        • /usr/src/share/mk/bsd.cpu.mk

Orthogonally: Though I cannot believe I'll ever be able to sell the FreeBSD project about using DITA, but it's "A thought," though.

The FreeBSD Handbook, by in large, already serves as a topically focused -- and very usefully detailed -- reference manual about the FreeBSD operating system. As a knowledge resource, the FreeBSD handbook very much "Holds its own," as furthermore a manner of a reference manual.

The Handbook is published in a format like of a set of thesis documents about individual components of FreeBSD. In a DITA format, each article-like section in the FreeBSD handbook could be rendered as a DITA Topic. That, in itself, might not exactly serve towards further development of the FreeBSD handbook. However, perhaps it might serve as an aid to users and developers, as towards a manner of extensibility about the FreeBSD handbook -- at least, then, to authors whom would be both familiar with the DITA format, and familiar with the "Internals" of FreeBSD.

The overlap, in that proverbial set -- perhaps it might not seem to be any very broad kind of an overlap, at least outside of an ideal estimate, as of a hypothetical universe in which DITA is something anyone would voluntarily learn, beyond the small community of technical documentation geeks, and those of us somewhere in orbital space to the same.

The FreeBSD Handbook, in its original format, is developed onto the DocBook toolchain -- a long tried and trusted toolchain for technical documents. The DocBook toolchain is comprised, essentially, of the DocBook Schema -- in any single format, such as of a Document Type Definition (DTD) or a RELAX-NG schema -- and the DocBook modular stylesheets. The DocBook stylesheets, in turn, are available in both of DSSSL format -- for application onto SGML DocBook documents -- and in XSL format, for application on to XML DocBook documents.

Though there is a mapping -- as commonly available of the DITA Open Toolkit (DITA OT) -- for transforming DITA documents onto DocBook, but presently, there might not be an inverse mapping for DocBook onto DITA. It might be a fairly trivial matter, to semantically invert any much of the DITA-to-DocBook transformation module, from DITA OT, in defining a DocBook-to-DITA transformation. However, the question of whether and how that may be pragmatically worth it might remain to be addressed.

There's a topic that the author of this article is not willing to venture to address, in any offhand regards, at the FreeBSD forums: "Anyone else wants to use DITA to document FreeBSD?" Though the author of this article might fancy himself to be sufficiently familiar with SGML, XML, DocBook, and DITA formats, sufficient to be able to manage such a project by himself, but the social incentive of such a matter might seem to be fairly much "In doubt," as it may seem to be fairly much "Non-trivial," as a prospective effort, in numerous independent points of view.

In a manner of a rhetorical question: How would a "Proof of concept" be regarded, for a DITA transform of the DocBook format of the original FreeBSD Handbook?

It might seem to need some kind of a "Run-up time," such a project, if it could ever be a project that might be any furthermore adopted by the FreeBSD developer community. Though the author of this article, in particular, fancies DITA to be as simple as push-button editing -- except for all of the visible markup of it -- but not everyone might quite agree.

In a further juxtaposition of DITA to DocBook: In DITA, there are also the matters of content inclusion and seperately, of linking, each of which such concepts does not occur exactly in such a manner, in DocBook, not in exactly as it occurs in the syntax and semantics of DITA. Furthermore, in DITA, there is the topic 'class' attribute -- probably a very much interesting features, to those of us whom may be, furthermore, object oriented programming (OOP) geeks.

Ed. Note: ...and then there's something about "How to avoid arbitrary topics," as towards, orthogonally, towards a manner of a Wiki model for DITA or -- contrarily -- towards a centrally edited topic repository model for DITA 

It would definitely be a project applying the Java(R) programming language, to document FreeBSD with DITA. DITA OT uses ASF* Ant, for instance, in DITA OT's own build automation framework. ASF Ant is a tool developed in Java(R). Whether or not all persons editing DITA documents may prefer to use editor platforms also developed in Java(r) -- such as the commercially licensed Oxygen XML product -- and the author of this article would rather prefer to use Emacs and PSGML, candidly -- but for so much as building the finally formatted documentation, it would definitely need to use Java(R), such a project. It may be at least a convenient thing, then, that FreeBSD is really good at running Java(R) applications.**

Is that enough of an incentive, in itself? Most probably, it is not. DITA is not the hottest kewlness online, and -- candidly -- all of this amounts to anything very much unlike a hot rod sports car view of FreeBSD. It doesn't exactly become easily to a metaphor about Minetest, either -- not to game around about operating systems design. This article describes some concepts of documentation, as in or towards a manner of a developer's view.


* ASF: The Apache Software Foundation.

** It could seem almost like a kind of Digital Magic -- the efficiency at which FreeBSD runs Java(R) applications, even on the desktop. Perhaps it's rather a matter of the operating system design in FreeBSD.