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

[Dirk Bächle]

Hi,

On 26.03.2013 00:50, Dirk Bächle wrote:

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

>


just a short update on this: I have successfully linked the new doc 
toolchain to the install/packaging process, as started via bootstrap.py. 
All files and packages seem to be there, but it would be good if someone 
from the ReleaseTeam could have a closer look at it (Bill?).

I have now done all I could and thought was important, trying to get the 
basic stuff working. I won't touch the repository for a while, until I 
got some feedback and we decided what the next steps could be.


> 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?

>

> [...]

>


Best regards,

Dirk