Re: eliminating conf.texi

[Rik]

John W. Eaton wrote:
> On 30-Nov-2009, Rik wrote:
>
> | John W. Eaton wrote:
> | > On 30-Nov-2009, Rik wrote:
> | >
> | > | Yes, that sums up the decision.  Currently, we require texinfo to be
> | > | installed on the build host which isn't terrifically onerous, but we
> | > | could get rid of the requirement altogether if we choose to rewrite the
> | > | few texi files which actually depend on conf.texi.
> | >
> | > I'm willing to consider not generating conf.texi, or generating it at
> | > configure time and only having it contain things like VERSION so that
> | > doesn't have to be changed by hand in the sources.  But I'm not sure
> | > how to correctly handle the conditional variables like HAVE_COLAMD.
> | >   
> | I'll think about this.  I don't know the best way to handle the
> | conditional variables either which is why I left it alone for the time
> | being.
>
> I did some more work on getting make distcheck to complete and now I'm
> thinking that we should try to remove the conditional variables from
> conf.texi.
>
> As I see it, we have a some options.
>
>   1. Require that HAVE_COLAMD, HAVE_CHOLMOD, HAVE_UMFPACK, and
>      HAVE_QHULL are all defined in order to run "make dist" (so that
>      all the figures for the manual can be generated).
>
>   2. Omit the figures that can't be generated (use some kind of
>      placeholder text).
>
>   3. Same as 2, except also cache the values of HAVE_COLAMD,
>      HAVE_CHOLMOD, HAVE_UMFPACK, and HAVE_QHULL at the time the
>      distribution is created, then build new copies only if the cached
>      values are false and the features are available on the system
>      where the distribution file being built.
>
> I'm leaning toward option 1 since it means that the manual in a
> distribution file will always be complete.  I don't think it is
> unreasonable to require that anyone making a distribution file has all
> the dependencies.  OTOH, we can make it relatively easy to still allow
> building without the dependencies (option 2) but I don't care if you
> have to edit the configure script or a Makefile to allow that to
> work.  To me, option 3 just seems like too much work for little
> benefit.
>   
I think we should begin by implementing option 1.  This only affects a
small group of people, maintainers, and the majority of people won't
need to do anything because complete documentation will now be shipped
with the distribution.  It will also save a bit on compile time for the
distribution since the documentation will have been pre-compiled. 

Another advantage is reducing the need to fix VPATH builds for the
documentation.  Currently, all the dependencies are correct if builddir
== srcdir.  I've been trying for a few days now to jigger the TEXINPUTS
variable so that VPATH build works, but I have not had any success and
it is not an enjoyable exercise.

> I propose to eliminate the top_srcdir, abs_top_srcdir, and OCTAVEHOME
> variables by editing the sources and finding another way to include
> the example files in the manual that does not require setting
> top_srcdir or abs_top_srcdir in the .texi sources.
>   
In doc/liboctave there are three references to @value{VERSION} which are
the only true dependencies introduced by conf.texi.  It appears to me
that by simply re-phrasing the documentation we could eliminate the
conf.texi dependency.

Reference 1:
@subtitle{Edition 1.0 for Octave version @value{VERSION}}

Suggestion:
Simply document the version of the documentation (1.0) and perhaps put a
hard-coded reference to the octave version where the class stuff was
introduced.
@subtitle{Edition 1.0 for Octave versions > 2.XX}

Reference 2:
This is the first edition of the documentation for Octave's C++ classes,
and is consistent with version @value{VERSION} of Octave.

Suggestion:
Same as reference 1.  Change the version to a hard-coded value
indicating what minimum version of Octave this documentation is good for.

Reference 3:
This manual documents how to use, install and port Octave's C++ class
library, and how to report bugs.  It corresponds to Octave version
@value{VERSION}.

Suggestion:
Same as reference 2.  This is just the ifnottex version of reference 2
and should be changed in the same way.