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

 
 

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

Submitter:  Dan Sebald <sebald>
Submitted:  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
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

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

https://hg.savannah.gnu.org/hgweb/octave/rev/f39ae754a7d8

Mike Miller <mtmiller>
Group Member
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


configure: WARNING: SUNDIALS NVECTOR serial library not found.  Solvers ode15i and ode15s will be disabled.


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

Rik <rik5>
Group 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


configure: WARNING:

I wasn't able to find a suitable style for declaring the api prefix
in a bison input file so I'm disabling bison.

configure: WARNING:

I wasn't able to find a suitable style for declaring a push-pull
parser in a bison input file so I'm disabling bison.

configure: WARNING:

I didn't find bison, or the version of bison that I found does not
support all the features that are required, but it's only a problem
if you need to reconstruct parse.cc, which is the case if you're
building from VCS sources.

configure: WARNING:

I wasn't able to find a version of GNU makeinfo that supports the @sortas
command, but it's only a problem if you need to build the manual, which is the
case if you're building from VCS sources.

configure: WARNING:

I didn't find icotool, but it's only a problem if you need to
reconstruct octave-logo.ico, which is the case if you're building from
VCS sources.

configure: WARNING:

I didn't find rsvg-convert, but it's only a problem if you need to
reconstruct octave-logo-*.png, which is the case if you're building
from VCS sources.

configure: WARNING: sndfile library not found.  The audioinfo, audioread, and audiowrite functions will be disabled.
configure: WARNING: PortAudio library not found.  The audioplayer, audiorecorder, and audiodevinfo functions will be disabled.
configure: WARNING: Xft library not found.  OpenGL graphics will not be fully functional.
configure: WARNING: OSMesa library not found.  Offscreen rendering with OpenGL will be disabled.
configure: WARNING: Qt libraries not found; disabling Qt GUI
configure: WARNING: AMD library not found.  This will result in some lack of functionality for sparse matrices.
configure: WARNING: CAMD library not found.  This will result in some lack of functionality for sparse matrices.
configure: WARNING: COLAMD library not found.  This will result in some lack of functionality for sparse matrices.
configure: WARNING: CCOLAMD library not found.  This will result in some lack of functionality for sparse matrices.
configure: WARNING: CHOLMOD library not found.  This will result in some lack of functionality for sparse matrices.
configure: WARNING: CXSparse library not found.  This will result in some lack of functionality for sparse matrices.
configure: WARNING: UMFPACK not found.  This will result in some lack of functionality for sparse matrices.
configure: WARNING: KLU library not found.  This will result in some lack of functionality for sparse matrices
configure: WARNING: SUNDIALS NVECTOR serial library not found.  Solvers ode15i and ode15s will be disabled.
configure: WARNING: SUNDIALS IDA library not found.  Solvers ode15i and ode15s will be disabled.
configure: WARNING: JAVA_HOME environment variable not initialized.  Auto-detection will proceed but is unreliable.
configure: WARNING: No Java executable found.  Octave will not be able to call Java methods.
configure: WARNING: building documentation disabled because makeinfo was not found; make dist will fail
configure:
configure: NOTE: Libraries or auxiliary programs may be skipped if they are
configure: NOTE: not found OR if they are missing required features on your
configure: NOTE: system.


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>
Group Member
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>
Group 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>
Group 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>
Group Member
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>
Group 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>
Group 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>
Group 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>
Group Member
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>
Group Member
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>
Group administrator
Fri 19 Jan 2018 04:45:11 PM UTC, comment #36: 

Release notes for all texinfo versions are conveniently listed here:

http://svn.savannah.gnu.org/viewvc/*checkout*/texinfo/trunk/NEWS

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


\input texinfo
@cindex foo
@bye


and run (I have Texinfo 6.1)


linux@ ~/octave/bug/52775 $ makeinfo --no-warn conftest.texi
linux@ ~/octave/bug/52775 $ echo $?
0


Then change conftest.texi to


\input texinfo
@cindex @sortas{a} foo
@bye


and run


sebald@moorglade ~/octave/bug/52775 $ makeinfo --no-warn conftest.texi
sebald@moorglade ~/octave/bug/52775 $ echo $?
0


Then change conftest.texi to


\input texinfo
@cindex @sssortas{a} foo
@bye


and run


linux@ ~/octave/bug/52775 $ makeinfo --no-warn conftest.texi
conftest.texi:2: unknown command `sssortas'
conftest.texi:2: misplaced {
conftest.texi:2: misplaced }
linux@ ~/octave/bug/52775 $ echo $?
1


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:


configure:9110: checking for makeinfo support for @sortas command
configure:9121: result: yes


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


octave> makeinfo --version
makeinfo (GNU texinfo) 4.13
octave> cat conftest.texi
\input texinfo
@cindex @sortas{a} foo
@bye
octave> makeinfo --no-warn conftest.texi
octave> cat conftest.info
octave>


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:


  if test -n "$warn_makeinfo"; then
    ENABLE_DOCS=no
    warn_docs_makeinfo="building documentation disabled because makeinfo was not found; make dist will fail"
    OCTAVE_CONFIGURE_WARNING([warn_docs_makeinfo])
  fi


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>
Group Member
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>
Group Member
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:


### Need to disable building documentation if either gnuplot or
### makeinfo are missing.  Skip these warnings if building docs was
### intentionally disabled with a configure option.

ENABLE_DOCS=yes
AC_ARG_ENABLE([docs],
  [AS_HELP_STRING([--disable-docs], [don't build documentation files])],
  [if test "$enableval" = no; then
     ENABLE_DOCS=no
     warn_docs="building documentation disabled; make dist will fail"
     OCTAVE_CONFIGURE_WARNING([warn_docs])
   fi], [])
if test $ENABLE_DOCS = yes; then
  if test $opengl_graphics = no || test -n "$warn_OSMesa"; then
    if test -n "$warn_gnuplot"; then
      ENABLE_DOCS=no
      warn_docs_graphics="building documentation disabled because no suitable graphics toolkit is available; make dist will fail"
        OCTAVE_CONFIGURE_WARNING([warn_docs_graphics])
    fi
  fi
  if test -n "$warn_makeinfo"; then
    ENABLE_DOCS=no
    warn_docs_makeinfo="building documentation disabled because makeinfo was not found; make dist will fail"
    OCTAVE_CONFIGURE_WARNING([warn_docs_makeinfo])
  fi
fi
if test $ENABLE_DOCS = yes; then
  AC_DEFINE(ENABLE_DOCS, 1,
    [Define to 1 to build Octave documentation files.])
fi
AM_CONDITIONAL([AMCOND_BUILD_DOCS], [test $ENABLE_DOCS = yes])


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>
Group 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>
Group Member
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>
Group 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>
Group 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>
Group Member
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

https://lwn.net/Articles/675087/

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>
Group Member
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:

https://ftp.gnu.org/old-gnu/Manuals/texinfo-4.2/html_node/env.html#env

So, maybe it's as simple as:

CONFIGURE FEATURE TEST

linux@ ~/octave $ (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.
(set TEXINFO_MISSING_SORTAS in the usual way)


INSIDE interpreter/macros.texi

@if @env{TEXINFO_MISSING_SORTAS}
@macro sortas{param1}
@end macro
@end


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>
Group Member
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>
Group 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>
Group Member
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.


## As of version 1.14.1, automake does not seem to generate
## rules for DVI, PDF, or HTML output that work for us when
## there are additional dependencies, so we include our own
## versions of the rules here.


The rule for pdf is


%reldir%/octave.pdf: %reldir%/octave.texi $(srcdir)/%reldir%/version-octave.texi | %reldir%/$(am__dirstamp)
        $(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
        MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I doc/interpreter -I $(abs_top_srcdir)/doc/interpreter' \
        $(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \
        `test -f '%reldir%/octave.texi' || echo '$(abs_top_srcdir)/'`%reldir%/octave.texi


The rule for html is


$(OCTAVE_HTML_STAMP): %reldir%/octave.texi $(srcdir)/%reldir%/version-octave.texi | %reldir%/$(am__dirstamp)
        $(AM_V_MAKEINFO)rm -rf $(OCTAVE_HTML_DIR)
        $(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) \
         -I doc/interpreter -I $(abs_top_srcdir)/doc/interpreter \
         --css-ref=octave.css \
         -o $(OCTAVE_HTML_TMP_DIR) `test -f '%reldir%/octave.texi' || echo '$(abs_top_srcdir)/'`%reldir%/octave.texi; \
        then \
          rm -rf $(OCTAVE_HTML_DIR) && \
          mv $(OCTAVE_HTML_TMP_DIR) $(OCTAVE_HTML_DIR) && \
          touch $@; \
        else \
          rm -rf $(OCTAVE_HTML_TMP_DIR); exit 1; \
        fi


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>
Group administrator
Fri 05 Jan 2018 05:15:32 PM UTC, comment #17: 

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


rm -rf doc/interpreter/octave.html
if /bin/sh /opt/octave/build-aux/missing makeinfo --html   \
 -I doc/interpreter -I /opt/octave/.build/../doc/interpreter \
 --css-ref=octave.css \
 -o doc/interpreter/octave.htp `test -f 'doc/interpreter/octave.texi' || echo '/opt/octave/.build/../'`doc/interpreter/octave.texi; \
then \
  rm -rf doc/interpreter/octave.html && \
  mv doc/interpreter/octave.htp doc/interpreter/octave.html && \
  touch doc/interpreter/octave.html/.octave-html-stamp; \
else \
  rm -rf doc/interpreter/octave.htp; exit 1; \
fi
doc/interpreter/expr.texi:111: Unknown command `sortas'.


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


TEXINPUTS="./build-aux:$TEXINPUTS" \
MAKEINFO='/bin/bash /home/rik/wip/Projects_Mine/octave-dev/build-aux/missing makeinfo   -I doc/interpreter -I ./doc/interpreter' \
texi2dvi  --build-dir=doc/interpreter/octave.t2d -o doc/interpreter/octave.dvi  \
`test -f 'doc/interpreter/octave.texi' || echo '/home/rik/wip/Projects_Mine/octave-dev/'`doc/interpreter/octave.texi


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

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

According to Automake documentation


By default, Automake requires the file texinfo.tex to appear in the same directory as the Makefile.am file that lists the .texi files. If you used AC_CONFIG_AUX_DIR in configure.ac (see Finding ‘configure’ Input in The Autoconf Manual), then texinfo.tex is looked for there. In both cases, automake then supplies texinfo.tex if --add-missing is given, and takes care of its distribution. However, if you set the TEXINFO_TEX variable (see below), it overrides the location of the file and turns off its installation into the source as well as its distribution.


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>
Group administrator
Fri 05 Jan 2018 04:53:10 PM UTC, comment #14: 

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


rm -rf doc/interpreter/octave.html
if /bin/bash /home/rik/wip/Projects_Mine/octave-dev/build-aux/missing makeinfo --html   \
 -I doc/interpreter -I /home/rik/wip/Projects_Mine/octave-dev/doc/interpreter \
 --css-ref=octave.css \
 -o doc/interpreter/octave.htp `test -f 'doc/interpreter/octave.texi' || echo '/home/rik/wip/Projects_Mine/octave-dev/'`doc/interpreter/octave.texi; \
then \
  rm -rf doc/interpreter/octave.html && \
  mv doc/interpreter/octave.htp doc/interpreter/octave.html && \
  touch doc/interpreter/octave.html/.octave-html-stamp; \
else \
  rm -rf doc/interpreter/octave.htp; exit 1; \
fi


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


      --conf-dir=DIR
              search also for initialization files in DIR.




Rik <rik5>
Group 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


make -j1 V=1


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

I notice that with V=0 I get


  MAKEINFO doc/interpreter/octave.info
  TEXI2DVI doc/interpreter/octave.dvi
  MAKEINFO doc/interpreter/octave.html/.octave-html-stamp
  DVIPS    doc/interpreter/octave.ps
  TEXI2PDF doc/interpreter/octave.pdf


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>
Group 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

@iftex
@codequoteundirected on
@end iftex

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

Rik <rik5>
Group 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:


  MAKEINFO doc/interpreter/octave.html/.octave-html-stamp
/opt/octave/.build/../doc/interpreter//macros.texi:112: Unknown command `codequoteundirected'.
doc/interpreter/expr.texi:111: Unknown command `sortas'.
doc/interpreter/expr.texi:111: Misplaced {.
doc/interpreter/expr.texi:111: Misplaced }.
Too many errors!  Gave up.
Makefile:28030: recipe for target 'doc/interpreter/octave.html/.octave-html-stamp' failed


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>
Group 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:

https://ftp.gnu.org/old-gnu/Manuals/automake-1.7.2/html_node/automake_81.html

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)?


$ sha256sum ../build-aux/texinfo.tex
370e9b54159b6dfada33ffc522f41ab0ee0ac887fe779aba5911616f1b31ac84  ../build-aux/texinfo.tex


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>
Group Member
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>
Group administrator
Thu 04 Jan 2018 10:40:59 AM UTC, comment #3: 

Following this changeset, I now get the following errors:


doc/interpreter//macros.texi:112: Unknown command `codequoteundirected'.
doc/interpreter/expr.texi:111: Unknown command `sortas'.


I use texinfo version 4.13 (latest available on openSUSE) and these commands are only available in more recent versions:
http://svn.savannah.gnu.org/viewvc/*checkout*/texinfo/trunk/ChangeLog

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>
Group 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:
   
   
Comment:
   

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)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group 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.13-4448.
    Corresponding source code