[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: advice for pre-generating documentation

From: Steffen Dettmer
Subject: Re: advice for pre-generating documentation
Date: Fri, 12 Feb 2010 12:21:24 +0100

On Thu, Feb 11, 2010 at 5:08 PM, Gaetan Nadon <address@hidden> wrote:
> generated using tools such as doxygen, asciidoc, xmlto, groff, and
> ps2pdf. I can state some reasons why generated docs and included in the
> tarball:

This is interesting and many seem to agree here, but I think this is wrong.
In my team we made bad experiences and now have the rules that:
- a file either is autogen OR in CVS/SVN but not both
- a file either is generated by make OR in srcdist
- generated files (doxygen, libs) are in bindist only
If someone wants to read the compiled documentation (be it HTML or
PDF) or just use any other compiled object (such as a lib), he should
use a bindist or a webbrowser.

We use doxygen is most cases only for API documentation (I think this
is the normal case), but our developers here usually seem never to
read the HTML doc but read the .h (.java...) files.

Including documentation may also be wrong when it is conditional, but
this might be a special case.

When CVS snaps or alike, let's say you check out trunk HEAD and run
make dist, the generated documentation also might be invalid for
example because required Change History information may not be filled
or so. I think typically someone can expect valid documentation only
from released versions.

I think with doxygen it is difficult to get the decencies right, don't
know if it even works, so how do you update the documentation? Are you
re-generating it when running make dist?

> 1) convenience
> 2) the target platform building the tarball does not have the tool
> 3) the target platform building the tarball has the tool, but at the
> wrong version
4) the target may have the tool but different (compatible or
incompatible) dependencies leading to different files be generated
(might be less important for documentation).

> 3) unconditionally add html generated files in EXTRA_DIST: this will
> cause 'make dist' to fail if the platform creating a tarball does not
> have the doc tool.

So in each srcdist you include all the HTML, PDF, man pages and
whatever files generated, right? Is this the intended "automake way"?
I just looked to some arbitrary lib and it has 8 MB sources but 20 MB
doc (just HTML+PDF), so it would bloat up srcdist a lot...
How to avoid to include outdated documentation?

>        EXTRA_DIST = all the html and doxygen files listed here

Does this mean to list all files individually here? In my example case
I had to list 1422 files, wow...
But how to maintain that? If anyone documents some struct somewhere, a
new file will be generated, but how to know what to add to EXTRA_DIST?
Do you create/use some include filelist.mak or so?



reply via email to

[Prev in Thread] Current Thread [Next in Thread]