bugGNU Octave - Bugs: bug #52775, PDF user manual uses a backward...


bug #52775: PDF user manual uses a backward apostrophe ` in code examples

Submitted by:  Dan Sebald <sebald>
Submitted on:  Mon 01 Jan 2018 04:12:54 AM UTC  
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  Closed
Release:  dev Operating System:  Any

Add a New Comment(Rich Markup)

You are not logged in

Please log in, so followups can be emailed to you.


( Jump to the original submission)

Mon 22 Jan 2018 10:06:28 AM UTC, comment #49:

Sorry for the late feedback. I confirm that the build of the documentation is disabled automatically and everything builds fine. Thank you all for sorting this out.

Guillaume <gyom>
Fri 19 Jan 2018 11:33:49 PM UTC, comment #48:

I incorporated your suggestions and pushed on default, this works fully for me now on older systems with Texinfo 4 and 5, case closed


Mike Miller <mtmiller>
Project Administrator
Fri 19 Jan 2018 10:58:59 PM UTC, comment #47:

Okay, you can revert that part of the cset. We definitely have two different styles in the configure warnings. The newer message style is terser

which I happen to like, but I don't care exceedingly.

Rik <rik5>
Project Administrator
Fri 19 Jan 2018 10:48:17 PM UTC, comment #46:

I really think the messages were more consistent with other messages the way they were. If a user tries to build without bison installed, it needs to be clear that your build will probably succeed unless you are trying to build from hg or patching a file or some other measure that usually applies to developers or packagers.

I think it's helpful for these kinds of missing build tool warnings to be called out in a block with newlines the way they are now.

When I build on Debian 7 with a bunch of build dependencies missing, I get a warning summary at the end that looks like this

If at some point we think these kinds of called out warning messages are no longer necessary then we should change them all consistently. But for now I think it's important to keep the makeinfo warnings looking the same as all the rest.

Mike Miller <mtmiller>
Project Administrator
Fri 19 Jan 2018 10:34:56 PM UTC, comment #45:

@Mike: I added AC_CACHE_CHECK, and shortened the warning messages to make them look like some of the other ones in the build process. See the attached sortas3.cset

(file #42979)

Rik <rik5>
Project Administrator
Fri 19 Jan 2018 10:30:05 PM UTC, comment #44:

@Mike: I just put in an AC_CACHE statement too. Let me upload my patch and you can modify it if necessary.

Rik <rik5>
Project Administrator
Fri 19 Jan 2018 10:18:24 PM UTC, comment #43:

The latest works for me with both Texinfo 4.13 (Debian 7) and 5.2 (Ubuntu 14.04), prints the correct warning message and disables building the manual.

I'll add a cache value and push this change soon.

Mike Miller <mtmiller>
Project Administrator
Fri 19 Jan 2018 10:09:01 PM UTC, comment #42:

Apparently I was behind the times by several minutes. I downloaded and tested Mike's newest patch and it also works with 6.1.

Rik <rik5>
Project Administrator
Fri 19 Jan 2018 10:01:59 PM UTC, comment #41:

When this is finalized it should probably also use AC_CACHE_VAL so the test doesn't have to be run every time configure is re-run.

Rik <rik5>
Project Administrator
Fri 19 Jan 2018 09:59:42 PM UTC, comment #40:

Mike's patch works for me, but this is with Texinfo 6.1. I purposefully modified the generated conftest.texi to have @ssortas which is an invalid command and the correct branch is taken and docs are disabled.

Maybe Texinfo 4.13 really doesn't return exit status correctly, in which case we can use the check on the size of conftest.info as a proxy. We will have to wait for Guillaume to run a test.

Rik <rik5>
Project Administrator
Fri 19 Jan 2018 09:57:34 PM UTC, comment #39:

New patch attached. Configure now creates a more complete document example. In Texinfo 4.13, apparently the document has to actually get to the step where it attempts to generate the index before it even attempts to see if @sortas is a known command or macro. I am posting this now, haven't tested yet but I will be testing shortly with Texinfo 4.13, 5.2, and 6.5.

(file #42978)

Mike Miller <mtmiller>
Project Administrator
Fri 19 Jan 2018 09:40:48 PM UTC, comment #38:

I can confirm Guillaume's observation with Texinfo 4.13. With such a simple document, it doesn't warn and it produces an empty info file with no error. I'm now playing with making the document a little more complex to see what the bare minimum is to get it to error.

With Texinfo 5.2, it does error on @sortas with the simple three-line example Dan suggested.

Mike Miller <mtmiller>
Project Administrator
Fri 19 Jan 2018 05:11:02 PM UTC, comment #37:

If the exit status is, for some reason, not being reported correctly then why not just use the existence of the output file?

I'm using texinfo 6.1 and when I run with a file that leads to an error then no output .info file is created. So check for '-e conftest.info'

Rik <rik5>
Project Administrator
Fri 19 Jan 2018 04:45:11 PM UTC, comment #36:

Release notes for all texinfo versions are conveniently listed here:


I see no mention of "exit"/"status" changes somewhere along the way.

Dan Sebald <sebald>
Fri 19 Jan 2018 04:35:05 PM UTC, comment #35:

Could you explore the behavior of makeinfo a bit? I'm wondering if older versions of Texinfo properly handled the exit status of the program. For example, change the contents of the conftest.texi to be

and run (I have Texinfo 6.1)

Then change conftest.texi to

and run

Then change conftest.texi to

and run

Dan Sebald <sebald>
Fri 19 Jan 2018 10:50:41 AM UTC, comment #34:

I applied the batch and am a bit confused because it still tried to compile the documentation (and failed).

Looking at the configure log:

and if I try to run the test manually, I get:

Guillaume <gyom>
Fri 19 Jan 2018 08:10:05 AM UTC, comment #33:

The test looks good. The explanation seems a bit wordy for "computerese"; maybe just "GNU makeinfo version does not support @sortas. Manual will not be compiled."

Also, in configure.ac is this message:

You may want to change "because makeinfo was not found" to "because makeinfo was not found or is out of date".

I will test when I have time to run configure and recompile a couple times in the background.

Dan Sebald <sebald>
Fri 19 Jan 2018 03:24:24 AM UTC, comment #32:

I've written a configure test to put this to rest. I haven't tested it on a system with an older Texinfo yet. If someone wants to test it for me, let me know if it warns correctly.

(file #42972)

Mike Miller <mtmiller>
Project Administrator
Fri 12 Jan 2018 08:52:25 PM UTC, comment #31:

Just to report my last couple findings, I have confirmed that Texinfo 5.2 does produce the correctly sorted output as long as the Gnulib texinfo.tex is present. And I have confirmed that I can install Texinfo 6.5 into /usr/local and everything builds again.

Mike Miller <mtmiller>
Project Administrator
Fri 12 Jan 2018 06:17:39 PM UTC, comment #30:

The code to disable documentation is already present in configure.ac. I've quoted it below:

There is also a macro OCTAVE_PROG_MAKEINFO in m4/acinclude.m4 which checks for the existence of makeinfo and sets the "warn_makeinfo" variable used above. It seems like the OCTAVE_PROG_MAKEINFO macro should be extended to test not only for presence of makeinfo, but also the capability to parse @sortas. There is no need to test for @codequoteundirected because if makeinfo supports @sortas it will definitely support the other one.

Rik <rik5>
Project Administrator
Fri 12 Jan 2018 06:03:50 PM UTC, comment #29:

To emphasize again, texi2dvi and texi2pdf version 5.2 do not error out on the sortas macro. It's only makeinfo 5.2 that errors (building octave.info and octave.html). So there is no error with any kind of validation of the syntax as long as the macro is defined in texinfo.tex for the TeX output formats (DVI and PDF). I have not looked at the rendered output yet because I didn't know what I was looking for.

It makes sense that texinfo.tex is not used for the plain text formats (Info and HTML) because they aren't TeX based. I guess that Texinfo implements its own conversion routines either in C or Perl that handle the sortas macro for the non-TeX formats.

On a system with Texinfo 6.5, I do get the top-level graphics object classes listed first in the "Graphics Properties Index" page for all output formats.

I don't think there's a point to a separate doc distribution, since we already build and include the docs with the source distribution.

I agree that this remaining compatibility issue primarily affects developers and packagers.

Mike Miller <mtmiller>
Project Administrator
Fri 12 Jan 2018 05:13:38 PM UTC, comment #28:

I do not want to give up the @sortas macro. The new Graphics Properties Index relies on it to put the Object Property link at the front of the table which is important in my mind.

I'm not surprised that Texinfo 4.13, written in C, fails to work. But I'm surprised that versions > 5 can't be made to work. They are written in Perl and are under texi2any in /usr/bin with makeinfo being a symlink to that file.

I looked at texi2any and I don't see any mention of TEXINPUTS so it is not using that input variable to find texinfo.tex. But it must find some version of the macro file because sortas doesn't appear in all of /usr/bin, but it does appear in the default location of /usr/share/texmf/tex/texinfo/texinfo.tex.

This still seems like something that could be solved by getting texi2any to find the correct macro file. But if it can't then I think we just warn the user and fail to build the manual. I don't want inconsistency between different users.

For perspective, this is really only a problem for developers and packagers. Everyone else will get a tarball with the pre-built documentation and they aren't going to be messing around with texi files which would trigger a requirement to rebuild.

Secondarily, lots of big packages have a docs-only distribution. Octave could move to that as well if it made things easier. In that case it is quite clear that when you pull octave-4.4.0-doc package you are getting just the documentation for that specific version and there is no expectation that you would build the documentation yourself.

Incidentally, I debugged things and it seems that texi2any verifies the syntax of the texi file before passing it off for conversion. The Perl modules that do this are in /usr/share/texinfo/Texinfo/*.pm. So that is why an error is generated with earlier versions because the Perl code hasn't been updated to include the keyword sortas, even though the macro file itself has.

Rik <rik5>
Project Administrator
Fri 12 Jan 2018 10:51:47 AM UTC, comment #27:

I prefer Mike's option 4, too. It is just a matter of one or two year until all major distros will support more recent versions of Texinfo.

Rather we should convince the distros to update this security irrelevant tool (I did for openSUSE) and we should not waste our time here add too much clutter into our sources no one will understand in a few years. Texinfo is complicated enough. It is just documentation that can be read online. If one wants to build it herself, the rule should be to have at least Texinfo 6 (from 2015) and it is no magic to compile it within a few minutes.

My two pence.

Kai Torben Ohlhus <siko1056>
Project Member
Fri 12 Jan 2018 10:26:42 AM UTC, comment #26:

The reason for the use of @sortas is to clean up an index having to cover words, symbols and whatever else in an organized and uncluttered fashion. Look at a copy of the octave.pdf from before and after all the changes. Older Texinfo versions and release-note history? I just read the Texinfo manual which said @sortas{} does what it does, and hey it worked.

What is wrong with option 1? I don't see it as that important that HTML and PDF indices should match the exact same position (the fact one is single-column, the other two-column is already noticeably different), plus it will self-correct as Linux bundlers update their Texinfo versions.

Dan Sebald <sebald>
Fri 12 Jan 2018 08:34:23 AM UTC, comment #25:

I prefer option 4 to any of your options: Do continue to use Gnulib's texinfo.tex. Add a configure feature test for the sortas macro, and if makeinfo doesn't support it, disable building the manual in all formats with a warning that GNU Texinfo needs to be upgraded to support some newer features. This is basically your option #3, but I see no reason to stop using Gnulib's texinfo.tex, it is still useful.

Honestly I'd also prefer option 5, simply backing out all uses of the sortas macro, but I haven't really been following why it was introduced last week or what purpose it serves. If the people working on improving the user manual think it's important enough to block certain sets of users from being able to build the user manual, I am in no position to argue against it.

Mike Miller <mtmiller>
Project Administrator
Fri 12 Jan 2018 08:06:23 AM UTC, comment #24:

I think I see what you are getting at. Texinfo now appears to be handled via some "universal" program makeinfo which incorporates support for TeX-derivative formats, .info, .html, and whatever else. These apps have names like texi2dvi, etc. However, of note is that the one called texi2html is on its way out (and is bundled in its own Ubuntu/Mint package). The texi2any app has an independent HTML conversion.

What's important for the texi2dvi support is the file texinfo.tex, and gnulib subdirectory has an up-to-date copy of that, so in the Octave environment, texi2dvi is effectively Texinfo 6.1--even though the system makeinfo is older. HTML support doesn't work in such a way, so it's implementation is the makeinfo version.

I'll just summarize options:

1) If there is no @sortas feature support, define @sortas{} as empty/do-nothing. Not desirable, but it builds.

2) Nuance the manual build into TeX versions and non-TeX versions by doing feature-tests on both. Right now, texi2dvi is looking to the local gnuplib texinfo.tex file and should like have the features and the TeX-derivative versions of the manual should be built. The non-TeX versions of the manual have a good chance of not being built because @sortas is introduced in early 2016


3) Don't use the gnulib texinfo.tex file. Instead always use the system true makeinfo version, and if it fails to have the feature @sortas, then no versions of the manual will be built.

I sort of like option #3 over #2, just because it is a simpler implementation I guess.

Dan Sebald <sebald>
Fri 12 Jan 2018 05:21:14 AM UTC, comment #23:

I agree with Rik in https://lists.gnu.org/archive/html/octave-maintainers/2018-01/msg00033.html, I don't think we want different manual output for different versions of Texinfo. I wouldn't want the table of contents or index to look different between the HTML and the PDF versions. So if this sorting feature is very important, then I think we just need to say it requires Texinfo 6.1 and be done with it. I am going to make sure I can install Texinfo 6 locally and build with that.

Mike Miller <mtmiller>
Project Administrator
Fri 12 Jan 2018 04:14:56 AM UTC, comment #22:

Well, there is still the idea of defining @sortas{} to be nothing, under the condition the feature test fails. It appears Texinfo might be able to read environment variables:


So, maybe it's as simple as:


INSIDE interpreter/macros.texi

The consequence is that some of the index entries will appear in unintended locations fit he builders Texinfo is old. But the unintended locations will still be reasonable because it will sort by the entry (instead of a hidden slight-variation on the entry).

Dan Sebald <sebald>
Fri 12 Jan 2018 03:09:35 AM UTC, comment #21:

Ok, I've tested this a little on Ubuntu 14.04 and I can confirm I can't build either the octave.info or octave.html formats of the manual with Texinfo 5.2. I can build octave.dvi, octave.pdf, and octave.ps.

I think the texinfo.tex auxiliary file is only used with the TeX rendered output formats (DVI, PS, and PDF), but Texinfo itself handles the macros to produce the Info and HTML output formats.

The codequoteundirected macro works with Texinfo 5.2, but the sortas macro was only introduced in Texinfo 6.1, and that is the fatal error that I get on Ubuntu 14.04.

I would still like to be able to support building on Ubuntu 14.04, which means Texinfo 5, but I don't see a nice way around this.

Mike Miller <mtmiller>
Project Administrator
Sat 06 Jan 2018 12:20:16 AM UTC, comment #20:

I added a dependency of the documentation on macros.texi (http://hg.savannah.gnu.org/hgweb/octave/rev/c85871d2a10e) so it isn't required to manually delete octave.dvi in order to see the effect of changes in macros.texi.

Rik <rik5>
Project Administrator
Fri 05 Jan 2018 06:40:50 PM UTC, comment #19:

Yeah, I found the same. Adding TEXINPUTS to the html rule might help here. The Automake built-in rule for building html info docs also do not contain TEXINPUTS. Maybe the Automake maintainers think that texinfo.tex is only required for correct appearance of printed output formats (PDF and PS).

Mike Miller <mtmiller>
Project Administrator
Fri 05 Jan 2018 05:17:47 PM UTC, comment #18:

Okay, finally found it. See doc/interpreter/module.mk which is part of the Automake environment. There is this comment in the file.

The rule for pdf is

The rule for html is

The HTML rule does not set the TEXINPUTS variable.

There are two things. We can fix this in the short term by adding in the correct variables from one of the other rules. Secondarily, we should go back and check whether that original comment is still correct and we need to provide all of these build rules ourselves. I'm stopping my own work on this bug as I've got some others to attend to.

Rik <rik5>
Project Administrator
Fri 05 Jan 2018 05:15:32 PM UTC, comment #17:

With make V=1 I get the same thing than you:

I tried copying gnulib/build-aux/texinfo.tex into doc/, doc/interpreter/, .build/doc/, .build/doc/interpreter/, . and .build/ but the outcome was still the same. it would be useful to also have @siko1056's feedback in case I'm doing something wrong as he has the same issue.

Guillaume <gyom>
Fri 05 Jan 2018 05:13:32 PM UTC, comment #16:

Something is clearly busted for HTML. When I run V=1 to produce the dvi file which is a precursor to the PDF file I get

Clearly the Automake process recognizes that this is a Texinfo command and is modifying the TEXINPUTS variable before calling makeinfo.

Rik <rik5>
Project Administrator
Fri 05 Jan 2018 05:03:11 PM UTC, comment #15:

According to Automake documentation

Octave is using AC_CONFIG_AUX_DIR so this should be set up correctly. It might be interesting to see if you can get this to work by copying texinfo.tex into doc/interpreter, doc/, top-level source directory, top-level build directory.

If it works then this is clearly just an issue of finding out where makeinfo is looking for the file and getting the file to be there.

Rik <rik5>
Project Administrator
Fri 05 Jan 2018 04:53:10 PM UTC, comment #14:

I just used V=1 on my own computer and I get

It's possible that makeinfo should be using the --conf-dir option to add in the build-aux directory.

Rik <rik5>
Project Administrator
Fri 05 Jan 2018 04:46:21 PM UTC, comment #13:

Ah, okay. The sortas is still important for HTML so we can't do without that.

Can you run with

so there is a full explanation of the commands you are running?

I notice that with V=0 I get

It is possible that MAKEINFO responds to a different environment variable than TEXI2DVI or TEXI2PDF and that you are not picking up the macros that TEXINFO_TEX is specifying.

Rik <rik5>
Project Administrator
Fri 05 Jan 2018 03:32:30 PM UTC, comment #12:

I applied this change in doc/interpreter/macros.texi and the error about "codequoteundirected" disappeared but, unsurprisingly, the ones about "sortas" are still there.

Guillaume <gyom>
Fri 05 Jan 2018 03:01:45 PM UTC, comment #11:

Since the codequoteundirected is about Tex output, what happens if you wrap the command with

@codequoteundirected on
@end iftex

In that case it won't apply to HTML output or to Info and plaintext output.

Rik <rik5>
Project Administrator
Fri 05 Jan 2018 11:09:56 AM UTC, comment #10:

You are right, I was confused because of the parallel build. A fuller error message is:

Guillaume <gyom>
Fri 05 Jan 2018 10:45:28 AM UTC, comment #9:

Regarding comment #6: The problem is not the LaTeX + PDF build, it is the HTML, that fails.

Kai Torben Ohlhus <siko1056>
Project Member
Fri 05 Jan 2018 10:21:00 AM UTC, comment #8:

I see the same thing :-|

Guillaume <gyom>
Fri 05 Jan 2018 10:15:46 AM UTC, comment #7:

TEXINFO_TEX seems to be the pertinent autoconf variable:


After configuration I'm seeing:

linux build1 # grep TEXINFO_TEX * -s
Makefile:TEXINFO_TEX = $(top_srcdir)/build-aux/texinfo.tex
Makefile:am__TEXINFO_TEX_DIR = $(top_srcdir)/build-aux

What are you seeing?

Dan Sebald <sebald>
Fri 05 Jan 2018 10:01:49 AM UTC, comment #6:

Thanks Mike, I checked and the file is the same as yours (and indeed contains definitions for "codequoteundirected" and "sortas". I reran ./bootstrap and ../configure but same errors still take place.

Guillaume <gyom>
Fri 05 Jan 2018 12:08:03 AM UTC, comment #5:

It shouldn't matter what version of Texinfo is being used, Octave uses its own texinfo.tex file pulled from gnulib, which is periodically synced with Texinfo upstream. This file contains the Texinfo macro definitions.

Guillaume - are you sure you have a correctly bootstrapped source tree? What does "sha256sum ../build-aux/texinfo.tex" show (assuming you've configured with ../configure)?

That file should be a symlink to "../gnulib/build-aux/texinfo.tex". And it should contain definitions for both "codequoteundirected" and "sortas".

Mike Miller <mtmiller>
Project Administrator
Thu 04 Jan 2018 05:29:19 PM UTC, comment #4:

"codequoteundirected" is in texinfo 5.0 from February, 2013. That is nearly 5 years old, the "sortas" command is from February, 2016, so only two years old.

I've put the question to the Octave Maintainer's list about which version of Texinfo we want to program to. This is only an issue for developers. Users, including Linux distributions, get the manual as part of the distribution tarball and don't need Texinfo tools on the computer used to build Octave.

Rik <rik5>
Project Administrator
Thu 04 Jan 2018 10:40:59 AM UTC, comment #3:

Following this changeset, I now get the following errors:

I use texinfo version 4.13 (latest available on openSUSE) and these commands are only available in more recent versions:

Guillaume <gyom>
Thu 04 Jan 2018 06:07:32 AM UTC, comment #2:

This is a great improvement. I've run in to this a couple of times, but was never bothered enough to find a good solution. It's super that it is just a one-liner. I pushed it on the development branch here (http://hg.savannah.gnu.org/hgweb/octave/rev/9d0522881498).

Rik <rik5>
Project Administrator
Mon 01 Jan 2018 10:02:14 PM UTC, comment #1:

I fretted over how to control TeX inside @code{} via some setting or package. Then I figured there must be some means of doing such a thing in Texinfo (I'm unfamiliar with it). I then found the answer in the Texinfo manual, Section 12.2 Inserting Quote Characters. The attached patch is an easy fix.

Chapter 9 Evaluation of the Octave manual has an example of single quotes use in code. Try doing cut-and-paste on that example via xviewer before and after the changeset. **NOTE** Be sure to do

rm doc/interpreter/octave.dvi

from the top build directory because it appears the make rules have no dependence on the file doc/interpreter/macros.texi.

(file #42785)

Dan Sebald <sebald>
Mon 01 Jan 2018 04:12:54 AM UTC, original submission:

Most of the code examples in the octave.pdf PDF user manual use double quotes for strings. These copy just fine into octave command line when selected in xviewer. However, there are some entries that use single quotes instead. I know that LaTeX will use a backward apostrophe by default. It would be better to make LaTeX use the "forward" or "closing" apostrophe within the @code{} entries so that the reader can copy the examples directly to the Octave command line.

Dan Sebald <sebald>


(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:

Attached Files
file #42979:  sortas3.cset added by rik5 (4KiB - application/octet-stream)
file #42978:  config-makeinfo-sortas-v2.patch added by mtmiller (2KiB - application/octet-stream)
file #42972:  config-makeinfo-sortas.patch added by mtmiller (2KiB - application/octet-stream)


Depends on the following items: None found

Items that depend on this one: None found


Carbon-Copy List
  • -email is unavailable- added by mtmiller (Posted a comment)
  • -email is unavailable- added by gyom (Posted a comment)
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by siko1056 (Updated the item)
  • -email is unavailable- added by sebald (Submitted the item)

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only project members can vote.




    Follow 11 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2018-01-19 mtmiller StatusIn Progress => Fixed
        Open/ClosedOpen => Closed
    2018-01-19 rik5 Attached File- => Added sortas3.cset, #42979
    2018-01-19 mtmiller Attached File- => Added config-makeinfo-sortas-v2.patch, #42978
    2018-01-19 mtmiller Attached File- => Added config-makeinfo-sortas.patch, #42972
    2018-01-05 rik5 StatusFixed => In Progress
        Open/ClosedClosed => Open
    2018-01-04 rik5 StatusPatch Submitted => Fixed
        Open/ClosedOpen => Closed
    2018-01-03 siko1056 StatusNone => Patch Submitted
    2018-01-01 sebald Attached File- => Added octave-apostrophe_texinfo_cut_and_paste-djs2018jan01.patch, #42785

    Back to the top

    Powered by Savane 3.4