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.
--
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
| 
