Docbook Build Toolchain (was Re: Proposal: Create product for each derivative's documentation)

[Philip Olson]

> On Thu, Apr 9, 2009 at 3:05 PM, Philip Olson <philip at roshambo.org>  
> wrote:
>>> If you do know of solid tools that the team could use to improve its
>>> toolchain, and have some concrete proposals to put forward that  
>>> could
>>> be evaluated, please put them forward.
>>
>> We suffered from this problem for awhile and ended up creating a  
>> new project
>> out of it that only requires a recent version of PHP. Granted it  
>> only deals
>> with the building aspect but it's great to say only PHP is needed  
>> instead of
>> various boring tools like automake, openjade, xsltproc, etc. This  
>> tool also
>> builds CHM and PDF.
>>
>> One goal is to make it generic enough to work on any DocBook  
>> project (and it
>> sorta is) but currently it contains PHP.net specific elements. If  
>> you're
>> interested in such a tool let me know and we'll use Ubuntu as a  
>> testbed for
>> when we continue work on expanding its use for others, or simply  
>> try it out.
>> Granted we designed it for DocBook 5 but DocBook 4 should work  
>> without too
>> much trouble.
>>
>> The tool in question is called PhD: http://wiki.php.net/doc/phd
>
> That does look quite cool. I think for building HTML in particular we
> are likely to be heavily biased in favour of tools which exist in the
> Ubuntu main repository, because we build HTML in our package
> generation process, which happens in the automatic Ubuntu build
> machines in Launchpad. Those machines can only use build tools which
> are in the Ubuntu repository. What are the chances of your tool making
> it into Ubuntu?

Maybe after it's ready for better generic use which is something we're  
serious about and even have a GSoC student working on that this  
summer. But the license and code are open, there's nothing holding it  
back... except human time.

> But the barrier to entry that has been mentioned isn't really in the
> build process: contributors to the team don't need to know about
> those. What we're looking for is an easier way for people to
> contribute material to the xml documents, so a wiki->xml tool, or a
> robust xml editor...

We also suffer from that and researched options over the years but  
nothing felt right. So, we (especially Yannick) have started work on  
another project appropriately named 'doc-editor' that allows users to  
login, edit and commit to the DocBook. And it allows 'anonymous'  
people to submit to a patch queue for developers to review and commit.  
However, it's in alpha stages right now but if interested have a look  
at a fully functional demo:

   PHP Doc Editor (Anonymous CVS user: cvsread pass: phpfi)
   - http://ytorres.dyndns.org/doc-editor/

Please don't work it too hard though :) And it also has dreams of  
being generic enough to work outside the php.net realm, just look at  
its TODO file for details. Unfortunately we don't use po files for  
translations and are considering this but change can be difficult work.

Perhaps it would be enjoyable if both the PHP and Ubuntu projects  
worked on a single tool like this.

Regards,
Philip