patchGNU Octave - Patches: patch #8988, Adding to index.html of manual,...

 
 

patch #8988: Adding to index.html of manual, installation/loading commands

Submitted by:  Fernando Pujaico Rivera <trucomanx>
Submitted on:  Thu 28 Apr 2016 08:41:27 PM UTC  
 
Category: NonePriority: 5 - Normal
Status: NonePrivacy: Public
Assigned to: NoneOpen/Closed: Open

Add a New Comment(Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

(Jump to the original submission Jump to the original submission)

Tue 24 May 2016 05:28:29 PM UTC, comment #21:

I understand and respect that the public target of index pages of octave-forge packages, they not is people that not to know OCTAVE.

This carry me to my another patch #8990, given that in the url of the package could be the place to locate the documentation relative to public target of package. bsltl by example : More oriented to people that begin with octave and octave-forge through of this.

I am according that octave-forge need a page of "getting started" about only of packages (instal/uninstall/load/auto/etc).
Thus, the index page of packages could have a link to this page.

I like of the explication of http://www.gnu.org/software/octave/doc/interpreter/Installing-and-Removing-Packages.html

We could clone this page in html and modify this to that the package name used in the examples (current:image) be the package name of caller site,
but I don't know if octave-forge site accept php, or if this can be made with javascript.

Fernando Pujaico Rivera <trucomanx>
Tue 24 May 2016 02:03:11 PM UTC, comment #20:

Fernando Pujaico Rivera <trucomanx> said on comment #17:
< [...]

> And statistics work the same way for me, but bsltl not.
> [..]


Yes, this only works for functions that exist in Mathworks toolboxes. For example, it will "fail" for fftconvn, a function from the Octave image package, because it is not on the Mathworks image toolbox. This is why I said "I'll guess that new users are more likely to be faced with this issue [...] when dealing with functions from one of the Matlab toolboxes".

Fernando Pujaico Rivera <trucomanx> said on comment #18:

> [...]
> I think that to install and load is a simple job, for people that know that the commands exist,
> but to people that only found a library by your characteristics, and is through of this search that begin in octave, I know that is a great help.
> [...]


Which is why I said "this boils down to: who's the target audience for the index page of a package?". The audience you are targeting, people that "found a library by your characteristics, and is through of this search that begin in octave" is not the target. The target audience are Octave users that are looking for a package that does something specific. In that case, this page should describe briefly what the package does, and a link for further documentation (which may include install and load instructions).

If the target audience is someone that has never used Octave before, and you're assuming that someone will start to use Octave because of the package index page, there are a lot of other things that will need to be explained.

---

Just my opinion. I think Julien is right that if Octave users are having trouble installing and loading packages, then we need to fix that other documentation and making it much easier to find.

Carnë Draug <carandraug>
Project Member
Tue 24 May 2016 11:56:40 AM UTC, comment #19:

I agree with Carnë that copying standard installation instructions on all index.html pages is perhaps not a great idea.

On the other hand, I think that this kind of basic "Getting started" information should be found very easily on the Octave Forge website. Currently, it's not.

This points to the Octave Forge website (and GNU FAQ) as the relevant target(s) for improvement, in my opinion.

Let me give a few examples:

  • There is actually a video, which should be useful for newcomers, on this page: https://sourceforge.net/projects/octave. But getting there from a package index file is not easy (you have to select "Link", which is the 8th item in a rather long list of nine items, and then click on the obscure "SourceForge summary page for the Octave-Forge project" link).
  • There is a also FAQ link in the header bar, which points to an almost empty page, which points to the general FAQ... which contains very little information about packages (and not basic stuff such as "pkg install -forge ...").
  • I just realized that the "pkg install -forge ..." instruction is actually available from the "Home" page. But I don't think that people looking at a particular package and wondering how to install it will go back to the home page. They would rather look for something called "Help", "Getting started" or "Documentation".

I would suggest:

1. providing some very basic "getting started" information on the Documentation page (more or less what Fernando wants to insert in index.html pages);

2. dealing with more specific (but yet common) questions in a dedicated section of the FAQ, which needs to be created;

3. simplifying access to the most important information by reducing the number of items in the header bar: I think that a single "Help" page could gather all the information for packages users (not developers) which is currently scattered accross the home page, the documentation page, the FAQ page (redundant with the documentation page); similarly, a developers page would gather the information for developpers (scattered accross the home page, the developers page, the mailing list page, the code page...).

Julien Bect <jbect>
Tue 24 May 2016 01:55:01 AM UTC, comment #18:

I think that to install and load is a simple job, for people that know that the commands exist,

but to people that only found a library by your characteristics, and is through of this search that begin in octave, I know that is a great help.

I work as a programmer writing some things to PhD students of agriculture and related sciences, and see important this help.

unfortunately I see the same problem in electrical engineering people who only knew matlab and windows.

Fernando Pujaico Rivera <trucomanx>
Tue 24 May 2016 01:20:21 AM UTC, comment #17:

I have the version OCTAVE_VERSION = 4.0.0
And statistics work the same way for me, but bsltl not.

>> pkg uninstall bsltl


>> C=coom([ 1 2 3 4; 1 2 3 4]);

error: 'coom' undefined near line 1 column 3

>> pkg install -forge bsltl


>> C=coom([ 1 2 3 4; 1 2 3 4]);

error: 'coom' undefined near line 1 column 3

>> pkg load bsltl
>> C=coom([ 1 2 3 4; 1 2 3 4]);


I think that some packages yes and others not.

Fernando Pujaico Rivera <trucomanx>
Tue 24 May 2016 12:52:06 AM UTC, comment #16:

I will just throw a very different opinion for your consideration. I don't think that a package index page should have install and load instructions.

Installing and loading package is a pretty standard and simple job. So standard and simple that makes install and load instructions only useful for very new Octave users. Anyone else will already know it so adding this instructions will increase cognitive load of the page. Note that just because one already knows the information in those info boxes, it doesn't mean there is no cost associated. The info in the boxes still needs to recognized so one knows it can be ignored. This would make the page worse for Octave users.

There is also one other reason why even recent users will already now about pkg. Without wanting to downplay the importance of the many Forge packages, I'll guess that new users are more likely to be faced with this issue (install and loading a package) when dealing with functions from one of the Matlab toolboxes. In such case, Octave will already show the user a error message reminding the user first to install (maybe we should show how to actually install a package instead of just noting is not installed?), and then to load the package:

I'd argue that this boils down to: who's the target audience for the index page of a package? Is it for an Octave user (which will already know about pkg) to gain information about the package? Or is it for new Octave users that will start using it? These instructions are only useful for the later and will just be noise for others.

Carnë Draug <carandraug>
Project Member
Mon 23 May 2016 04:28:48 PM UTC, comment #15:

Maybe, as you say, the link in my patch :

http://www.gnu.org/software/octave/doc/interpreter/Installing-and-Removing-Packages.html

should be change to :

[../../getting.html]

and leave a html page that redirect to:

http://www.gnu.org/software/octave/doc/interpreter/Installing-and-Removing-Packages.html

thus, if the link change, we only need change the getting.html.

I am attaching the getting.html.

(file #37238)

Fernando Pujaico Rivera <trucomanx>
Mon 23 May 2016 12:50:46 AM UTC, comment #14:

PS: How can I post message with source code with "rich markup"? like the comment #4

Fernando Pujaico Rivera <trucomanx>
Mon 23 May 2016 12:34:59 AM UTC, comment #13:

I made some changes,
I am attaching a new diff file with the changes.

Here, you can see an use example:

http://nongnu.org/bsltl/bsltl_refman/bsltl/

To make this example I used the next code:

options = get_html_options ("octave-forge");
options.package_doc="overview.texi";
options.package_doc_options=[options.package_doc_options," --init-file=/path-to-file/overview.init"];
options.package_doc_options=[options.package_doc_options," --css-ref=manual.css"];
generate_package_html ("bsltl", "bsltl_html", options);

I think that I attended its recommendations,
I like to know your comments>

(file #37231)

Fernando Pujaico Rivera <trucomanx>
Thu 19 May 2016 08:03:08 AM UTC, comment #12:

Feel free to use / generalize the text from the section “Installation” in https://sourceforge.net/p/octave/interval/ci/default/tree/doc/chapter/getting-started.texinfo for the FAQ page.

Unfortunately, I don't have the time to do it myself before the end of month.

Oliver Heimlich <oheim>
Thu 19 May 2016 07:13:31 AM UTC, comment #11:

The FAQ might be an appropriate place, if a section dedicated to packages were inserted in it.

Julien Bect <jbect>
Thu 19 May 2016 07:01:03 AM UTC, comment #10:

As a "minimal" content for the Octave Forge style I would suggest

  • Install from the network: `pkg install -forge ...`
  • Load the package before use: `pkg load ...`
  • See (link to some appropriate place) for more information.
Julien Bect <jbect>
Thu 19 May 2016 06:28:54 AM UTC, comment #9:

I like the alternative. Regarding the last point: The Octave Forge FAQ page would be a good place to put further information.

Oliver Heimlich <oheim>
Thu 19 May 2016 05:48:51 AM UTC, comment #8:

I'm not a big fan of the "loading" section on the right.

First, because any user trying to use a function from an unloaded package gets an error message indicating that he must use "pkg load ..." first.

Second, because it don't find it very elegant...

-----

I would like to propose an alternative:

  • Add only one new subsection, with both heading and content configurable through options.
  • Make this section optional: it the content option field is empty, the section is not displayed at all.
  • For the Octave Forge option set, use "Getting started" as a title and provide a minimal content made of link to some other page on the Octave Forge website.

The last point is important: it means that if we want to modify the "Getting started" instructions for Octave Forge packages, we don't have to re-generate to documentation of all Octave Forge packages.

Julien Bect <jbect>
Thu 19 May 2016 05:33:37 AM UTC, comment #7:

Following up on comment #4:

The title "Online installing" is not suitable for all use cases of the generate HTML package.

I believe a "Installation", or "Installation instructions" would be better.

Julien Bect <jbect>
Thu 19 May 2016 05:27:39 AM UTC, comment #6:

For the link to "offline installation methods", perhaps would it be better to provide a direct link to

http://www.gnu.org/software/octave/doc/interpreter/Installing-and-Removing-Packages.html#Installing-and-Removing-Packages

Julien Bect <jbect>
Thu 19 May 2016 01:28:07 AM UTC, comment #5:

It is true, I will make the change soon and I will post here.

Fernando Pujaico Rivera <trucomanx>
Wed 18 May 2016 11:18:01 PM UTC, comment #4:

Your patch is only going to work if the package is hosted on Octave Forge due to the -forge option in the install box.

I'd suggest to configure the commands with get_html_options (…). The default template should produce the install command:

The “octave-forge” template should produce the install command:

You probably have to use placeholders like %name, %version, and %extension.

Oliver Heimlich <oheim>
Wed 04 May 2016 12:34:56 PM UTC, comment #3:

I understand what you say.
I think that we can call this, as "Online installing" leaving clear that is necessary an internet connection. Adding a link to the complete installation manual.

As can be seen, now, in the modification here:

http://www.nongnu.org/bsltl/bsltl_refman/bsltl/

Thus, other people that search another installation method, they can found the specific method to your necessity.

PS: I have attached the new diff file: Adding-online-offline-installation-method.diff

(file #37062)

Fernando Pujaico Rivera <trucomanx>
Sun 01 May 2016 01:18:31 PM UTC, comment #2:

I like that proposal. It fixes the most common issue for new users.

On the other side, package installation might become more complicated than that, so we should add a link (next to the install instructions) to a new page on Octave Forge that explains this in greater details (the big orange box at http://octave.sourceforge.net/ is insufficient as well).

- Users of the Octave windows installer don't have to install certain packages
- In several GNU distributions it is preferred to use the redistributed version of the package (e. g. Debian, Fedora, …)
- When the workstation is not connected to the internet, the user might want to fall back to manual download and install w/o the -forge option
- (and so on)

Oliver Heimlich <oheim>
Thu 28 Apr 2016 10:15:27 PM UTC, comment #1:

I forgot to say that I'm talking about the package generate html

Fernando Pujaico Rivera <trucomanx>
Thu 28 Apr 2016 08:41:27 PM UTC, original submission:

I like to propose show the installation/loading commands in the index page of reference manual.
I send adjoint a diff file with the modification.

I think that this is important, given that the octave packages are unloaded by default.
And many people don't know how make this in the command line.

The reference manual is the first information found in the search of web.

You can see an example of this modification in the next site.

http://nongnu.org/bsltl/bsltl_refman/bsltl/index.html

Fernando Pujaico Rivera <trucomanx>

 

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

Attach File(s):
   
   
Comment:
   

Attached Files
file #37238:  getting.html added by trucomanx (455B - text/html - Redirect to getting started)
file #37231:  adding-getting-started-and-install-load.diff added by trucomanx (3KiB - text/x-patch - Adding getting started)
file #37062:  Adding-online-offline-installation-method.diff added by trucomanx (2KiB - text/x-diff - generate_html : source example )
file #37013:  generate_html.diff added by trucomanx (1KiB - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -unavailable- added by jbect (Posted a comment)
  • -unavailable- added by oheim (Posted a comment)
  • -unavailable- added by trucomanx (Submitted the item)
  • -unavailable- added by trucomanx
  • -unavailable- added by trucomanx
  • -unavailable- added by trucomanx
  •  

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    Follow 7 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Mon 23 May 2016 04:28:48 PM UTCtrucomanxAttached File-=>Added getting.html, #37238
    Mon 23 May 2016 12:34:59 AM UTCtrucomanxAttached File-=>Added adding-getting-started-and-install-load.diff, #37231
    Wed 04 May 2016 12:34:56 PM UTCtrucomanxAttached File-=>Added Adding-online-offline-installation-method.diff, #37062
    Thu 28 Apr 2016 08:41:27 PM UTCtrucomanxAttached File-=>Added generate_html.diff, #37013
      Carbon-Copy-=>Added -unavailable-
      Carbon-Copy-=>Added -unavailable-
      Carbon-Copy-=>Added -unavailable-

    Back to the top


    Powered by Savane 3.1-cleanup1