Minimum Texinfo version for creating the documentation

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

Minimum Texinfo version for creating the documentation

Rik-4
All,

Currently the minimum Texinfo version required for creating the Octave
manual is something ancient like 4.13.  Recent changesets use features from
5.0 (Feb. 2013) and 6.1 (Feb. 2016).  These really improve the appearance
of the manual, but aren't necessarily available on ancient systems.  Given
that Octave creates the manual and distributes it in the tarball, is it
okay to bump up the required Texinfo to 6.1?  Developers on older systems
can use '--disable-docs' to concentrate on just the Octave core, or they
can compile and install newer versions of Texinfo.

--Rik

Reply | Threaded
Open this post in threaded view
|

Re: Minimum Texinfo version for creating the documentation

Mike Miller-4
On Thu, Jan 04, 2018 at 09:26:16 -0800, Rik wrote:
> Currently the minimum Texinfo version required for creating the Octave
> manual is something ancient like 4.13.  Recent changesets use features from
> 5.0 (Feb. 2013) and 6.1 (Feb. 2016).  These really improve the appearance
> of the manual, but aren't necessarily available on ancient systems.  Given
> that Octave creates the manual and distributes it in the tarball, is it
> okay to bump up the required Texinfo to 6.1?  Developers on older systems
> can use '--disable-docs' to concentrate on just the Octave core, or they
> can compile and install newer versions of Texinfo.

It would be helpful to continue to support Texinfo 5.2 at a minimum for
now (Debian 8.0 and Ubuntu 14.04).

--
mike

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Minimum Texinfo version for creating the documentation

Daniel Sebald
On 01/04/2018 01:48 PM, Mike Miller wrote:

> On Thu, Jan 04, 2018 at 09:26:16 -0800, Rik wrote:
>> Currently the minimum Texinfo version required for creating the Octave
>> manual is something ancient like 4.13.  Recent changesets use features from
>> 5.0 (Feb. 2013) and 6.1 (Feb. 2016).  These really improve the appearance
>> of the manual, but aren't necessarily available on ancient systems.  Given
>> that Octave creates the manual and distributes it in the tarball, is it
>> okay to bump up the required Texinfo to 6.1?  Developers on older systems
>> can use '--disable-docs' to concentrate on just the Octave core, or they
>> can compile and install newer versions of Texinfo.
>
> It would be helpful to continue to support Texinfo 5.2 at a minimum for
> now (Debian 8.0 and Ubuntu 14.04).

The easiest thing would be to put conditional statements around the
command that controls the code

@ifWISHTHEREWEREVERSIONING
@codequoteundirected on
@end

and to define sortas() to be nothing

@ifWISHTHEREWEREVERSIONING
@macro sortas{param1}
@end macro
@end

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040ifset-_0040ifclear.html#g_t_0040ifset-_0040ifclear

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Defining-Macros.html#Defining-Macros

and those using old Texinfo will simply lose out.  Unfortunately there
doesn't seem to be a means of getting the Texinfo version internal to
Texinfo itself (I was unfamiliar with Texinfo up until a week ago).

So, we could somehow create and inject some definitions into the Texinfo
configuration at the "configure" stage.  That is, we can get version from

"
linux@ ~ $ texi2dvi --version
texi2dvi (GNU Texinfo 6.1) 6991

Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later
<http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
"

and based on the version number somehow add

@set NO_SORTAS_SUPPORT
@set HAVE_CODEQUOTEUNDIRECTED

to one of the Texinfo files.  (Should be an easy thing to append to the
end of some file via some shell script like "cat".)

Then if in the Texinfo macro file we condition with

@ifset HAVE_CODEQUOTEUNDIRECTED
@codequoteundirected on
@end

@ifset NO_SORTAS_SUPPORT
@macro sortas{param1}
@end macro
@end

that should be it.

Dan

Reply | Threaded
Open this post in threaded view
|

Re: Minimum Texinfo version for creating the documentation

John W. Eaton
Administrator
On 01/04/2018 04:26 PM, Daniel J Sebald wrote:

> and based on the version number somehow add

If we decide to do something like this, then in the name of autoconf and
all that is good, could we please do it using feature tests instead of a
version number?

Thanks,

jwe


Reply | Threaded
Open this post in threaded view
|

Re: Minimum Texinfo version for creating the documentation

Mike Miller-4
On Thu, Jan 04, 2018 at 16:33:19 -0500, John W. Eaton wrote:
> If we decide to do something like this, then in the name of autoconf and all
> that is good, could we please do it using feature tests instead of a version
> number?

+1

Can someone describe exactly what features of Texinfo 5 or 6 we are
using that won't work with an older version of Texinfo 4?

If we are only talking about the existence of the macros
@codequoteundirected and @sortas, those are defined in the texinfo.tex
file which we inherit from gnulib, so there might not be a problem at
all.

--
mike

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Minimum Texinfo version for creating the documentation

Daniel Sebald
On 01/04/2018 04:01 PM, Mike Miller wrote:

> On Thu, Jan 04, 2018 at 16:33:19 -0500, John W. Eaton wrote:
>> If we decide to do something like this, then in the name of autoconf and all
>> that is good, could we please do it using feature tests instead of a version
>> number?
>
> +1
>
> Can someone describe exactly what features of Texinfo 5 or 6 we are
> using that won't work with an older version of Texinfo 4?
>
> If we are only talking about the existence of the macros
> @codequoteundirected and @sortas, those are defined in the texinfo.tex
> file which we inherit from gnulib, so there might not be a problem at
> all.

Those are the only two.  See

https://savannah.gnu.org/bugs/?52775#comment3

It must be that the builder's system is recognizing some older version
of Texinfo ahead of what is in gnulib.  Perhaps that is a build bug.

Per JWE's idea, the following seems a minimal script example (first is a
valid macro name, second not):

linux@ ~/octave $ (echo "\input texinfo" && echo "@cindex @sortas{test}
ing" && echo "@bye") > testtexinfo.texi; texi2dvi --quiet testtexinfo.texi
linux@ ~/octave $ (echo "\input texinfo" && echo "@cindex @snortas{test}
ing" && echo "@bye") > testtexinfo.texi; texi2dvi --quiet testtexinfo.texi
/usr/bin/texi2dvi: etex exited with bad status, quitting.

I tried not needing the intermediate file, but it seems that texi2dvi
needs the name to verify the .texi extension.

Dan

Reply | Threaded
Open this post in threaded view
|

Re: Minimum Texinfo version for creating the documentation

Mike Miller-4
On Thu, Jan 04, 2018 at 16:26:26 -0600, Daniel J Sebald wrote:
> Per JWE's idea, the following seems a minimal script example (first is a
> valid macro name, second not):
>
> linux@ ~/octave $ (echo "\input texinfo" && echo "@cindex @sortas{test} ing" && echo "@bye") > testtexinfo.texi; texi2dvi --quiet testtexinfo.texi
> linux@ ~/octave $ (echo "\input texinfo" && echo "@cindex @snortas{test} ing" && echo "@bye") > testtexinfo.texi; texi2dvi --quiet testtexinfo.texi
> /usr/bin/texi2dvi: etex exited with bad status, quitting.

This works for me on Debian 7 with Texinfo 4.13.

First, just running texi2dvi without any path set to Octave's source
tree:

  $ (echo "\input texinfo" && echo "@cindex @sortas{test} ing" && echo "@bye") > testtexinfo.texi; texi2dvi --quiet testtexinfo.texi
  /usr/bin/texi2dvi: etex exited with bad status, quitting.

Now, running with TEXINPUTS set to Octave's source tree, as is done in
the current build process:

  $ export TEXINPUTS=:$HOME/octave/gnulib/build-aux:
  $ (echo "\input texinfo" && echo "@cindex @sortas{test} ing" && echo "@bye") > testtexinfo.texi; texi2dvi --quiet testtexinfo.texi

No error here. So this seems to be compatible with Texinfo 4.13.

--
mike

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Minimum Texinfo version for creating the documentation

Rik-4
In reply to this post by Rik-4
On 01/04/2018 01:33 PM, [hidden email] wrote:
Subject:
Re: Minimum Texinfo version for creating the documentation
From:
Daniel J Sebald [hidden email]
Date:
01/04/2018 01:26 PM
To:
Mike Miller [hidden email], [hidden email]
List-Post:
[hidden email]
Content-Transfer-Encoding:
7bit
Precedence:
list
MIME-Version:
1.0
References:
<MTAwMDAwMS5ub21hZA.1515086782@quikprotect> [hidden email]
In-Reply-To:
[hidden email]
Message-ID:
[hidden email]
Content-Type:
text/plain; charset=utf-8; format=flowed
Message:
7

On 01/04/2018 01:48 PM, Mike Miller wrote:
On Thu, Jan 04, 2018 at 09:26:16 -0800, Rik wrote:
Currently the minimum Texinfo version required for creating the Octave
manual is something ancient like 4.13.  Recent changesets use features from
5.0 (Feb. 2013) and 6.1 (Feb. 2016).  These really improve the appearance
of the manual, but aren't necessarily available on ancient systems.  Given
that Octave creates the manual and distributes it in the tarball, is it
okay to bump up the required Texinfo to 6.1?  Developers on older systems
can use '--disable-docs' to concentrate on just the Octave core, or they
can compile and install newer versions of Texinfo.

It would be helpful to continue to support Texinfo 5.2 at a minimum for
now (Debian 8.0 and Ubuntu 14.04).

The easiest thing would be to put conditional statements around the command that controls the code

@ifWISHTHEREWEREVERSIONING
@codequoteundirected on
@end

and to define sortas() to be nothing

@ifWISHTHEREWEREVERSIONING
@macro sortas{param1}
@end macro
@end

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040ifset-_0040ifclear.html#g_t_0040ifset-_0040ifclear

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Defining-Macros.html#Defining-Macros

and those using old Texinfo will simply lose out.  Unfortunately there doesn't seem to be a means of getting the Texinfo version internal to Texinfo itself (I was unfamiliar with Texinfo up until a week ago).

So, we could somehow create and inject some definitions into the Texinfo configuration at the "configure" stage.  That is, we can get version from

"
linux@ ~ $ texi2dvi --version
texi2dvi (GNU Texinfo 6.1) 6991

Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
"

and based on the version number somehow add

@set NO_SORTAS_SUPPORT
@set HAVE_CODEQUOTEUNDIRECTED

to one of the Texinfo files.  (Should be an easy thing to append to the end of some file via some shell script like "cat".)

Then if in the Texinfo macro file we condition with

@ifset HAVE_CODEQUOTEUNDIRECTED
@codequoteundirected on
@end

@ifset NO_SORTAS_SUPPORT
@macro sortas{param1}
@end macro
@end

that should be it.

Dan

Could certainly do this, but does it make sense that the Octave manual should appear differently from computer to computer?  While each computer might have different libraries installed and different features available, the Octave manual covers everything.  Imagine if Moby Dick started with "Call me Ishmael" in the U.S., but "Call me George" in the U.K.  It doesn't seem desirable to have that kind of variation.

But, maybe the answer is already in texinfo.tex as Mike suggests.  I did 'make dist-gzip' and then looked inside the resulting archive and there was definitely a texinfo.tex which included the sortas macro.

--Rik


Reply | Threaded
Open this post in threaded view
|

Re: Minimum Texinfo version for creating the documentation

siko1056
In reply to this post by Mike Miller-4
Mike Miller-4 wrote
> If we are only talking about the existence of the macros
> @codequoteundirected and @sortas, those are defined in the texinfo.tex
> file which we inherit from gnulib, so there might not be a problem at
> all.

Are the macros, defined in texinfo.tex, used for the HTML output as well?  I
assume this is where my build fails using Texinfo 4.13.

Kai




--
Sent from: http://octave.1599824.n4.nabble.com/Octave-Maintainers-f1638794.html

Reply | Threaded
Open this post in threaded view
|

Re: Minimum Texinfo version for creating the documentation

Carnë Draug
In reply to this post by Mike Miller-4
On 4 January 2018 at 22:01, Mike Miller <[hidden email]> wrote:

> On Thu, Jan 04, 2018 at 16:33:19 -0500, John W. Eaton wrote:
>> If we decide to do something like this, then in the name of autoconf and all
>> that is good, could we please do it using feature tests instead of a version
>> number?
>
> +1
>
> Can someone describe exactly what features of Texinfo 5 or 6 we are
> using that won't work with an older version of Texinfo 4?
>
> If we are only talking about the existence of the macros
> @codequoteundirected and @sortas, those are defined in the texinfo.tex
> file which we inherit from gnulib, so there might not be a problem at
> all.

Not sure if this is true.  Building in Debian jessie (version 8) which
has texinfo version 5.2 is currently failing due to "unknown command
`sortas'".

Carnë

Reply | Threaded
Open this post in threaded view
|

Re: Minimum Texinfo version for creating the documentation

Mike Miller-4
On Thu, Jan 18, 2018 at 12:39:13 +0000, Carnë Draug wrote:
> Not sure if this is true.  Building in Debian jessie (version 8) which
> has texinfo version 5.2 is currently failing due to "unknown command
> `sortas'".

You're right. I ran into that later and discussed on
https://savannah.gnu.org/bugs/?52775. The plan is to add a configure
test for the sortas macro and disable docs with a warning on any system
that doesn't support it (requires Texinfo 6.1 or newer).

--
mike

signature.asc (849 bytes) Download Attachment