OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [docbook-apps] Producing Open Source Software


2009/3/5 DavePawson <davep@dpawson.co.uk>:
> Eric Johnson wrote:
>>
>> One of the big hurdles for advocating the use of DocBook in “public” open
>> source projects is that there are plenty of wiki based alternatives that are
>> free, have short learning curves, and do not require “building”.
>
> True. There are always easier alternatives.
> These still require project effort to generate the documentation though?

Hi.

As a contributor to the PHP documentation, I have to say that the
tools we use have come a LONG way.

We use DocBook 5 with a few tiny additions.

We currently have a 2 step process to build the documentation, both
are written in PHP.

The first pulls all the documentation into a single XML file. The
second processes the big xml file into HTML, PHP pages, CHM, PDF.

There is some work on making this a single process.

The current English documentation consists of around 12,500 files on
around 26Mb.

Creating the entire range of output (plain HTML for standalone unfussy
local reading, PHP pages for the PHP.net sites/mirrors, HTML for the
CHM build process) takes around 10 mins on my slow desktop machine,
whilst running in idle mode (windows).

The tool to convert the large XML to the resultant formats is called PhD.

We have new people coming onboard to translate the manual using these
tools on a fairly regular basis.

PhD is written in PHP and can be amended to create any style you like.
It is very extendable.

Admittedly, getting the XML right is sometimes a bit of an issue for
the newbies, but they learn. Very quickly. Simply because their
commits fail to build. And are 2 steps produce all the output needed
to fix it.

Regards,

Richard Quadling.

http://wiki.php.net/doc/phd/install

> That, I think, was the focus of Karens message.
>
>> Developers can easily contribute to the pool of documentation. The wiki
>> approach does have some drawbacks
>
> Yes, of course. Most alternatives have some pro's and con's.
>
> As Karen notes, documentation, in docbook, for docbook ....
> is weird anyway :-)
>
>
>
>
> regards
>
> --
> Dave Pawson
> XSLT XSL-FO FAQ.
> http://www.dpawson.co.uk
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>



-- 
-----
Richard Quadling
Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731
"Standing on the shoulders of some very clever giants!"


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]