Re: Format for documentation?

[Ondrej J. <ne...@po...>]

                                        Maxim, 22:51:23
                                        06. jun 2002 (stvrtok)
Greetings.

	All written here will be only my opinion. It could be wrong, so than
please correct me. Maybe your opinion will be different, so feel free to
disagree with me.

> Although I'm in the middle of my exams (Probability Theory tomorrow!),

	Combinatoric analyze (called as combat ;-) tomorrow.

>   Docbook: With all the buzz about SGML and XML, I thought that
>     Docbook would be the thing to use... I've tried it, but I don't
>     particularly like it. The good thing about Docbook is, that it's
>     designed for this task: there's tags for filenames, code examples
>     and so on.

	I think DocBook is the right solution. It is designed for
documentation like that what you want. Of course dynamic examples cannot be
included, but anyway you can include link to examples on phpWeather website.

>     But Docbook is a very verbose markup language because all tags has
>     to be closed, and because the tag-names are long: they use <para>
>     instead of just <p>. Can this be changed?

	It is possible to create new <p> tag. Its behaviour will be the same
as <para>. It is possible with some addition to DTD, but I don't know how,
because I never need this feature.

	The question is, if it will be DocBook anymore, also after that DTD
change.

>     Docbook can be converted to HTML which looks good. It can also be
>     converted into PDF and PS which looks very bad. I don't know why,
>     but the Docbook source is converted into a strange mess which can
>     only be processed by jadetex. Why not just convert it into good-
>     looking LaTeX-code?

        I don't think that output of DocBook into PDF ans PS is bad. I use
it very often and it looks good. HTML is preffered, usege of PS desirable,
when you want to print whole, part or parts of documentation.

> So, what do you guys think? Which formats do you know and which formats do
> you like?

	I strictly difference two types of documentation: user and
developer. DocBook is ideal for generating user documentation.  But its not
good for developer documentation.

	For developer documentation you have tools like Doxygen (mailly
C/C++ sources), JavaDoc (mainly Java sources) and PHPDoc (of course mainly
PHP sources). You will use special tags directly in source codes, such as
@author, @param to mark module, function, method or variable. Appropriate
tool will generate well-arranged documentation for you.

	So my conclusion: DocBook for user documentation, PHPDoc for
developer documentation. I wish you a good decision.

	=Nepto=
____________________________________________________________________________
Ondrej 'Nepto' Jombik, http://www.nepto.sk/              ne...@at...