Quantcast

Question about generate_html: indicate package version or not ?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Question about generate_html: indicate package version or not ?

Julien Bect-2
Hi all,

Currently the HTML doc produced by generate_html does not indicate the
version of the package for which the doc was generated (except in
index.html, of course).

Example : https://octave.sourceforge.io/io/function/append_save.html

I was thinking that it might be a good idea to indicate it on each page,
either in a visible manner (at the bottom of the page, for instance) or
at least as meta-data.

Any thought on this ?

@++
Julien


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Question about generate_html: indicate package version or not ?

PhilipNienhuis
Julien Bect-2 wrote
Hi all,

Currently the HTML doc produced by generate_html does not indicate the
version of the package for which the doc was generated (except in
index.html, of course).

Example : https://octave.sourceforge.io/io/function/append_save.html

I was thinking that it might be a good idea to indicate it on each page,
either in a visible manner (at the bottom of the page, for instance) or
at least as meta-data.

Any thought on this ?

@++
Julien
I only started thinking about this after reading your email :-)

Isn't it obvious that the html docs refers to the current package release?
What purpose would a version indicator serve? or, IOW, what can go wrong now?

Matlab has something like "present since version XXXXX" in its on-line docs for functions.
Maybe maybe that could be handy as well for OF packages (but also a lot of work; even more when considering that some functions have moved from one package to another or were even duplicates, like deg2rad).

Philip
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Question about generate_html: indicate package version or not ?

Julien Bect-2
Le 15/03/2017 à 16:51, PhilipNienhuis a écrit :

> Julien Bect-2 wrote
>> Hi all,
>>
>> Currently the HTML doc produced by generate_html does not indicate the
>> version of the package for which the doc was generated (except in
>> index.html, of course).
>>
>> Example : https://octave.sourceforge.io/io/function/append_save.html
>>
>> I was thinking that it might be a good idea to indicate it on each page,
>> either in a visible manner (at the bottom of the page, for instance) or
>> at least as meta-data.
>>
>> Any thought on this ?
>>
>> @++
>> Julien
> I only started thinking about this after reading your email :-)
>
> Isn't it obvious that the html docs refers to the current package release?

Yes, more or less.  But if you want to know what that "current release"
is, you have to go to another page.

> What purpose would a version indicator serve? or, IOW, what can go wrong now?

I simply find it convenient to be able to know instantly the version of
the package to which the doc corresponds.

Seems like a pretty standard thing to do.  See, e.g.,

http://scikit-learn.org/stable/modules/linear_model.html#ridge-regression 
(version number in title bar and in left menu)

https://docs.scipy.org/doc/numpy/reference/generated/numpy.apply_along_axis.html#numpy.apply_along_axis 
(version number under "SciPy.org")

http://docs.julialang.org/en/release-0.4/manual/modules/ (version number
in title bar and in URL)

https://golang.org/pkg/crypto/rc4/ (version number at the bottom of the
page)

https://www.lua.org/manual/5.3/manual.html#3.4.3 (version number in
title bar and in URL)

Loading...