Re: advice for pre-generating documentation

[Gaetan Nadon]

On Fri, 2010-02-12 at 12:21 +0100, Steffen Dettmer wrote:

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

I don't like it either, the makefile gets complicated and error prone.
The main argument is that not all platforms have the tool so they would
not be able to install the doc. I think there are other ways to handle
such situation like publishing doc-only tarballs. The docs are not
binaries and don't have to be built on each platform. 

If you can avoid putting doc generated files in the tarball, you will
save yourself the trouble.

> 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?
> 
> oki,
> 
> Steffen
> 
>

signature.asc
Description: This is a digitally signed message part