[Octave-bug-tracker] [bug #35187] the "help" command displays truncated help (words missing, etc)

[Mark Messer]

Follow-up Comment #9, bug #35187 (project octave):

Here is a summary of what I know about the cause of garbled help. Some of it
duplicates what a dawid found. I have saved input and output in files. 

'help inv' causes Octave to call <Octave home>shareoctave3.4.3mhelphelp.m. 

help.m calls get_help_text('inv'), which extracts help text containing TexInfo
markup from <Octave home>liboctave3.4.3octi686-pc-mingw32inv.oct. This is a
binary file. But if you display inv.oct in Notepad++, you can see the text
starting on "line" 431. The text is extracted cleanly. 

help.m calls __makeinfo__(), passing in the text and the output format "plain
text". 

<Octave home>shareoctave3.4.3mhelp__makeinfo__.m. expands some macros in the
text, if needed (@SeeAlso in this case). Then it adds a line containing 'input
texinfo' to the beginning of the text, and '@bye' to the end. It writes the
text to a temporary file. The temporary file is not garbled. I have saved a
copy as octave-help-swldx7.

__makeinfo__.m then constructs a shell command to transliterate the markup to
the desired output format. makeinfo_program() returns the name of the program
to do the transliteration. By default, this is makeinfo, found in the <Octave
home>msys folder. __makeinfo__.m adds options to the shell command for either
plain text or html output. Because this case is plain text, the command is 
    makeinfo --no-headers --no-warn --force --no-validate
C:UsersMMesserAppDataLocalTempoctave-help-swldx7
The command is stored in the cmd variable. 

__makeinfo__.m executes the following Octave command, so that Octave will
delegate execution of makeinfo to the shell. 
    [status, retval] = system (cmd);
The output of makeinfo is garbled. 

help.m gets the output from _makeinfo__.m and adds a few paragraphs at the
beginning and end. This is displayed. I copied the output from help inv from
the Octave window and stored it in HelpInvOutputFor-swldx7.txt.

---
Unlike a dawid, I found that makeinfo produces the same garbled output when I
type one of these lines at the Octave prompt, 
    octave:2> help inv 
        octave:3> [status, retval] = system('makeinfo --no-headers --no-warn 
--force
--no-validate C:UsersMMesserAppDataLocalTempoctave-help-swldx7')
or this at the DOS prompt
    makeinfo --no-headers --no-warn --force --no-validate
C:UsersMMesserAppDataLocalTempoctave-help-swldx7


---
The issue appears to be caused by a bug in makeinfo.exe. Word wrap is not
handled correctly. 

Typing 'makeinfo --help' at the DOS prompt displays options, including this. 
    Options for Info and plain text:
          ...
          --fill-column=NUM       break Info lines at NUM characters (default
72).
This option is not available for html output. 

The marked up text is already wrapped at column 72, so word wrap is not
needed. But there is no way to disable it. makeinfo indents each line. If this
makes the line too long, the last word is wrapped. When this is done,
sometimes the last word is lost. Other times it prints at the beginning of the
same line, which implies a CR was inserted. The next line is not indented,
possibly because makeinfo does not recognize the beginning of a new line. 

Adding --fill-column=76 to line 164 of __markinfo__.m reduces word wrapping,
and reduces the amount of garbling. Setting --fill-column to 200 or 0 makes
problems worse. 

Adding --html to line 164 prevents word wrapping. The html output is correct.



--- 
Linux uses LF line endings. In Windows, CRLF is common. 

The marked up help text in inv.oct ends each line with LF. __makeinfo__ adds
lines ending with LF. 

I am not sure if CR matters. I thought garbling was reduced by adding this
line to __makeinfo__.m immediately before writing the temporary file. 
  text = strrep (text, "n", "rn")
But this could be just from changing the length of lines. And I have some
inconsistent results that I need to figure out before I could draw
conclusions. 


---
makeinfo is part of GNU texinfo. makeinfo appears to be fragile and buggy.
There are comments scattered through the code mentioning a need to work around
problems by adding a blank line at the end of a text block, or removing spaces
at the beginning of each line. 

I have not found such a work around for this. 

I did not see a word wrap bug mentioned in the texinfo project bug list.
Perhaps we should add it. 

'makeinfo --version' reports 
    makeinfo (GNU texinfo) 4.13

    Copyright (C) 2008 Free Software Foundation, Inc.
This is the latest version. 



(file #24858, file #24859)
    _______________________________________________________

Additional Item Attachment:

File name: octave-help-swldx7             Size:0 KB
File name: HelpInvOutputFor-swldx7.txt    Size:1 KB


    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?35187>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/