Re: Converting HTML to Docbook

Yeah - I agree - any methods that makes it easier for people to add documentation is great .. - I'm just very lazy so the idea of only keeping up to date one set of documentation is very nice... :) I started looking at the inline tags -> docbook anyway, below is a sample of the header for php_codedoc it'self. I got it starting to outputting docbook already, but it probably needs a few more hours work. I was wondering how confused phpdoc or phpdocu would get if I started adding extra tags - eg. using @page @pagesummary @section @list @listend @varlist @varlistitem @varlisttype rather than using the PAGE: XXXX format... regards alan /* * @Docbook * PACKAGESECTION: packages.php.codedoc

* PAGE:           INDEX
* This chapter expains how to use the phpcodedoc tool which can generate lxr type html and docbook

* output from comments embedded in class files *

* PAGE:        Introduction

* PAGESUMMARY: what is PHP_CodeDoc all about? *

* SECTION:     Introduction

* * PHP_CodeDoc was written for a number of reasons * LIST: * - To make use of the php tokenizer module to generate documentation * - To produce documentation that showed the source code as well as the notes * - Because I saw the ruby class documentation, and thought it looked very clear.. * ENDLIST: * * PHP_CodeDoc was not written (unlike most other similar applications) to emulate javadoc, * my main logic here was that javadoc is focused on documenting closed source applications * where as most of the stuff I need to document is open source - so including the source * in the output was essential to understanding what the class really did. *

* PAGE:         Configuring PHP_CodeDoc

* PAGESUMMARY: Setting up PHP_CodeDoc *

* SECTION:      Main configuration options

* * Some documents to go in here * * *

* PAGE:        Docbook output

* PAGESUMMARY: Using PHP_Codedoc to generate docbook *

* SECTION:     Tags inside your files

* * All PHPcodedoc to docbook tags have a similar format, the *, followed by the keyword * PACKAGESECTION,PAGE,SECTION,PAGESUMMARY,LIST,ENDLIST, OPTIONLIST,ENDOPTIONLIST followed by a colon, * then some optional text. * * VARLIST * ITEM: PAGESECTION * TYPE: string * The page section is the url type locater that your package falls in - usually package.section.name * ITEM: * * * */ Martin Jansen wrote:

On Sat Jul 27, 2002 at 10:2844AM +0800, Alan Knowles wrote:

If you are looking at creating a converter -->to<-->from<-- Docbook.. Abiwords xml file format would be not that difficult to write a mapping application

What I want to write is a *simple* system that allows programmers to write documentation as easy as pie, as they can use a techniqe (HTML) all of them know without having to invest time into learning Docbook (even if it only takes 1/2 day). For the programmer this has the advantage that his package looks kinda complete since it comes with a end-user documentation. For us this has the advantage that much more contributors to PEAR will write a documentation for their package, which will make PEAR more acceptable.

I didnt really want to add large amounts of html code to the phpdoc comments, but a few

You should be able to add HTML to the inline comments already, no? (Actually I haven't tried it myself so far, but I'm pretty sure I saw it one time.)

I think the idea is to try and avoid having multiple documentation locations, with the same information - that have to be kept up to date..

IMO the PHPDoc documentation should point out the technical details of the package. Documentation targeted to novice users of the package shouldn't be created from the API documentation, since they usually only want to know how they can use the package - they aren't interested in the deepest technical things.