bugGNU Octave - Bugs: bug #56929, csvread help text xref to dlmread...

 
 

bug #56929: csvread help text xref to dlmread appears confusingly when displayed in info format

Submitted by:  Nicholas Jankowski <nrjank>
Submitted on:  Sat 21 Sep 2019 02:20:23 PM UTC  
 
Category:  Documentation Severity:  1 - Wish
Priority:  3 - Low Item Group:  Documentation
Status:  Confirmed Assigned to:  None
Originator Name:  Nicholas Jankowskk Open/Closed:  Open
Release:  5.1.0 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)

Tue 24 Sep 2019 05:37:45 PM UTC, comment #9: 

The attached patch seems to do the job in most situations.

(file #47567)

Pantxo Diribarne <pantxo>
Project Member
Tue 24 Sep 2019 04:18:26 PM UTC, comment #8: 

@Rik: Thanks. I tested your patch and, as is, it doesn't do well with 3 arguments calls. See e.g. "help line" which displays

octave:1> help line
...
Programming Note: The full list of properties is documented at
see Line Properties Line Properties.
...

The problem with this approach is that it is impossible to distinguish @ref, @xref and @pxref (and decide to add "See", "see" or nothing).

On the other hand, I've had no luck trying to define new macros @oref, @oxref and @opxref to distinguish plaintext and other outputs. So far I've tried this:

diff -r 251056aeba5d doc/interpreter/macros.texi
--- a/doc/interpreter/macros.texi        Mon Sep 23 13:51:17 2019 -0700
+++ b/doc/interpreter/macros.texi        Tue Sep 24 18:12:28 2019 +0200
@@ -84,6 +84,42 @@
@end macro
@end ifnotinfo

+@c The following macros o*ref redefine the corresponding *ref macros to avoid
+@c info-like references ("Note ...") in static help strings.
+
+@ifnotplaintext
+@macro oref{arg1, arg2, arg3, arg4, arg5}
+@ref{\arg1\, \arg2\, \arg3\, \arg4\, \arg5\}
+@end macro
+@end ifnotplaintext
+
+@ifplaintext
+@macro oref{arg1, arg2, arg3, arg4, arg5}
+\arg3\
+@end macro
+@end ifplaintext
+
+@ifnotplaintext
+@macro oxref{arg1, arg2, arg3, arg4, arg5}
+@xref{\arg1\, \arg2\, \arg3\, \arg4\, \arg5\}
+@end macro
+@end ifnotplaintext
+
+@ifplaintext
+@macro oxref{arg1, arg2, arg3, arg4, arg5}
+See \arg3\
+@end macro
+@end ifplaintext
+
+@macro opxref{arg1, arg2, arg3, arg4, arg5}
+@ifnotplaintext
+@pxref{\arg1\, \arg2\, \arg3\, \arg4\, \arg5\}
+@end ifnotplaintext
+@ifplaintext
+see \arg3\
+@end ifplaintext
+@end macro
+
@c FIXME: someday, when Texinfo 5.X is standard, we might replace this with
@c @backslashchar, which is a new addition to Texinfo.

diff -r 251056aeba5d scripts/help/__makeinfo__.m
--- a/scripts/help/__makeinfo__.m        Mon Sep 23 13:51:17 2019 -0700
+++ b/scripts/help/__makeinfo__.m        Tue Sep 24 18:12:28 2019 +0200
@@ -128,7 +128,7 @@
     ## Take action depending on output type
     switch (lower (output_type))
       case "plain text"
-        cmd = sprintf ('%s --no-headers --no-warn --force --no-validate --output=- "%s"',
+        cmd = sprintf ('%s --no-headers --no-warn --force --no-validate --plaintext --output=- "%s"',
                        makeinfo_program (), name);
       case "html"
         cmd = sprintf ('%s --no-headers --html --no-warn --no-validate --force --output=- "%s"',
diff -r 251056aeba5d scripts/io/csvread.m
--- a/scripts/io/csvread.m        Mon Sep 23 13:51:17 2019 -0700
+++ b/scripts/io/csvread.m        Tue Sep 24 18:12:28 2019 +0200
@@ -31,7 +31,7 @@
## @end example
##
## Any optional arguments are passed directly to @code{dlmread}
-## (@pxref{XREFdlmread,,dlmread}).
+## (@opxref{XREFdlmread,,dlmread}).
## @seealso{dlmread, textscan, csvwrite, dlmwrite}
## @end deftypefn

This works for "help csvread" but fails for some mysterious reason (and mystery is even documented in texinfo's documentation, https://www.gnu.org/software/texinfo/manual/texinfo-html/Macro-Details.html) when compiling and trying to generate html and pdf output...

Pantxo Diribarne <pantxo>
Project Member
Mon 23 Sep 2019 05:12:04 PM UTC, comment #7: 

@Pantxo: If we want to have 'help' produce plaintext output we could modify scripts/help/__makeinfo__.m.  The current script produces Info output when "plain text" is requested, and then cleans it up with a few regular expressions.  See the code starting at line 128.

    ## Take action depending on output type
    switch (lower (output_type))
      case "plain text"
        cmd = sprintf ('%s --no-headers --no-warn --force --no-validate --output=- "%s"',
                       makeinfo_program (), name);

If you add "--plaintext" to the invocation of mkinfo then it will the @ifplaintext macros will work.

Alternatively, we could add another two regular expressions to clean up the results of the expansion of @pxref and @xref.  See the attached rough patch which does that.

(file #47563)

Rik <rik5>
Project Administrator
Mon 23 Sep 2019 02:21:15 PM UTC, comment #6: 

To illustrate my previous post, it would be handy if the following source string lead to "Plain text doc." from the "help" function, and "Info doc." when read using the "doc" function in cli (thus using the info program).

## -*- texinfo -*-
## @deftypefn {} {@var{retval} =} toto (@var{input1}, @var{input2})
## @ifinfo
## Info doc.
## @end ifinfo
## @ifplaintext
## Plain text doc.
## @end ifplaintext
## @end deftypefn

Then some environment specific macro could be written to avoid cluttering static help strings with unusable links.

Pantxo Diribarne <pantxo>
Project Member
Mon 23 Sep 2019 07:38:54 AM UTC, comment #5: 

@Rik: I played with this in the past. My recollection is that the doc strings prepared for the "help" function were processed for "texinfo" output, so there was no way to write macros that would distinguish static output (for "help") and dynamic one (.info files). If they were processed for "plaintext" output, we could do things in macro.texi, using e.g. "@ifplaintext … @end ifplaintext". Am I missing something?
The @seealso macro seems to hide some non-textinfo magic: it is capable of producing different outputs for help doc stings and .info files.

Pantxo Diribarne <pantxo>
Project Member
Mon 23 Sep 2019 03:17:52 AM UTC, comment #4: 

ok. I guess I see what you're saying. From a documentation/readability standpoint, though, it seems pretty poor as standard form. XREFdlmread isn't exactly anything someone can act on or follow, or something anyone unfamiliar with texinfo would have any expectation of deriving meaning.

Eg., clear enough in the html/pdf:  "Any optional arguments are passed directly to dlmread (see dlmread)." (with the latter a clickable link)

non-clickable, text only version says " (*note dlmread: XREFdlmread.) " seems fairly non-intuitive to someone just reading the helptext.

not sure what you mean by cursor over it and hit return. i assume you don't mean in the octave interpreter?

if that's the standard, i guess it should be left as is.

Nicholas Jankowski <nrjank>
Sun 22 Sep 2019 10:10:41 PM UTC, comment #3: 

This is just the way the @xref, @pxref macros in Texinfo behave.  In formats like PDF and HTML, Texinfo creates a link and writes "see LINK_TEXT".  The underlying link location is not displayed.

In info format, you get what you have seen.  First, bold format is replaced in plain text by

*note:

And then texinfo lists the link text (dlmread) and the link itself (XREFdlmread).  The link works as expected.  If you cursor over it and then hit <RETURN> the info program will take you to the documentation for dlmread.

If this is really bothersome, you could write a texinfo macro which does something different.  The file doc/interpreter/macros.texi contains an example for the @seealso macro.  

Rik <rik5>
Project Administrator
Sun 22 Sep 2019 08:17:59 PM UTC, comment #2: 

It's not really a parse error, this is exactly the way Texinfo is supposed to be formatted in its normal text output behavior. If we want to add some extra preprocessing to format these links another way when the doc strings are shown in the Octave interpreter, we can do that. But this is more of a feature request than a problem.

Here is an example from the info user manual itself in the (text based) info browser:

   Texinfo itself (*note (texinfo)Top::) is a documentation system that
uses a single source file to produce both on-line information and
printed output.  You can typeset and print the files that you read in
Info.

This is how cross-references are normally rendered in the text interface.

All that is to say, it's definitely reasonable to add a feature to preprocess the doc string snippets and delete cross-references, since there is nowhere for them to link.

Mike Miller <mtmiller>
Project Administrator
Sat 21 Sep 2019 07:15:59 PM UTC, comment #1: 

Confirmed in csvread but also in all function documentation that provide internal links (e.g. text, image,...).

Maybe the seealso macro could be extended to handle links to parts of the manual, not only functions?

Pantxo Diribarne <pantxo>
Project Member
Sat 21 Sep 2019 02:20:23 PM UTC, original submission:  

In the csvread documentation I see

“Any optional arguments are passed directly to dlmread (see dlmread).”

Where the second dlmread is a link

Typing help csvread, that renders as:

“Any optional arguments are passed directly to ‘dlmread’ (*note dlmread: XREFdlmread.).”

The code in the docstring is:

Any optional arguments are passed directly to @code{dlmread} (@pxref{XREFdlmread,,dlmread}).”

My texinfo skills are weak, so I’m not sure what that’s supposed to look like, and why it parses right for the doc and html but not for the help display

Nicholas Jankowski <nrjank>

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #47567:  56929b.patch added by pantxo (2KiB - text/x-patch)
file #47563:  56929.patch added by rik5 (1KiB - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by pantxo (Posted a comment)
  • -email is unavailable- added by nrjank (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
    2019-09-24 pantxo Attached File- => Added 56929b.patch, #47567
    2019-09-23 rik5 Attached File- => Added 56929.patch, #47563
    2019-09-22 rik5 Severity3 - Normal => 1 - Wish
    2019-09-22 rik5 Severity1 - Wish => 3 - Normal
        Item GroupFeature Request => Documentation
        SummaryCsvread help text xref to dlmread doesn’t parse right => csvread help text xref to dlmread appears confusingly when displayed in info format
    2019-09-22 mtmiller Severity3 - Normal => 1 - Wish
        Priority5 - Normal => 3 - Low
        Item GroupDocumentation => Feature Request
    2019-09-21 pantxo StatusNone => Confirmed
        Operating SystemMicrosoft Windows => Any

    Back to the top


    Powered by Savane 3.5