[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: eliminating conf.texi
From: |
Rik |
Subject: |
Re: eliminating conf.texi |
Date: |
Wed, 02 Dec 2009 11:57:11 -0800 |
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.