Gabor Hojtsy wrote:
> 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.
This is very extremely and unlikely case. Documentation is not like
system administration where you must fixed broken configuration file in
as few minutes as possible. You usually write phpdoc with your popular
editor in your customized environment.
> 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
Customizing (extending/subseting) DocBook doesn't affect processing
tools. Only thing you must to do is to customize stylesheets to handle
new elements. This is very easy usually.
> 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
The biggest problem here is inconvience for authors. DocBook is standard
for writing documentation in a same sense as HTML is standard for
marking up web-pages. Authors doesn't want to learn new markup language
twice a year.
> So what about inventing some shortcut tags for
> our problematic parts add some tags to DocBook,
Shortcutting is issue of editing environment. This is not reason for
modifying DTD. If you think that DocBook XML markup is too verbose you
can swith to SGML version and use all its minimalization features.
Sounds strange? Yes, in these days when we have very powerful computers
it is very easy to use enough clever software which will hide you from
markup editing complexities.
> remove those we never use and name the language
> eg. PHPBook. This way we would have a simple
Removing unused tags (subseting DocBook) is another issue. This could
have very positive asset.
Jirka
--
-----------------------------------------------------------------
Jirka Kosek
e-mail: [EMAIL PROTECTED]
http://www.kosek.cz
