Easy navigation to function doc in the HTML manual

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

Easy navigation to function doc in the HTML manual

siko1056
Dear Octavers,

Here is a small proposal for a Javascript extension "ref.html" of the HTML reference manual to easily navigate to the documentation of a specific function, just knowing its name.

To find the documentation of the "plot" function, other documentations have a base URL + the function name, e.g.

https://help.scilab.org/docs/6.0.0/en_US/plot.html
https://www.mathworks.com/help/matlab/ref/plot.html
https://www.gnu.org/software/octave/doc/interpreter/Two_002dDimensional-Plots.html#XREFplot

Now you want to lookup the "abs" function. In the first two URLs, one simply replaces the function name and is there. For Octave some googling or [function index][1] reveals the following URL:

https://www.gnu.org/software/octave/doc/interpreter/Complex-Arithmetic.html#XREFabs

I think the problem is apparent. With the inclusion of "ref.html", the two URLs can be resolved via:

https://www.gnu.org/software/octave/doc/interpreter/ref.html?plot
https://www.gnu.org/software/octave/doc/interpreter/ref.html?abs

which is basically just a post-processing of [1] to a Javascript. If someones disagrees with this feature, I'll remove it. I find it especially useful for the upcoming "publish" function, where the possibility to link to Octave function documentation should be given in the next version.

Best,
Kai.


[1]: https://www.gnu.org/software/octave/doc/interpreter/Function-Index.html
Reply | Threaded
Open this post in threaded view
|

Re: Easy navigation to function doc in the HTML manual

Oliver Heimlich
On 24.10.2016 13:50, siko1056 wrote:

> Dear Octavers,
>
> Here is a small proposal for a Javascript extension "ref.html" of the HTML
> reference manual to easily navigate to the documentation of a specific
> function, just knowing its name.
>
> To find the documentation of the "plot" function, other documentations have
> a base URL + the function name, e.g.
>
> https://help.scilab.org/docs/6.0.0/en_US/plot.html
> https://www.mathworks.com/help/matlab/ref/plot.html
> https://www.gnu.org/software/octave/doc/interpreter/Two_002dDimensional-Plots.html#XREFplot
>
> Now you want to lookup the "abs" function. In the first two URLs, one simply
> replaces the function name and is there. For Octave some googling or
> [function index][1] reveals the following URL:
>
> https://www.gnu.org/software/octave/doc/interpreter/Complex-Arithmetic.html#XREFabs
>
> I think the problem is apparent. With the inclusion of "ref.html", the two
> URLs can be resolved via:
>
> https://www.gnu.org/software/octave/doc/interpreter/ref.html?plot
> https://www.gnu.org/software/octave/doc/interpreter/ref.html?abs
>
> which is basically just a post-processing of [1] to a Javascript. If
> someones disagrees with this feature, I'll remove it. I find it especially
> useful for the upcoming "publish" function, where the possibility to link to
> Octave function documentation should be given in the next version.

Kai,

what you want to do is already provided by Texinfo.  There are XREF html
pages for all functions from the function index.  For example, you can
simply use

https://www.gnu.org/software/octave/doc/interpreter/XREFplot.html

If you want to reference some function from inside another Texinfo
document you may use a htmlxref configuration file with “octave node
https://www.gnu.org/software/octave/doc/interpreter/” and can then use
xref commands as well:

@xref{Two-Dimensional Plots,,, octave}
@xref{XREFplot,, plot, octave}

… which will let you reference chapters or functions from the function
index.

Oliver

Reply | Threaded
Open this post in threaded view
|

Re: Easy navigation to function doc in the HTML manual

siko1056
Dear Oliver,

That makes my improvement for publish a no-brainer... Thanks a lot! I removed ref.html.

Best,
Kai
Reply | Threaded
Open this post in threaded view
|

Re: Easy navigation to function doc in the HTML manual

John W. Eaton
Administrator
On 10/24/2016 05:32 PM, siko1056 wrote:
> Dear Oliver,
>
> That makes my improvement for publish a no-brainer... Thanks a lot! I
> removed ref.html.

Also, if you'd prefer something like

   https://www.gnu.org/software/octave/functions/plot

then I think we can do that with a server rewrite rule that transforms
that URL into

   https://www.gnu.org/software/octave/doc/interpreter/XREFplot.html

jwe


Reply | Threaded
Open this post in threaded view
|

Re: Easy navigation to function doc in the HTML manual

siko1056
John W. Eaton wrote
Also, if you'd prefer something like

   https://www.gnu.org/software/octave/functions/plot

then I think we can do that with a server rewrite rule that transforms
that URL into

   https://www.gnu.org/software/octave/doc/interpreter/XREFplot.html

jwe
This should be possible, but the XREF-mechanism is good enough for my purpose, as the links are deterministic as in the Scilab oder Matlab manual. My problem with publish is, that I need to translate links like <octave:plot See the plot function> to a meaningful manual URL and it works using XREF.

Kai
Reply | Threaded
Open this post in threaded view
|

Re: Easy navigation to function doc in the HTML manual

John W. Eaton
Administrator
On 10/25/2016 08:45 AM, siko1056 wrote:

> John W. Eaton wrote
>> Also, if you'd prefer something like
>>
>>    https://www.gnu.org/software/octave/functions/plot
>>
>> then I think we can do that with a server rewrite rule that transforms
>> that URL into
>>
>>    https://www.gnu.org/software/octave/doc/interpreter/XREFplot.html
>>
>> jwe
>
> This should be possible, but the XREF-mechanism is good enough for my
> purpose, as the links are deterministic as in the Scilab oder Matlab manual.
> My problem with publish is, that I need to translate links like <octave:plot
> See the plot function> to a meaningful manual URL and it works using XREF.

OK.

jwe