[wp-hackers] WordPress DocBook err, Book

[Jacob]

Francesco Corsentino wrote:
> I think this is a good idea! I'm writing a Archlinux Handbook (italian 
> version) using DocBook. But, but,  there are some problems: IMHO 
> project you launch needs:
> 1) xsl files to produce many formats (pdf, html/xhtml, plaintext, rtf, 
> etc...) and this point is more difficult (even if solution to this 
> problem we could do it then);
> 2) a subset of docbook markup (infact, one thing I've noticed about 
> docbook syntax is that there are many elements with same sense) so the 
> author will probably use coherent syntax;
> 3) a great coordination rules (for authors).
>
> I say: it's a great idea, so do you agree? 
Yeah, I started an User Guide Outline using the XSL DocBook. There are 
plenty of formats supported by PDF, I don't think is one of them. There 
are other ways to convert documents to PDF and RTF. My primary interest 
is only HTMl/XHTML and being able to see my work live. The problem I had 
with the docbook markup before was not being able to visualize what I 
was typing would look like. With XSL, I can do that.

I didn't use the build options in the DocBook XSL book. I used PHP 
5.1.4+ XSLTProcessor() class. Everything seems to work, but I haven't 
done any customizations at this point. The script in PHP is really 
simple. DocBook 5, simplifies a lot of the markup.

I plan on continuing the work on the End User Guide, supported in large 
part by the codex. There shouldn't be large chunks missing after using 
the codex. The second DocBook that I plan to write will be for 
Developers Guide, but that will take longer and I'm not sure I'll have 
it ready before 2.4 is released. There is a lot of information in the 
codex, but information on hooks, filters, and usage documentation for 
how to use the Cron API, Taxonomy API, etc isn't very detailed. I'll 
probably place the effort back into the codex, while I'm working on the 
Developer Guide.

The other issue I have after I complete the User Guide is providing a 
way for others to modify it. I could build something that would allow 
anyone to edit the files, but I'll probably use Google Code instead. 
Anything that uses the Codex has to be GPL, therefore would have to have 
source available.

Documentation is a volunteer effort. I wouldn't hold your breath and 
usually what you are probably doing is getting the foundation for 
someone who is interested to jump on to the project later. DocBook isn't 
so easy as the Codex that anyone can join, or so it would seem.

-- 

Jacob Santos

http://www.santosj.name - blog
http://wordpress.svn.dragonu.net/unittest/ - unofficial WP unit test suite.

Also known as darkdragon and santosj on WP trac.