Documentation is not distributed.

[Jari Häkkinen]

related to ticket:278

The doc subdirectory is almost empty (Makefile.am and Makefile.in are distribution) when a distribution package is created with 'make dist'. There are Automake directives to include files and directories in the distribution.

[Peter]

added relationship with ticket:278

[Peter]

What is the plan here?

To include source files needed for generating documentation, or to include already generated documentation?

[Jari Häkkinen]

Replying to peter:

What is the plan here?

To include source files needed for generating documentation, or to include already generated documentation?

Both.

[Peter]

Sure, we can not distribute a pdf without source files such as .tex files. Yat is an open project.

Next obvious question: if documention is included in distribution, will make doc regenerate the documentation? If yes, the warnings in configure on "You have no doxygen..." is still relevant but somehow misleading. If no, they are simply wrong.

It is possible to detect whether this is a dist or not and insert conditionals on this in Makefile.in. See e.g. svndigest. In that way one could make make doc to do nothing. However, here I think I prefer to keep the makefiles to be similar in checkout and dist. I suppose it is less error prone.

[Jari Häkkinen]

Replying to peter:

Next obvious question: if documention is included in distribution, will make doc regenerate the documentation?

No, if the source files are not changed, make should figure out that the targets are up to date.

If yes, the warnings in configure on "You have no doxygen..." is still relevant but somehow misleading. If no, they are simply wrong.

To get the doxygen warning you need at least to enable debugging, if you enable debugging you are doing something more than installing the package. My response to the previous question was no but I think the message is correct, you will not be able to generate documentation. Of course, the documentation is already there. Issuing 'make clean' will remove the generated files ... alas the docs must be secured in a distribution (i,e., protected from a make clean).

[Peter]

Replying to jari:

Replying to peter:

Next obvious question: if documention is included in distribution, will make doc regenerate the documentation?

No, if the source files are not changed, make should figure out that the targets are up to date.

Ok, that dependency it currently not there. Source files in this context is header files, right?

If yes, the warnings in configure on "You have no doxygen..." is still relevant but somehow misleading. If no, they are simply wrong.

To get the doxygen warning you need at least to enable debugging, if you enable debugging you are doing something more than installing the package. My response to the previous question was no but I think the message is correct, you will not be able to generate documentation. Of course, the documentation is already there. Issuing 'make clean' will remove the generated files ... alas the docs must be secured in a distribution (i,e., protected from a make clean).

Ok, I agree. I thought the condition on enable-debug was removed, but it was only the tab that was removed. Then it is fine.

[Jari Häkkinen]

Replying to peter:

Ok, that dependency it currently not there. Source files in this context is header files, right?

Hm ... yes? I'll call you back on this one.

Ok, I agree. I thought the condition on enable-debug was removed, but it was only the tab that was removed. Then it is fine.

I had to remove one level of tabs becauese the message from configure became ugly. Write nicely formatted messages with the AM macros is not a simple thing.

[Peter]

Replying to jari:

Replying to peter:

Ok, that dependency it currently not there. Source files in this context is header files, right?

Hm ... yes? I'll call you back on this one.

It seems like doxygen's mechanism of tag files can help us here. The idea is to turn the dox generation into a two step procedure. First, create a tag file for each directory/namespace. Second, compile the tag files into html pages or whatever format we want. How does this help? The fact that we create one tag file per directory implies that we can trigger the generation from the corresponding Makefile, which in turn implies that we can add the wanted dependencies. For instance, in yat/utility one would add dependency to include_utility_HEADERS

[Peter]

An easier way is probably to work with time-stamp files. Somehow we could add

doxygen.stamp: $(include_utility_HEADERS)
	@echo `date` > doxygen.stamp 

in yat/utility/Makefile.am and correspondingly in other src Makefile.am.

Either doxygen.stamp is local or one has one doxygen.stamp file located in doc. Which solution is preferable depends much on what type of dependency we are aiming for.

Ideally the timestamp should be checked prior every call to Doxygen. Therefore a good solution might be to call cd yat/utility; make doxygen.stamp and so on in each of the src dirs.

[Peter]

Replying to jari:

Replying to peter:

What is the plan here?

To include source files needed for generating documentation, or to include already generated documentation?

Both.

Distributing generated files adds some complexity. The problem is whether the generated file should be considered to be src or not, in other words, does the files appear in @srcdir@ or in @builddir@? Well it depends, is the simple answer but that answer is not good enough. This is similar to how GNU projects often generate .info file from a .texi file and the .info file is distributed. I think we should look at how autotools generate rules for this case, and then copy the design somehow.

[Peter]

Seems like .texi files are generated in @srcdir@, which makes sense. Following that choice, files that are distributed would be built in @srcdir@.

[Peter]

Some unexpected obstacles. Files generated by Doxygen in doc/latex/ have extremely long filenames. This causes problem for my gtar, which doesn't accept filenames longer than 99 chars.

This makes me doubtful whether it was a wise decision to distribute generated documentation. It would be much easier to only distribute source code. It would make building from a dist and from a svn wc more similar. Also, if we are concerned about users not having doxygen, we can provide documentation of latest release through Trac page. HTML is already provided there and we could add a PDF for download.

Opinions?

[Jari Häkkinen]

Replying to peter:

Some unexpected obstacles. Files generated by Doxygen in doc/latex/ have extremely long filenames. This causes problem for my gtar, which doesn't accept filenames longer than 99 chars.

This makes me doubtful whether it was a wise decision to distribute generated documentation. It would be much easier to only distribute source code. It would make building from a dist and from a svn wc more similar. Also, if we are concerned about users not having doxygen, we can provide documentation of latest release through Trac page. HTML is already provided there and we could add a PDF for download.

Opinions?

We can settle for docs through trac only. There is a README file where we can add links to the documentation. I can live with this.

[Peter]

(In [1265]) Changing so generated docs are not distributed and consequently docs can be generated in builddir