[wp-docs] Re: [wp-hackers] Codex function page proposal

[Jacob Santos]

You should have mentioned the Perl automated script. However, it again 
seems as if you are moving toward DocBook for your solution. You should 
look more into phpDocumentor [1], because it can also output in DocBok 
format. It might be an issue however is that the phpdoc does not include 
@category, which the DocBook format template uses. If that is the case, 
then it shouldn't be too difficult to add it in for all of the files. 
You would just need to add @category to all of the file level phpdoc 
blocks. The patch for that wouldn't be that difficult.

Hmm, it seems that whatever you conclude on, it will be interesting. 
Hopefully, the conclusion will be sooner rather than later, because I 
don't think any one else will attempt what you guys are doing at the 
moment or at least not in the near future.

Jacob Santos


Charles K. Clarkson wrote:
> Additional Thoughts:
>
> It would probably be better for this and future documentation projects
> to generate XML from the WordPress source code. Future Codex editors
> could then use that XML source to customize references. Writing a XML
> standard for that is beyond my current skills, but common source files
> have a lot of appeal.
>
> The program which produces the Trunk [4] (phpDocumentor) might be a good
> candidate for producing the base XML files. Examples, Descriptions and
> Notes would still require human editors to maintain relevant
> documentation, but could be left in the XML files to allow more robust
> WordPress documentation projects down the line.
>
> As Jacob has stated, we need to avoid duplicate effort, not because it
> is is inefficient, but because we all will eventually move on to other
> projects and we need to find the easiest path to keeping the Codex up to
> date now and in the future.
>
> You mentioned code syntax highlighting in your example page [3]. With a
> publicly available XML file of the WordPress function docs it isn't much
> of a stretch to see a WordPress plugin which could use one of the
> textarea plugins to display up to date WordPress documentation in the
> Admin area of the users own blog complete with links to other sources
> and syntax highlighted examples customized to the users preferences.
>
> [1] http://codex.wordpress.org/Template:Parameter
> [2] http://us2.php.net/manual/en/funcref.php
> [3] http://codex.wordpress.org/User:Chrisbliss18/wp_cache_add
> [4] http://phpdoc.wordpress.org/trunk/
>
> HTH,
>
> Charles Clarkson