[Scons-dev] New SCons doc toolchain...

[Dirk Bächle]

Hi developers,

over the last weeks, I collected together all the work I'd done so far 
on the rewrite of the documentation toolchain in SCons. It has now 
reached a state where I think it's ready to get a little more public, so 
I pushed the current code to my private work repository.
If you'd like to have a look at it, you can get a copy of the branch 
with something like:

   hg clone 
https://dirkbaechle@bitbucket.org/dirkbaechle/scons_experimental -r 
new_doc_toolchain scons_doc_toolchain

Yes, I use named branches to organize my work...and no, I don't intend 
to create a pull request for the official SCons repo from here. ;)

It currently has the following main features:

   - All processing is based on plain Python scripts, the only 
additional dependencies are either lxml or libxml2.
     (for creating the PDF files, you also need to have a renderer like 
fop, xep or jw installed)
     XML parsing is now DOM-based, instead of using SAX.
   - Uses a special SCons XSD, based on the Docbook v4.5 DTD/XSD.
   - All documents (like MAN pages, User guide and also the 
Tools/Builders docs in the src/engine folder)
     are valid against this XSD and can be easily re-validated after any 
changes by running a single script.
   - The troff input files for the MAN pages have been converted to 
Docbook (DocLifter still rocks!).
   - Entities, the descriptions for Tools/Builders/Functions/CVars and 
the automatically created example
     outputs are supported as before.
   - All document folders have SConstructs, together with the added 
Docbook Tool you can directly create
     HTML and MAN pages. The User guide has its own titlepage design, 
see the attached PDF for getting
     a first impression from a few selected pages.

For more information about the new folder structure, which files can be 
found where and how everything fits together, please refer to the file 
'doc/overview.rst'. It's also still a work in progress, but hopefully 
already can
answer some of the most urgent questions.

So, just dive in if you find the time, and give some feedback please. 
Try to edit a document and then create the
output. I'm especially interested in comments about the general 
workflow. Is it user-oriented and friendly enough for the developers and 
the release team?
I'd rather not go into deep discussions about the design of the 
titlepages for the User manual, or why exactly I chose Docbook v4.5 as a 
start. If you think that these details need a change, you'll get your 
chance as soon as the new toolchain has found its way into the main 
repository. ;)

In the meantime I'll continue with completing documentation and 
rewriting the bootstrap.py and doc/SConstruct files, such that the 
building and packaging processes work with the new setup.

So much for today.

Best regards,

Dirk

-------------- next part --------------
A non-text attachment was scrubbed...
Name: user_guide_snippet.pdf
Type: application/pdf
Size: 487784 bytes
Desc: not available
Url : <http://two.pairlist.net/pipermail/scons-dev/attachments/20130326/2e864dcc/attachment-0001.pdf>