Date: Wed, 15 Jan 1997 09:15:28 -0500 (EST) From: John Fieber <jfieber@indiana.edu> To: A JOSEPH KOSHY <koshy@india.hp.com> Cc: freebsd-doc@FreeBSD.ORG Subject: Re: Any tutorials on docbook? Message-ID: <Pine.BSI.3.95.970115084146.264h-100000@fallout.campusview.indiana.edu> In-Reply-To: <199701151351.AA253546261@fakir.india.hp.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, 15 Jan 1997, A JOSEPH KOSHY wrote: > Are there any tutorials on using DocBook? Do we have any examples of > Docbook use in the 3.0-current tree? Funny you should ask. I just started working on one yesterday. The resources that exist now include: The documentation that comes with Docbook is pretty good. It can be found at http://www.ora.com/davenport/dbdoc/. The user's guide and reference are the most relevant here. The reference contains document fragments illustrating each element in use. Sample documents. The docbook documentation is, naturally, written using docbook. I have some other documents, include the Digital Unix Technical Overview and System Administration Guide, the latter of which is larger than our own handbook. I'm also working on marking up the FreeBSD tutorials and will put them on the web as I have them done. I'll see about putting these together on a web page sometime today. An issue I'm still hammering out as I markup the sample documents is markup recommendations. Docbook is rich enough that you could potentially end up with more markup than content in your document! For example, in running text, you could have: ... <command>rm -rf /</command> ... or ... <command>rm <parameter>-rf</parameter> <parameter>/</parameter></command> ... or ... <command>rm <parameter><option>-rf</option> <parameter><filename>/</filename></parameter></parameter> ... and so on. For running text, I tend to favor the first form, except when command syntax is being defined. The markup guide I'm working on will be not so much a guide to docbook, as a narrowing of its scope to something manageable. The other practical concern is that implementing all possible docbook constructs in a docbook -> whatever conversion is a huge task. I'm trying to identify *supported* constructs. The results of my automated linuxdoc to docbook conversion, unfortunately, do *not* yield good examples of docbook markup. Bunches of things that can be usefully marked up in docbook simply are not marked up because Linuxdoc has no equivalent elements (for example, tips and warnings) while others have a one to many mapping. Most in-line typographic treatment in Linuxdoc is done with <tt>...</tt>, <bf>...</bf> and <em>...</em>. Docbook does have a generic emphasis element, there is no equivalent to the others. My conversion tries out bunches of regex expressions on the content of <tt>...</tt> and friends to guess the content (eg something with slashes, like <tt>/etc/sysconfig</tt> gets turned into <filename>/etc/sysconfig</filename>, <tt>rm -r</tt> becomes <command>rm -r</command>, and <tt>foo@bar.org</tt> becomes <email>foo@bar.org</email>. Unfortunately, there are limits to the accuracy and a fair number of things get mis-interpreted. Realizing that legacy documents would be converted to docbook, the creaters endowed every element with a "remap" attribute. When a <tt>...</tt> or <bf>...</bf> cannot be figured out, it just comes out as <emphasis remap=tt>...</emphasis> or <emphasis remap=bf>...</emphasis>. The other notable difference is that the text used to identify a cross reference is specified where the reference is made in linuxdoc, while in docbook, it is specified (or inferred from) the target. Again, the remap attribute on the <xref> tag is used to simulate linuxdoc behavior, but that should *not* be used for any new documents. -john
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSI.3.95.970115084146.264h-100000>