Re: Converting HTML to Docbook

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 eg. direct mapping of <ulink> maps to ... <c style="ulink"> <title> maps to ... <p style="title"> etc. Which would be a bit more fun :) - althought there would still be no validity checking :( Ok, I was thinking about doing this next week - I reconned about 3-4 hours to add it to PHP_CodeDoc. I didnt really want to add large amounts of html code to the phpdoc comments, but a few Simple Mail type 'From:' Tags should be (a) easy to parse (b) easy to type (c) easy to read.. This could form the basis of the solution - and anything that is not delt with this way can be done with a few HTML type tags. looking at the problem: we need to map 'something' in the comments of a php file (pear class etc) to docbook format: This is a striped down docbook consists of something like this /********* PAGE INDEX *********/ some paragraphs - this appears on the main index page for the package) /******** PAGE: Introduction *********/ pagesummary: some text (Refpurpose) /********* Introduction *********/ (some paragraphs - this is the body of the introduction) /********* PAGE: Config Options *********/ pagesummary: some text (Refpurpose) /********* Required Options *********/ SETTINGSLIST: parameter: database type: dsn (some notes about ) .... /********* PAGE: Doing stuff methods *********/ refpurpose: Expain what doing stuff is all about This stuff should be ok autogenerating from the phpdoc comments: *<refsect1>*

     *<title>*{From phpdoc}*</title>*

*<para>*

     {From phpdoc: - have we got a 1 liner tag in phpdoc}
     *</para>*
     *<funcsynopsis>*
       *<funcprototype>*
         *<funcdef>**<function>*{from phpdoc}*</function>**</funcdef>*
         *<paramdef>*{from phpdoc} *<parameter>*{from phpdoc}*</parameter>**</paramdef>*
         *<paramdef>*{from phpdoc} *<parameter>**<optional>*{from phpdoc}*</optional>**</parameter>**</paramdef>*
       *</funcprototype>*
     *</funcsynopsis>*

An example method header: | /** * Summary: get an result using key, value * * * Returns number of rows located (usually 1) for success, * and puts all the table columns into this classes variables *

||    * Example: example1.php

* This would return exectute the following SQL * Example: example1.sql * And output the following * Example: text * * hello world * * /Example: *

||    * see also DB_DatabObject::fetch()

* * if no value is entered, it is assumed that $key is a value * and get will then use the first key in _get_keys * to obtain the key. *

   * @param     string     key column
   * @param     string     key value
   * @access    public
   * @return     int No. of rows

*/| /* ----------------------------------------------- HTML Tags that would be usefull: <UL|OL> <LI> For lists - as I cant think of any other clean way to do anything like this <tt> </tt> <- what would this map to - i'm sure there is a tag <b> </b> <= emphasis..????

<a href=""> </A>     <= maps to ulink

|DB_DatabObject::fetch() <- class:method() should map to a ulink to that page... somehow.| ----------------------------------------------------------------------------------- In summary above: The tags that would be recognized: @packageTitle ???? /********* PAGE: INDEX *********/ - for the index page and partintro

/********* PAGE:xxxx        ********/  - for page breaks wth title
/********* xxxxxxx              ********/  - for sect1 titles
pagesummary:            (maps to refpurpose)
SETTINGSLIST:     <for a variablelist,entry etc.
parameter:               <- for parameter part of var list
type:                      for type part of var list
Example: (php) Title                For small embedded examples

(some code here....) /Example:

Example: (html) Title                For small embedded examples

(some code here....) /Example: Example: (see example1.php) Title Goes here.... (<--includes a file from the example folder - use the extension to determine 'type') --------------------------------------------------------------------------------------- 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.. Docbook is not really that much more difficult than html - it only took me a day to write and learn the first manual - and about 1/2 a day for all the others. so I'm not that sure why having a html version would be that advantagos.. As we have discovered with the weekly news - html although it has a WYSIWYG editor, does have a habit of spitting out 'crap' html :) anyway not to put you off the idea... :) best regards alan Martin Jansen wrote:

Hi, the following text describes my plans for HTML2Docbook converter for PEAR. A programmer can use some very basic HTML tags in order to create his documentation for the package. This tags are: * <h1 /> * <h2 /> * <p /> * <code /> * <tt /> * <a /> <h1 /> is the title of the package (e.g. 'XML_RSS'). <h2 /> starts a new subelement (e.g. 'Introduction' or the documentation of a function). <p /> defines a paragraph with text while <code /> defines a sourcecode listing (aka PHP example code). <tt> can be used to point out filenames during texts in paragraphs. <a /> can either define internal or external links. Perhaps we could even abuse <div> to start special areas of the documentation (like examples, warning or notes). This layout still misses things like semi-automated function definitions (parameters, return value etc.), but it should be enough to give a programmer, who does not want to mess around with Docbook, the ability to write documentation, that can be automatically integrated into the manual. At a later point we will perhaps even be available to create a (HTML-) skeleton from the PHPDoc comments, which can be edited by the programmer, but for now I think this system should work out pretty well. Please comment on this and tell me your suggestions. I hope to be able to start working on this next weeek (this is when I'll also try to finish a first version of the PEAR bug reporting interface). After that I will be on vacation for two weeks with no PEAR, PHP or email at all.