bugGNU Octave - Bugs: bug #57845, doc: remove redundant @ref, @xref,...

 
 

bug #57845: doc: remove redundant @ref, @xref, and @pxref arguments

Submitter:  Nicholas Jankowski <nrjank>
Submitted:  Tue 18 Feb 2020 02:21:58 AM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Nicholas Jankowski Open/Closed:  * Closed
Release:  * 6.0.90 Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Tue 18 Feb 2020 09:27:43 PM UTC, comment #5: 

Looks good to me, thanks!

Mike Miller <mtmiller>
Group Member
Tue 18 Feb 2020 04:18:27 PM UTC, comment #4: 

I added a release number (6.0.90) for the first release candidate for 6.1.0 and have tagged this bug with that Release.

This seems to be a simple fix.  I used this Perl substitution


s/(\@[px]*ref)\{([^,]+),,\2/$1\{$2/g


There weren't very many instances.  See changeset https://hg.savannah.gnu.org/hgweb/octave/rev/05c1217d0dae.

Marking as fixed and closing report.

Rik <rik5>
Group administrator
Tue 18 Feb 2020 07:15:56 AM UTC, comment #3: 

I think we should drop those third arguments when the label is the same as the name of the reference to link to, because it does make the output look better in the Info manual.

Compare this one-argument @ref link from the docstring for 'max'



For two inputs (X and Y), return the pairwise maximum according to
the rules for *note Broadcasting::.


with this three-argument @ref link from the docstring for 'text'



Programming Notes: The full list of properties is documented at
*note Text Properties: Text Properties.


The first is much clearer, the second demonstrates the redundancy that Nick mentions in this bug report, only present because of using the three-argument @ref syntax.

Both of these look fine in the plain text output that is post-processed by the '__makeinfo__' function, I'm quoting from the Info format of the user manual.

Mike Miller <mtmiller>
Group Member
Tue 18 Feb 2020 04:32:40 AM UTC, comment #2: 

I think the reason may have been consistency.  The first argument to @ref is the name of the node to link to (equivalent to the link field in HTML), while the third argument, if present, is the text to display instead of the node name.

For a cross-reference to a function such as "ls" the node name is "XREFls", but that looks bad when displayed as "See: XREFls" so the longer form


@ref(XREFls,,ls)


is used.  If the node name and the text are the same one isn't required to use the longer form.  However, it may have made the regexp easier if the references were always consistent.  See https://savannah.gnu.org/bugs/?56929 where I used regexp to make the appearance of links in plaintext look better.

Rik <rik5>
Group administrator
Tue 18 Feb 2020 02:59:41 AM UTC, comment #1: 

I used the following extended regex (with grep -E or git grep -E)


@\w*ref\{[^X].*,\s*,.*\}


as a starting point to find such cross-references. However, even some of those should probably stay the way they are.

In the end, it only looks to me like you're talking about the cross-references that were added in https://hg.savannah.gnu.org/hgweb/octave/rev/a7b6502b5cb5 to fix bug #52816.

Rik - is there a reason you opted for the three-argument form for these cross-references?

Mike Miller <mtmiller>
Group Member
Tue 18 Feb 2020 02:21:58 AM UTC, original submission:  

Low priority task: 

As discussed in bug #50247 and a mailing list discussion [1], it may be preferred to switch most document section references to 'single argument'. E.g., many places linked to "Text Properties" using @ref{Text Properties, , Text Properties}, rather than simply @ref{Text Properties}. 

While rendered links in PDFs, web pages, and the octave doc browser simply appear in either case as a hyperlinked "Text Properties", in any text rendering (Octave help or CLI doc browser) it would appear as "*note Text Properties:Text Properties", which is needlessly redundant.

Suggest a task of doing a find/replace throughout the full sourcecode for the redundancy. a

grep -r ',,' .

on the doc and script folders should generate the list, but maybe there's a more efficient way?

https://octave.1599824.n4.nabble.com/preferred-reference-format-to-help-manual-tp4695752.html

Nicholas Jankowski <nrjank>
Group Member

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

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 nrjank (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 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2020-02-18 rik5 StatusNone Fixed
        Open/ClosedOpen Closed
        Releasedev 6.0.90

    Back to the top

    Powered by Savane 3.13-caa5.
    Corresponding source code