Octave-Forge website / docs.html

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

Octave-Forge website / docs.html

Julien Bect
Carnë,

Two tiny remarks about the "Documentation" page
(http://octave.sourceforge.net/docs.html).

1) There's something wrong about this sentence:

"This is an online version of a version version of the Octave manual."

2) The last line has a broken link:

http://octave.sourceforge.net/soctcl0.1.zip

@++
Julien


Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Carnë Draug
On 11 August 2014 16:39, Julien Bect <[hidden email]> wrote:
> Carnë,
>
> Two tiny remarks about the "Documentation" page
> (http://octave.sourceforge.net/docs.html).
>
> 1) There's something wrong about this sentence:
>
> "This is an online version of a version version of the Octave manual."

Fixed. Thank you.

> 2) The last line has a broken link:
>
> http://octave.sourceforge.net/soctcl0.1.zip

Retrieved. I am unsure how useful or even up to date that is, though.

Carne

Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Julien Bect
Le 12/08/2014 03:58, Carnë Draug a écrit :
>> 2) The last line has a broken link:
>> >
>> >http://octave.sourceforge.net/soctcl0.1.zip
> Retrieved. I am unsure how useful or even up to date that is, though.

I don't know either, but perhaps this (and probably some other things
from the "Developers Documents" on
http://octave.sourceforge.net/docs.html) should go to the wiki or Agora
instead ?

Another remark : the "docs.html" page currently has a "User Questions"
section, which points to http://octave.sourceforge.net/FAQ.html, which
is itself empty except for a link to the Octave FAQ. I would suggest :

1) Renaming "User Questions" to "Frequently Asked Questions",

2) Since OF doen't yet have its own FAQ, linking directly from
"docs.html" to the Octave FAQ and perhaps removing "FAQ.html".


Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Carnë Draug
On 12 August 2014 07:19, Julien Bect <[hidden email]> wrote:

> Le 12/08/2014 03:58, Carnë Draug a écrit :
>>>
>>> 2) The last line has a broken link:
>>> >
>>> >http://octave.sourceforge.net/soctcl0.1.zip
>>
>> Retrieved. I am unsure how useful or even up to date that is, though.
>
> I don't know either, but perhaps this (and probably some other things from
> the "Developers Documents" on http://octave.sourceforge.net/docs.html)
> should go to the wiki or Agora instead ?

Probably the wiki. Fell free to create a page with it there and then I
could just link them.

> Another remark : the "docs.html" page currently has a "User Questions"
> section, which points to http://octave.sourceforge.net/FAQ.html, which is
> itself empty except for a link to the Octave FAQ. I would suggest :
>
> 1) Renaming "User Questions" to "Frequently Asked Questions",
>
> 2) Since OF doen't yet have its own FAQ, linking directly from "docs.html"
> to the Octave FAQ and perhaps removing "FAQ.html".

It used to have its own FAQ. But I removed it in favour of the much
more up to date and general FAQ on Octave's wiki. But I'm not sure I
like the idea of the FAQ button, which suggests an internal link,
redirecting the user to another host.

I'd gladly strip Octave Forge of all this content, move it to the wiki
where it is easier to change by everyone, and limit OF to browse
packages and their documentation. But this is way more work than what
I can offer. If people start editing Octave wiki with this info, they
could slowly be retired from the Octave Forge site.

Carnë

Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Julien Bect
Le 12/08/2014 18:23, Carnë Draug a écrit :

>> Another remark : the "docs.html" page currently has a "User Questions"
>> >section, which points tohttp://octave.sourceforge.net/FAQ.html, which is
>> >itself empty except for a link to the Octave FAQ. I would suggest :
>> >
>> >1) Renaming "User Questions" to "Frequently Asked Questions",
>> >
>> >2) Since OF doen't yet have its own FAQ, linking directly from "docs.html"
>> >to the Octave FAQ and perhaps removing "FAQ.html".
> It used to have its own FAQ. But I removed it in favour of the much
> more up to date and general FAQ on Octave's wiki. But I'm not sure I
> like the idea of the FAQ button, which suggests an internal link,
> redirecting the user to another host.

This isn't exactly what I was suggesting, sorry if I wasn't clear. My
suggestion was:

1) Link from "docs.html" directly to the FAQ on the wiki (this is done now)

2) Remove the FAQ from the top menu... but, if I understood correctly
your previous mail, changes to the top menu are not easy to do (?).


Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Carnë Draug
On 12 August 2014 17:41, Julien Bect <[hidden email]> wrote:

> Le 12/08/2014 18:23, Carnë Draug a écrit :
>>>
>>> Another remark : the "docs.html" page currently has a "User Questions"
>>> >section, which points tohttp://octave.sourceforge.net/FAQ.html, which is
>>> >itself empty except for a link to the Octave FAQ. I would suggest :
>>> >
>>> >1) Renaming "User Questions" to "Frequently Asked Questions",
>>> >
>>> >2) Since OF doen't yet have its own FAQ, linking directly from
>>> > "docs.html"
>>> >to the Octave FAQ and perhaps removing "FAQ.html".
>>
>> It used to have its own FAQ. But I removed it in favour of the much
>> more up to date and general FAQ on Octave's wiki. But I'm not sure I
>> like the idea of the FAQ button, which suggests an internal link,
>> redirecting the user to another host.
>
>
> This isn't exactly what I was suggesting, sorry if I wasn't clear. My
> suggestion was:
>
> 1) Link from "docs.html" directly to the FAQ on the wiki (this is done now)
>
> 2) Remove the FAQ from the top menu... but, if I understood correctly your
> previous mail, changes to the top menu are not easy to do (?).

Exactly. For the reasons explained on the other email, I won't be
doing this any time soon.

Carnë

Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Julien Bect
Le 12/08/2014 18:55, Carnë Draug a écrit :
>> 2) Remove the FAQ from the top menu... but, if I understood correctly your
>> >previous mail, changes to the top menu are not easy to do (?).
> Exactly. For the reasons explained on the other email, I won't be
> doing this any time soon.

I would be glad to help, although I'm not exactly sure of how I can
usefully contribute...

I think that it would be safer to be able to rebuild the whole website
"from scratch" if needed, which would make it much easier to change
things such as the top menu.

Easier said than done, I know, but perhaps is this a direction where I
could contribute, if I knew where to start from... Is there some sort of
"source code" for the website, somewhere ? I mean, a place where all the
data and admin scripts for building all the html pages are located ?

Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Julien Bect
In reply to this post by Carnë Draug
Le 12/08/2014 18:23, Carnë Draug a écrit :
>>>> 2) The last line has a broken link:
>>>>> http://octave.sourceforge.net/soctcl0.1.zip
>>> Retrieved. I am unsure how useful or even up to date that is, though.
>> I don't know either, but perhaps this (and probably some other things from
>> the "Developers Documents" onhttp://octave.sourceforge.net/docs.html)
>> should go to the wiki or Agora instead ?
> Probably the wiki. Fell free to create a page with it there and then I
> could just link them.

Actually, I just found out that this file (soctcl0.1.zip) is a very old
version of the tcl-octave package

http://octave.sourceforge.net/tcl-octave

which is itself listed as "unmaintained" on the Packages page of the OF
website.

Looks like you can safely remove the link from the "Documentation" page
and also the zip itself.

@++
Julien

Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

c.-2
In reply to this post by Carnë Draug

On 12 Aug 2014, at 18:55, Carnë Draug <[hidden email]> wrote:

>> but, if I understood correctly your
>> previous mail, changes to the top menu are not easy to do (?).
>
> Exactly. For the reasons explained on the other email, I won't be
> doing this any time soon.

To be more precise, the changes are very easy but they require regenerating
html help for ALL currently released packages wich is quite lengthy.

Julien, maybe you would be interested in helping with this yourself?
I can provide detailed directions if you are interested.

> Carnë
c.
Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Julien Bect
Le 13/08/2014 07:19, c. a écrit :
> On 12 Aug 2014, at 18:55, Carnë Draug <[hidden email]> wrote:
>>> but, if I understood correctly your
>>> previous mail, changes to the top menu are not easy to do (?).
>> Exactly. For the reasons explained on the other email, I won't be
>> doing this any time soon.
> To be more precise, the changes are very easy but they require regenerating
> html help for ALL currently released packages wich is quite lengthy.

Lengthy... and not fully automated, I assume ?

> Julien, maybe you would be interested in helping with this yourself?
> I can provide detailed directions if you are interested.

Yes, I already proposed to help (see above, same thread).



Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

c.-2

On 13 Aug 2014, at 07:36, Julien Bect <[hidden email]> wrote:

> Lengthy... and not fully automated, I assume ?
actually it almost all automated, what needs to be done is:

1) install ALL packages.
2) patch generate_html to produce web pages with the new style
3) run generate_package_html for each package
4) upload all new html files to sourceforge

steps 3 and 4 will take quite a bit of time but are easily automated.

Carnë, correct me if something is missing from the list.

To make this easier in the future I'd move the code for the top menu into
a separate .php script and then invoke it from each static page, instead
of copying the static code into each page as it is done now.

c.
Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Julien Bect
Le 13/08/2014 11:14, c. a écrit :
> On 13 Aug 2014, at 07:36, Julien Bect <[hidden email]> wrote:
>> Lengthy... and not fully automated, I assume ?
> actually it almost all automated,

Ok. So my first goal will be to make it FULLY (and not almost) automated.

>   what needs to be done is:
>
> 1) install ALL packages.

Let's tackle this one first... Is there somewhere a "raw" list of all
the packages that must be included ?

It seems that I can obtain it by parsing one of the following pages :

http://octave.sourceforge.net/packages.php

http://sourceforge.net/projects/octave/files/Octave%20Forge%20Packages/Individual%20Package%20Releases/

but shouldn't there be a "source" for this somewhere (for the sake of
argument, think of the extreme case where both the FRS data and the web
data are lost on SF) N

> 2) patch generate_html to produce web pages with the new style
> 3) run generate_package_html for each package
> 4) upload all new html files to sourceforge


Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

c.-2

On 13 Aug 2014, at 11:28, Julien Bect <[hidden email]> wrote:

> Le 13/08/2014 11:14, c. a écrit :
>> On 13 Aug 2014, at 07:36, Julien Bect <[hidden email]> wrote:
>>> Lengthy... and not fully automated, I assume ?
>> actually it almost all automated,
>
> Ok. So my first goal will be to make it FULLY (and not almost) automated.
>
>>  what needs to be done is:
>>
>> 1) install ALL packages.
>
> Let's tackle this one first... Is there somewhere a "raw" list of all the packages that must be included ?
>
> It seems that I can obtain it by parsing one of the following pages :
>
> http://octave.sourceforge.net/packages.php
>
> http://sourceforge.net/projects/octave/files/Octave%20Forge%20Packages/Individual%20Package%20Releases/
>
> but shouldn't there be a "source" for this somewhere (for the sake of argument, think of the extreme case where both the FRS data and the web data are lost on SF) N

the list used internally by pkg.m is here:

http://octave.sourceforge.net/list_packages.php

be aware that this is not a static text file it is generated
by a server-side script by iterating over all directories containing
html docs.

c.
Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

c.-2

On 13 Aug 2014, at 12:46, c. <[hidden email]> wrote:

> the list used internally by pkg.m is here:
>
> http://octave.sourceforge.net/list_packages.php
>
> be aware that this is not a static text file it is generated
> by a server-side script by iterating over all directories containing
> html docs.


If you want to parse this list in an Octave script, have a look at:

scripts/pkg/private/list_forge_packages.m

and

scripts/pkg/private/get_forge_pkg.m

c.


Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Julien Bect
In reply to this post by c.-2
Le 13/08/2014 12:46, c. a écrit :

> On 13 Aug 2014, at 11:28, Julien Bect <[hidden email]> wrote:
>
>> Le 13/08/2014 11:14, c. a écrit :
>>> On 13 Aug 2014, at 07:36, Julien Bect <[hidden email]> wrote:
>>>> Lengthy... and not fully automated, I assume ?
>>> actually it almost all automated,
>> Ok. So my first goal will be to make it FULLY (and not almost) automated.
>>
>>>   what needs to be done is:
>>>
>>> 1) install ALL packages.
>> Let's tackle this one first... Is there somewhere a "raw" list of all the packages that must be included ?
>>
>> It seems that I can obtain it by parsing one of the following pages :
>>
>> http://octave.sourceforge.net/packages.php
>>
>> http://sourceforge.net/projects/octave/files/Octave%20Forge%20Packages/Individual%20Package%20Releases/
>>
>> but shouldn't there be a "source" for this somewhere (for the sake of argument, think of the extreme case where both the FRS data and the web data are lost on SF) N
> the list used internally by pkg.m is here:
>
> http://octave.sourceforge.net/list_packages.php
>
> be aware that this is not a static text file it is generated
> by a server-side script by iterating over all directories containing
> html docs.

Ok, I understand. Is there a (public visible) repository where all these
php scripts are developed ?


Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

c.-2

On 13 Aug 2014, at 13:03, Julien Bect <[hidden email]> wrote:

> Ok, I understand. Is there a (public visible) repository where all these php scripts are developed ?

Not that I know, until now they have just been edited in place.
If you have an OF account you can get them via ssh/sftp from the server.
c.
Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Julien Bect
In reply to this post by c.-2
Le 13/08/2014 12:46, c. a écrit :
> the list used internally by pkg.m is here:
>
> http://octave.sourceforge.net/list_packages.php
>
> be aware that this is not a static text file it is generated
> by a server-side script by iterating over all directories containing
> html docs.

It seems a little unnatural to me to require that the whole OF website
has been built to be able to get something as "primitive" as the list of
all Octave packages...

Especially since I'm looking for a way to _build_ the website... If the
website is lost, then I cannot get the package list... so how I can I
rebuild the website ?

It would make more sense to me to have a STATIC list of packages
somewhere (perhaps on a Mercurial repo on SF, together with all the
other admin scripts that are used to build the website ?) that could be
used to build the website, and also uploaded as
octave.sourceforge.net/list_packages.txt (for instance) for use from pkg.

Does that make sense to you ?

Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Søren Hauberg


Den 13-08-2014 kl. 13:23 skrev Julien Bect:

> Le 13/08/2014 12:46, c. a écrit :
>> the list used internally by pkg.m is here:
>>
>> http://octave.sourceforge.net/list_packages.php
>>
>> be aware that this is not a static text file it is generated
>> by a server-side script by iterating over all directories containing
>> html docs.
>
> It seems a little unnatural to me to require that the whole OF website
> has been built to be able to get something as "primitive" as the list of
> all Octave packages...

The motivation for it this way was to minimise the burden of the OF
administrators. Back when I was actively involved, running OF took quite
a bit of time, so the more files that needed to be edited the more
time-consuming release-related tasks became.

I'm not arguing against a static list of packages, but I urge you to
pick a system which requires the smallest amount of work to maintain --
maintaining the web site is the task which is the least fun to most
people in this community, so if it becomes a hurdle nobody will do it.

Several people (myself included) basically burned out because of
annoying web-maintenance responsibilities. So, please don't design a
system which require a small amount of work to maintain -- design a
system which require the *smallest possible* amount of work to maintain.

Cheers
Søren

Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

c.-2
In reply to this post by Julien Bect

On 13 Aug 2014, at 13:23, Julien Bect <[hidden email]> wrote:

> Le 13/08/2014 12:46, c. a écrit :
>> the list used internally by pkg.m is here:
>>
>> http://octave.sourceforge.net/list_packages.php
>>
>> be aware that this is not a static text file it is generated
>> by a server-side script by iterating over all directories containing
>> html docs.
>
> It seems a little unnatural to me to require that the whole OF website has been built to be able to get something as "primitive" as the list of all Octave packages...
>
> Especially since I'm looking for a way to _build_ the website... If the website is lost, then I cannot get the package list... so how I can I rebuild the website ?
>
> It would make more sense to me to have a STATIC list of packages somewhere (perhaps on a Mercurial repo on SF, together with all the other admin scripts that are used to build the website ?) that could be used to build the website, and also uploaded as octave.sourceforge.net/list_packages.txt (for instance) for use from pkg.
>
> Does that make sense to you ?

No, it doesn't.

With the current setup, the process to make a package release is very simple,
the package maintainer produces the package tarball and html docs and the site
maintainer uploads the docs to the website.

When a new package is added or removed the list changes automatically.

So there is no maintainance work to be done on the package list, while
maintainance of each package is completely done by the package maintainers.

The main idea behind the design of Octave Forge is to reduce centralized
maintainance to a minimum and delegate as many tasks as possible to package maintainers.

Whatever change you plan, I strongly recommend that you please follow this approach
anything else has proven to be unpractical with the EXTREMELY low workforce we
can dedicate to site maintaince.

c.






Reply | Threaded
Open this post in threaded view
|

Re: Octave-Forge website / docs.html

Julien Bect
Le 13/08/2014 13:37, c. a écrit :

> On 13 Aug 2014, at 13:23, Julien Bect <[hidden email]> wrote:
>
>> Le 13/08/2014 12:46, c. a écrit :
>>> the list used internally by pkg.m is here:
>>>
>>> http://octave.sourceforge.net/list_packages.php
>>>
>>> be aware that this is not a static text file it is generated
>>> by a server-side script by iterating over all directories containing
>>> html docs.
>> It seems a little unnatural to me to require that the whole OF website has been built to be able to get something as "primitive" as the list of all Octave packages...
>>
>> Especially since I'm looking for a way to _build_ the website... If the website is lost, then I cannot get the package list... so how I can I rebuild the website ?
>>
>> It would make more sense to me to have a STATIC list of packages somewhere (perhaps on a Mercurial repo on SF, together with all the other admin scripts that are used to build the website ?) that could be used to build the website, and also uploaded as octave.sourceforge.net/list_packages.txt (for instance) for use from pkg.
>>
>> Does that make sense to you ?
> No, it doesn't.
>
> With the current setup, the process to make a package release is very simple,
> the package maintainer produces the package tarball and html docs and the site
> maintainer uploads the docs to the website.

Why ask the package maintainer to produce the html doc himself ? Because
some packages do not rely on generate_html to do this ?

> [...]
>
> Whatever change you plan, I strongly recommend that you please follow this approach
> anything else has proven to be unpractical with the EXTREMELY low workforce we
> can dedicate to site maintaince.

I understand your point. It is very important that the maintenance
burdens should remain as low as possible.

It seems to me, however, that having a static list of package *names*
adds very little to the current maintenance routine.

In fact, the only difference, I believe, is that when a *new package* is
added (not a new release of an existing package), the static list must
be updated.

Another option would be to have a list of *unmaintained* packages. In
this case, we could obtain the list of packages by parsing

http://sourceforge.net/projects/octave/files/Octave%20Forge%20Packages/Individual%20Package%20Releases

and then removing unmaintained packages from the list.

Does any of this makes sense to you ? Or does it still look too heavy ?

12