Hi Frank,
> Using docbook/SGML for this and turning it into book-style; assuming I'd
There isn't much difference, but we have standardized on DocBook/XML in
the community so if you want to use our community toolchain you'll need
to use DocBook/XML. I use 4.4, the toolchain works with 5.0pre4 also,
though you need the DTD schema which isn't fully supported with 5.0 as we
haven't put together a RelaxNG toolchain yet.
For converting to DocBook, I have a heavily hacked up version of an XSL
file I found on the DocBook Wiki which will do the heavy lifting of
converting HTML into DocBook. Since DocBook tags convey the semantics
rather than the formatting there is a good deal of additional editing
required, but it at least gets the paragraph and section handling out of
the way.
The redistribution terms for DocBook appear to be pretty liberal so I'm
planning on putting together a toolchain package you can just grab and
install from the community page. I imagine you'll find it useful. :)
> go for this, is it possible to embed hyperlinks, both to other sections
> of the article series and to actual sourcecode on cvs.opensolaris.org ?
Yes -- DocBook supports many different link tag types, including
hyperlinks, cross reference links, and olinks. olinks are the most
flexible as they resolve through a lookup table, so you can change the
link depending on the output format type -- think PDF versus delivering
multiple HTML files in multiple directories, where one format is a cross
reference but the other output format generates a hyperlink. You can get
as complex or as simple as you like.
> On reviewing, cut&pasting it all from the blog entries into a single
> file makes it very hard to maintain for me (and doubly hard to split up
> again afterwards). My UNIX-utils-for-textprocessing knowledge is a bit
> stale - does anyone know a simple preprocessor that substitutes nothing
> but '#include "...."' so that I can create the "all in one" file/TOC
> simply by concatenating the sections ? What would I use ? Maybe I should
> just shellscript that ...
The XML processor supports multiple files. I would suggest having one file
per chapter or section, though you can split it up however you like.
Here's a sample from the index file of a project design document that I
have in the works:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE book
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; [
<!ENTITY % params SYSTEM "params.mod">
%params;
<!ENTITY titlepg SYSTEM "title.xml">
<!ENTITY intro SYSTEM "intro.xml">
...
<!ENTITY glossary SYSTEM "glossary.xml">
]>
<book><title>&doctitle;</title>
&titlepg;
&intro;
..
&glossary;
</book>
If you find the XML entity syntax a little off-putting (which some people
do -- I like the modularity it provides myself) the xsltproc processor
supports the XInclude standard for XML. The source tarballs for the
various books released on the docs community page use XInclude rather than
entities to concatenate the chapters.
> Another option might be to (ab-)use the genunix.org OpenSolaris Wiki and
> put the articles there. What do you folks think about that idea ? Wiki
> would be a simple way for change tracking and article review ...
The Wiki seems like a fine tool for working on a draft version. :)
- Eric
