preferred reference format to help/manual?

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

preferred reference format to help/manual?

nrjank
Administrator
(texinfo newbie, so please correct my ignorance here)

looking at different docstrings I see mixed uses of:

@ref{Text Properties}

and 

@ref{Text Properties,, Text Properties}

and similar. 

is the redundancy necessary?  Why the skipped input, and is there something about the Octave manual layout that requires the seemingly redundant node callout?

The latter just shows up as a "Text Properties" hyperlink in the rendered docs, but in text displays shows up as 
*note Text Properties: Text Properties.

(and in the doc viewer only the first part is hyperlinked)

without the redundant node callout it's
  *note Text Properties::


Reply | Threaded
Open this post in threaded view
|

Re: preferred reference format to help/manual?

Mike Miller-4
On Mon, Feb 17, 2020 at 16:44:18 -0500, Nicholas Jankowski wrote:

> (texinfo newbie, so please correct my ignorance here)
>
> looking at different docstrings I see mixed uses of:
>
> @ref{Text Properties}
>
> and
>
> @ref{Text Properties,, Text Properties}
>
> and similar.
>
> is the redundancy necessary?  Why the skipped input, and is there something
> about the Octave manual layout that requires the seemingly redundant node
> callout?
Well the syntax is described here:

  https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040ref.html

In your particular example, the link to "Text Properties" in plot.txi
was added in 2008, for Octave version 3.2.0.

Then the links to properties in individual function docstrings (text.m
in this case) were added in 2018, for Octave version 4.4.0.

So the link in plot.txi after @DOCSTRING(text) is now redundant, can
probably be dropped.

It might be better to use the one-argument syntax, it only depends on
how we want the link to be formatted in each particular usage.

Does that help?

--
mike

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: preferred reference format to help/manual?

nrjank
Administrator
On Mon, Feb 17, 2020 at 6:08 PM Mike Miller <[hidden email]> wrote:
On Mon, Feb 17, 2020 at 16:44:18 -0500, Nicholas Jankowski wrote:

It might be better to use the one-argument syntax, it only depends on
how we want the link to be formatted in each particular usage.

Does that help?
 
Yes, that makes sense. I was putting a patch together to knock out bug #50247.  Absent any objections I'll go with the one-argument syntax for my changes. Changing it elsewhere sounds like a much bigger search and destroy task.