[PPL-devel] Ocaml docs being built even though interface is not enabled

[Michael Tautschnig]

> Michael Tautschnig wrote:
>> [...]
>>> [NOTE: the actual reason I am telling all of this is that I would 
>>> like  to know if there are better ways of solving the issue ...]
>>>
>>
>> I guess I don't really know all of the story, but I simply wonder why you
>> distribute the pre-built docs at all? Why not have them built, just like all the
>> other stuff? To me it seems that building the documentation takes quite some
>> time, but the checks take even more, so why bother?
>
> We do not want ordinary users to depend on tools such as doxygen,  
> graphviz, etc., in order to obtain the user documentation.
>
If this is the case, wouldn't it actually make sense to ship a
ppl-<version>-doc.tar.gz archive with pre-built documentation? I think it
shouldn't be too hard to have "make dist" build an additional archive, and
probably you have some script that takes care of uploading the snapshots, so
this should also scale.

Not that I'd see a really big problem here, but it would just make things a bit
cleaner.

>> One other note (I'm not sure whether this still applies to pre36, it was true as
>> of pre35): You overwrite the all target of doc/Makefile by a no-op, which is
>> inconsistent with the other targets, which have their usual meaning. To some
>> extent, it makes sense because you intoduce more targets (like user-configured,
>> etc.). But wouldn't it also be an option to just remove doc from the SUBDIRS
>> entry in the top-level Makefile.am and have users always do the stuff manually
>> in doc/? Which, of course, means that we need to run make -C doc clean, make -C
>> doc install, etc. Just an idea.
>
> I will have to think a bit more about this last proposal ...
> and maybe also read some more of the autotools' documentation.
>

You might want to take a look at the autobook, in case you don't know about it.
I guess your knowledge is way beyond of what is presented there, but it really
has some nice considerations about the general workflow. It's available online:

http://sources.redhat.com/autobook/

Best,
Michael