Re: Format for documentation?

[Martin G. <gim...@gi...>]

Ondrej Jombik <ne...@po...> writes:

>                                         Maxim, 22:51:23
>                                         06. jun 2002 (stvrtok)
> Greetings.
>=20
> 	I think DocBook is the right solution. It is designed for
> documentation like that what you want.

Yes, I can see that this is one of the strengths of DocBook.

That was the problem with plain LaTeX: I had to invent all the
commands myself, and I had to take care of making them robust (there's
a number of LaTeX special characters in LaTeX and many of them are
used in PHP-code).

But Texinfo is also designed to make documentation... and because it's
a macro-package for TeX, then I felt more comfortably with it :-)

> Of course dynamic examples cannot be included, but anyway you can
> include link to examples on phpWeather website.

Yes, that would be an OK solution.
=20
>>     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?
>=20
> 	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.

Why not? Don't you get tired of typing all those long tags again and
again? Texinfo also has a bunch of tags, but they're at least as short
as their DocBook counterparts.
=20
> 	The question is, if it will be DocBook anymore, also after
> that DTD change.
>=20
>>     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?
>=20
>         I don't think that output of DocBook into PDF ans PS is bad.
> I use it very often and it looks good.

It's just that I'm used to the output from LaTeX - it's probably a
matter of adaptation, the output doesn't look as bad today as it did
yesterday :-)

But I still think, that it looks strange when the text is indented
about an inch while the headings are left at the left margin.

Also, then spacing around the paragraphs, lists and displayed code is
"funny"... The worst thing is how the <term>'s in a <variablelist> is
at the left margin together with the headings.

Take a look here:

  http://www.gimpster.com/temp/phpweather-doc/

I've converted the Texinfo docs I've written into DocBook. I then went
through the DocBook file and fixed it a little (removed some empty
<para></para> tags an so on...)

> 	For developer documentation you have tools like Doxygen
> (mailly C/C++ sources), JavaDoc (mainly Java sources) and PHPDoc (of
> course mainly PHP sources).

Yes, I know - I've used all three systems :-) I actually like Doxygen:
it generates very nice HTML and LaTeX output. It's a shame that it
doesn't grok PHP code yet...

> 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.

We're already using PHPDoc in PHP Weather. Speaking of PHP Doc: is it
still being worked on? phpdoc.de haven't been updated in about two
years and the phpdoc I was able to find at cvs.php.net is behaving
strange: it eats the first word in the documentation of each
function/variable/etc...

=2D-=20
Martin Geisler                       My GnuPG Key: 0xF7F6B57B

See my homepage at http://www.gimpster.com/ for:
PHP Weather =3D> Shows the current weather on your webpage.
PHP Shell   =3D> A telnet-connection (almost :-) in a PHP page.