[Octave-bug-tracker] [bug #62417] 'format' errors on names with spaces when calling with function form

[John W. Eaton]

Follow-up Comment #23, bug #62417 (project octave):

Reposting my previous comment because of a botched verbatim tag...

I understand that the quoting caused confusion, but I think this is really a
problem due to a mixture of bad Texinfo markup in the source file.  In the
docstring for the format command in pr-output.cc, we have four tables.  Three
use "@table @code" like this:


@table @code
@item short
...
@item long
...
@item  short e
@itemx long e
...
@end table


which results in the items being typeset in typewriter font in PDF and similar
output formats and surrounding in single quote characters in the Info and the
output displayed by the command-line help function.

The other table uses "@table @asis" with the @item entries sometimes tagged
with @qcode{}, like this:


@table @asis
@item  @qcode{"+"}
@itemx @qcode{"+"} @qcode{"@var{chars}"}
@itemx @code{plus}
@itemx @code{plus @var{chars}}
...
@item bank
...
@item native-hex
...
@end table


To further confuse things, we also have


@item  short eng
@itemx long eng
Identical to @samp{short e} or @samp{long e} but displays the value using an
engineering format, where the exponent is divisible by 3.  For example, with
the @samp{short eng} format, @code{10 * pi} is displayed as
@code{31.416e+00}.


By using @samp, you get a typewriter font surrounded by quotation marks in
typeset output and text enclosed in single quote characters in ASCII output. 
The use of @samp might just be wrong.  I don't remember the guidelines about
what tags to use for what purpose.

Part of the problem is that in the Info format and what is displayed by the
help function the convention is to use single quotes to display @code elements
because simple ASCII output doesn't have a typewriter font.

I'm not sure what is best.  Maybe the guidelines for Texinfo formatting are
not being followed correctly or they are just outdated.  The quotes in simple
ASCII output were probably fine in 1990 but easily misinterpreted today. 
Maybe we should try to improve the help function so that it displays nicely
typeset output when possible?  That might avoid confusion in about 99% of all
use cases in these modern times.


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?62417>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/