Preliminary mod_smtpd doc work

[rian <ri...@MIT.EDU>]

Hi,

I'm planning on starting initial mod_smtpd documentation work. I just
wanted to poll the list on what type of documentation format is
preferred, especially among the mod_smtpd hackers.

These are the options I know of:

1. DocBook
2. Texinfo
3. Latex
4. Doxygen

Personally I would prefer something in DocBook, than Texinfo and Latex
because I don't know much about the formatting language and DocBook
seems pretty intuitive and can be converted into a large amount of
formats. Also I suspect the mod_smtpd documentation will contain a lot
of examples since it has specific applications (spam filtering, message
translation, different queuers, extending SMTP command set). In my
experience Doxygen is usually pretty cryptic and not very helpful and
it's usually just easier to look at the source files yourself instead of
bother Doxygen.

Of course this work will come after some bug fixes, minor interface
changes, and code reviews.

Thanks.

Rian Hunter

Re: Preliminary mod_smtpd doc work

[Garrett Rooney <ro...@electricjellyfish.net>]

On 9/28/05, rian <ri...@mit.edu> wrote:
> Hi,
>
> I'm planning on starting initial mod_smtpd documentation work. I just
> wanted to poll the list on what type of documentation format is
> preferred, especially among the mod_smtpd hackers.
>
> These are the options I know of:
>
> 1. DocBook
> 2. Texinfo
> 3. Latex
> 4. Doxygen
>
> Personally I would prefer something in DocBook, than Texinfo and Latex
> because I don't know much about the formatting language and DocBook
> seems pretty intuitive and can be converted into a large amount of
> formats. Also I suspect the mod_smtpd documentation will contain a lot
> of examples since it has specific applications (spam filtering, message
> translation, different queuers, extending SMTP command set). In my
> experience Doxygen is usually pretty cryptic and not very helpful and
> it's usually just easier to look at the source files yourself instead of
> bother Doxygen.

I don't see Doxygen as filling the same role as DocBook/Texinfo/Latex.
 Doxygen gives you API docs, the other three give you a format to
write more general documentation.  Personally, I'd suggest doxygen for
the API docs and DocBook for higher level documentation on how to use
and extend the system.

-garrett

Re: Preliminary mod_smtpd doc work

[Mads Toftum <ma...@toftum.dk>]

On Wed, Sep 28, 2005 at 12:59:37PM -0400, Joshua Slive wrote:
> rian wrote:
> >4. Doxygen
> 
> You should also consider the httpd-docs format discussed at
> http://httpd.apache.org/docs-project/docsformat.html
> which is xhtml-based with some extra (docbook-like) structure thrown on 
> top.  If you want to be able to integrate into the existing docs, then 
> this would be the way to go.
> 
+1 for module usage documentation, anything elshe should be -1^Wstrongly 
discouraged. But that said, doxygen is what is already used for the inline 
api docs, so that's fine for documenting the functions.

vh

Mads Toftum
-- 
`Darn it, who spiked my coffee with water?!' - lwall

Re: Preliminary mod_smtpd doc work

[Joshua Slive <jo...@slive.ca>]

rian wrote:
> Hi,
> 
> I'm planning on starting initial mod_smtpd documentation work. I just
> wanted to poll the list on what type of documentation format is
> preferred, especially among the mod_smtpd hackers.
> 
> These are the options I know of:
> 
> 1. DocBook
> 2. Texinfo
> 3. Latex
> 4. Doxygen

You should also consider the httpd-docs format discussed at
http://httpd.apache.org/docs-project/docsformat.html
which is xhtml-based with some extra (docbook-like) structure thrown on 
top.  If you want to be able to integrate into the existing docs, then 
this would be the way to go.

Joshua.