Hi!
After getting home from the doc meeting, I decided to
propose this idea about having a simplified XML language
on top of DocBook for phpdoc stuff.
This idea may be completely useless, or may be accepted
to implement in the future. First it seemed to me a good
idea, so I decided to write it down. This does not mean,
that it is good at all ;)
I) *So* what is the problem?
We have problems with some really cluttered
DocBook elements. Just think about a listitem.
You always need to put at least a simpara into a
listitem. What do you need to insert if you
would like to put in some PHP code? A
programlisting with role="php"... And I think
everybody remembers the discussions about using
a container tag for see alsos, and a list tag
in it, with paras in each list item, with
the linked endpoint in each para. Huh.
II) *So* how can we solve the problem?
a) Macros in editors and/or using XML editors...
Advantage: no need to modify xml files and/or
the used language
Problem: sometimes you have no XML
editor at hand, and this won't make our
XML code readable. Cluttered xml files.
b) Customize DocBook, write own stye sheets
for processing new tags, and customize
the DTD
Advantage: using our own tags, readable
XML files
Problem: there are ready made tools
for docbook, and this would make the
usage of those tools impossible or at
least hard
c) Build a new language on top of DocBook,
and provide some simple conversion style
sheets from our language to DocBook.
Advantage: using our own tags, readable
XML files, simple DTD (only those tags we use)
Problem: more processing time, DocBook
as an intermediary language
Now I would like to extend point c) as this is
a new idea (and quite interesting in my eyes).
This may be good for our needs.
So what about inventing some shortcut tags for
our problematic parts add some tags to DocBook,
remove those we never use and name the language
eg. PHPBook. This way we would have a simple
language, which we can convert to DocBook anytime
to use the DocBook tools already available.
What we only need to do is to run a simple 1-2KB XSLT
sheet on all XML files before we run the HTML / FO sheets
on them. I don't think so that the [probably very
small] performance decrease would be less then the
ease of editing.
An example:
DocBook:
<itemizedlist>
<listitem>
<simpara>
text in here
</simpara>
</listitem>
<listitem>
<simpara>
more text in here
</simpara>
</listitem>
</itemizedlist>
PHPBook:
<itemizedlist>
<listitempara>
text in here
</listitempara>
<listitempara>
more text in here
</listitempara>
</itemizedlist>
For php codes:
<programlisting role="php">
<![CDATA[
php code here
]]>
</programlisting>
<phpcode>
<![CDATA[
php code here
]]>
</phpcode>
So this would be a wrapper around DocBook, as
we can map all our new tags to DocBook equivalents
with *extremely* simple XSLT sheets.
This way we can invent any easy XML syntaxes for
see also lists for example, like:
<seealsolist>
<function>echo</function>
<link linkend="configure.session">Session stuff</link>
</seealsolist>
Then we can convert this automatically to any
valid DocBook XML stuff to take advantage of ready
made XSLT sheets and conversion programs.
I can volunteer in the creation of these simple
XSLT sheets, and the PHPBook DTD (simplified and
extended DocBook) if we can come up with some
structures to ease our lives.
And remember, that this idea may be completely useless,
but may be good enough to implement. We need more
discussion on this ;)
Goba
