# patch #8990: generate_html : Adding field (additional documentation:url) to index.html of ref-man

 Submitted by: Fernando Pujaico Rivera Submitted on: Sun 01 May 2016 11:17:28 AM UTC Category: None Priority: 5 - Normal Status: Done Privacy: Public Assigned to: None Open/Closed: Closed

You are not logged in

## Discussion

Thu 14 Jul 2016 08:37:06 AM UTC, comment #22:

This patch can be closed.

Julien Bect <jbect>
Thu 14 Jul 2016 08:36:34 AM UTC, comment #21:

Ok, here is what I have done:

1) I have provided a dedicated icon and CSS class for homepage links.  Both generate_html and project have been modified.  The icon comes from the Tango icon theme, which is in the public domain.

2) I have implemented support for multiple URLs, assuming "," as a delimiter.  Currently, the links are labeled "Homepage" if there is only one link, and "Homepage #1", ..., "Homepage #n" if there are several.

Julien Bect <jbect>
Thu 07 Jul 2016 08:46:24 PM UTC, comment #20:

There is no definition how multiple url should be defined but the packages who do it use a comma.

Use this on the octave-forge repository http://hg.code.sf.net/p/octave/octave-forge

find -maxdepth 2 -name DESCRIPTION | xargs grep -i --color url

Some examples

Carnë Draug <carandraug>
Thu 07 Jul 2016 06:05:27 PM UTC, comment #19:

I have pushed the change to "Homepage".

There are still two issues, I think:

a) The current code assume only one URL and fails if there is a list of URLs.  I can try to make it work for lists of URLs, but how are they supposed to be arranged? what is the delimiter? Is there at least one example of a package with such a list out there?

b) There is no homepage icon.  Currently it points to the news icon, but I don't think it should stay like that.

Julien Bect <jbect>
Thu 07 Jul 2016 12:58:10 PM UTC, comment #18:

Carnë,

I don't necessarily want to make it an option, but I have to disagree with your argumentation:

a) "coherent style" doesn't mean identical content,

b) The generate_package_html function is not meant to be used for the Octave Forge website only, or for Octave Forge packages only.

---

Anyway, I count you in for "Homepage".

Anyone else?

Julien Bect <jbect>
Thu 07 Jul 2016 12:51:43 PM UTC, comment #17:

I don't care much anyway. I will be happy with homepage but don't make it an option since then each package will look different and we should have a coherent style.

Carnë Draug <carandraug>
Thu 07 Jul 2016 12:42:16 PM UTC, comment #16:

For all the packages that I have been looking at, there was actually just one link (even if several is possible in principle) and "Homepage" was an accurate, or at least acceptable, description of the page pointed to.

There is also the case of many Octave Forge packages which point to the root of the OF website, for which the "External links" heading sounds inappropriate...

I guess there will be no universally good solution, so I propose the following:

a) Make this configurable through the option structure.

b) Use "Homepage" (singular) as the default.

What do you think?

Julien Bect <jbect>
Thu 07 Jul 2016 12:33:22 PM UTC, comment #15:

The documentation for url field says that it's "list of homepages related to the package."

However, that doesn't make much sense to me if there's many urls. Instead, "External links" would make more sense to me (similar to what happens in wikipedia pages).

Carnë Draug <carandraug>
Thu 07 Jul 2016 11:58:33 AM UTC, comment #14:

So, we have two votes in favour of "Homepage".

Everyone else ?

Julien Bect <jbect>
Thu 07 Jul 2016 11:30:43 AM UTC, comment #13:

I like of name of: homepage, yes.

Fernando Pujaico Rivera <trucomanx>
Wed 06 Jul 2016 04:27:35 PM UTC, comment #12:

Ok I have pushed Fernando's patch.

@Fernando: I have made a minor change to the first line of the patch... Was there a reason to call insert_html_entities on list.url ?

The link is currently name "Additional documentation".  This doesn't seem entirely appropriate to me.  Perhaps "Homepage" would be better.  At least, this would be consistent with the Octave manual:

What do you think ?

Julien Bect <jbect>
Wed 06 Jul 2016 01:18:16 PM UTC, comment #11:

Do any of you think this will be ready in time for 4.2.0?  If so, please prepare a "final" patch as soon as possible.

Lachlan Andrew <lachlan>
Tue 24 May 2016 04:53:01 PM UTC, comment #10:

for me it is clear that it is a matter of making a decision,
My vote is in favor that this variable be displayed.

Fernando Pujaico Rivera <trucomanx>
Tue 24 May 2016 05:33:10 AM UTC, comment #9:

Please remember that the generate_html package is not dedicated to Octave Forge packages only.

Therefore:

1. Since the DESCRIPTION file already supports a URL field, as pointed by Carnë, I believe that generate_package_html() should display the content of this field if it is present.

2. In which case Octave Forge packages should include such an information in their DESCRIPTION, and in which case should we display it in the official index.html page, is a matter for separate discussion, I believe.  A project policy could be agreed upon, but this has nothing to do with the generate_html package (except perhaps in the choice of the options for the "octave forge" settings).

3. We might want to add a flag to hide the URL information even when it is available in DESCRIPTION. I don't know if it is really needed.

Julien Bect <jbect>
Tue 24 May 2016 01:45:34 AM UTC, comment #8:

@carnë Yes, the patch file #37068 use this,
but we were discussing whether this should be done
then, are you in favor of something like the example file #37069 ?

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

Addressing the most basic concern which is adding a url to the index file:

The DESCRIPTION file already supports a URL as a standard field. It would be simple for the generate_html package to get that information and add it to the page.

octave> [desc] = pkg ("list", "bsltl")
desc =
{
[1,1] =

scalar structure containing the fields:
[...]
url = http://www.nongnu.org/bsltl/
[...]

Oliver's reasoning about what should and should not be in the package documentation sounds good though so do consider it when making use of the URL.

Carnë Draug <carandraug>
Mon 23 May 2016 05:21:55 PM UTC, comment #6:

----------------------------------------------------------------------------------
I understand the problem with the support  of equations,
I go hold here the topic of equation because I will post a patch about this now.
----------------------------------------------------------------------------------

----------------------------------------------------------------------------------
I like your proposal to a tutorial:
(1) An overview of the package functionality,
(2) a quick start introduction for the package,
(3) examples what you can do with the package—possibly with code and images,
(4) lightweight theoretical background with references to further material that is available elsewhere.

maybe we should create a manual of generate_html package:

options = get_html_options ("octave-forge");
options.package_doc="tutorial.texi";
generate_package_html ("generate_html", "generate_html_manual", options);

Talking about of this structure and some examples
of others changes made in the package.

I would can write (slowly) this, but my English is very bad and I would need a
later review of write.
----------------------------------------------------------------------------------

----------------------------------------------------------------------------------
I think that you have reason, a link to "external information" (wiki or site)
can be in the tutorial file of each package.

----------------------------------------------------------------------------------

Fernando Pujaico Rivera <trucomanx>
Wed 18 May 2016 11:05:48 PM UTC, comment #5:

There are several topics, let me try to comment them separately.

Equations / math markup in Texinfo: This is one of the topics where there is large difference between PDF and non-PDF output formats in Texinfo. The @math macro can typeset math in PDF, but does nothing in HTML, so you end up with more or less cryptic LaTeX code in the online documentation. In the end it is easier to just use @tex formatters and duplicate the formula in ASCII art for other output formats (which is done in the Octave core manual). Personally, I don't like to duplicate the formulas and prefer to enter simple math with Unicode glyphs. In turn, Unicode glyphs don't work well with PDF output unless you define them with \DeclareUnicodeCharacter. The \DeclareUnicodeCharacter macro will introduce further problems with different Texinfo versions, see bug #46083.

Typesetting math with MathJax: I guess it is fairly easy to define a Texinfo macro that will produce a math environment in PDF output and some MathJax processable node in HTML output. However, my personal experience with MathJax is that the browser rendering is not optimal (e. g. when I look at the Feynman Lectures in my Iceweasel browser, the font rendering looks different in math mode). Thus, I still prefer Unicode glyphs. However, I'd love to see better math support in browsers.

What goes in the package documentation: I agree that you can't (and shouldn't) put tutorial videos and heavy theoretical background into an Octave package documentation. This certainly is the wrong place. However, there is a lot of stuff that you could put in the Texinfo documentation, especially when it is tightly related with the particular package. (1) An overview of the package functionality, (2) a quick start introduction for the package, (3) examples what you can do with the package—possibly with code and images, (4) lightweight theoretical background with references to further material that is available elsewhere (articles, streaming videos from Mediagoblin, …). See http://octave.sourceforge.net/interval/package_doc/index.html for what I mean. I believe that this is far more useful than a plain link to an external site with a general description of a particular topic which is not necessarily related to the Octave package.

Separate release of package and documentation: If you want to separate package-x.y.z.tar.gz and package-doc-x.y.z.tar.gz this is a good sign that either your documentation is not tightly related to the Octave package, or that the documentation is under heavy construction at the moment and you want to release it in a different frequency. In the latter case it might be a good idea to create the documentation in a Wiki (e. g. wiki.octave.org) and, later, transfer it into the Texinfo manual which can be released together with software changes as part of the package.

Heavy packages because of documentation: There are some tricks to keep the size share of documentation small. For example, you don't have to ship documentation images as part of your package release, if the images can be generated using Octave (and your package). For example, in the interval package there is a doc/Makefile which generates lots of Octave plots for the manual and the images are not part of the original release package. The images are generated from short m-file scripts. In some cases the m-file scripts are written in Texinfo, so they can be included as code examples in the manual without duplication. Not shipping a generated documentation is not a problem, if the user can generate it easily (e. g. using a doc/Makefile). Also, we have a published HTML version on Octave Forge, and some redistributors (e. g. Debian) will package binaries that contain a generated documentation.

Oliver Heimlich <oheim>
Wed 04 May 2016 06:53:21 PM UTC, comment #4:

I am attaching a example of standalone off-line reference manual (bsltl_refman.tar.gz) with package documentation (overview.texi), showing my problem with the equations. To see overview.texi please go to https://sourceforge.net/p/octave/bsltl/ci/master/tree/doc/overview.texi

Fernando Pujaico Rivera <trucomanx>
Wed 04 May 2016 06:12:04 PM UTC, comment #3:

options = get_html_options ('octave-forge');
options.package_doc = 'tutorial.texi'; # or whatever it is called
generate_package_html ('$(PACKAGE)', '$(HTML_DIR)', options)

is that the texinfo syntax not interpret latex equations in html output format.

Show equations is very important for a project as  Octave.
By example, I can't use texinfo for generate the html tutorial of my package.

(PS: I am thinking about the latex equation support to html manuals, but I will post this in another patch thread.)

Fernando Pujaico Rivera <trucomanx>
Wed 04 May 2016 04:03:09 PM UTC, comment #2:

I do not think it's a good practice expect that all documentation is joined to source code.

I think that in the "doc/" directory  of octave package, should have a method to generate the reference manual (offline standalone), and a mini tutorial (manual.texi) with a bit of theory,
As the example that you say:

options = get_html_options ('octave-forge');
options.package_doc = 'manual.texi'; # or whatever it is called
generate_package_html ('$(PACKAGE)', '$(HTML_DIR)', options)

(Thanks by the info, now I will make one.)

given that a complete tutorial, need many figures, examples  and a big theorical explication. Packages with a big theorical charge. Package as bim, fem-fenics, fuzzy-logic-toolkit, bsltl,tsa.
merge all them with the source code could generate packages very heavy, being that only a little percentage of this weigth will be to the source code.
Maybe the packages should be separate in

packagename-1.0.0.tar.gz
packagename-doc-1.0.x.tar.gz

so that the "doc/" directory in packagename-1.0.0.tar.gz have a method to generate a off-line standalone reference manual and mini tutorial.

And in packagename-doc-1.0.x.tar.gz should have

• A generated (off-line standalone) version of reference manual
• A generated (off-line standalone) version of mini tutorial.
• A complete manual including theory.

Thus will be more difficult that a package turn on unmaintained, given that other people with the adequate formation can modify and refresh the source code.

I understand that octave-forge not should be a index page. But a link to the official home page of package should be necesary, given that there could be more information as: videos, examples, tutorial, book, articles  and/or  theory itself relative to package.

Maybe my original idea should be modify to a more discreet link, that no distract the attention of reference manual.

I am attaching a new diff file (Adding-additional-information.diff) and a example of reference manual (bsltl_html.tar.gz).

Fernando Pujaico Rivera <trucomanx>
Sun 01 May 2016 01:38:53 PM UTC, comment #1:

There is going to be a strategic decision regarding this change.

Currently, Octave Forge is used as both, a place to develop packages and a repository of these packages. The best-practice to add such information is to put it in a “package documentation” and publish it on Octave Forge.

See the following packages for examples: database, interval, optim, and parallel. Unfortunately many packages miss such a documentation at the moment.

To use this feature, you write a manual (in TexInfo format) and distribute it in your package in a sub folder called “doc” (next to “inst”). The doc folder is copied over during package installation.

For publication on Octave Forge you can also create the documentation as follows:

options = get_html_options ('octave-forge');
options.package_doc = 'manual.texi'; # or whatever it is called
generate_package_html ('$(PACKAGE)', '$(HTML_DIR)', options)

This approach also works well with explaining the use of a package (with code examples), since you may check the correctness of code examples using the doctest package.

Now, let's go back to your idea of pointing to external documentation. You can do this very well in a manual (as described above). However, if the primary source of documentation for a package is hosted elsewhere, i. e. , not at Octave Forge, this is a step towards making Octave Forge a repository of externally hosted packages. Something like https://metacpan.org/ as Carnë pointed out earlier. And, as soon as we start going in that direction, placing a single link won't help much and will not be enough.

Oliver Heimlich <oheim>
Sun 01 May 2016 11:17:28 AM UTC, original submission:

I would like suggest that, in the index.html file of reference manual be show a field with a url to a site with more documentation. By example: books, tutorials for each function, or a better explication of library with examples.

This url should be the site specified in the description file of package.

I consider this very important to projects with packages with a complex theorical explication, that need show a bit of theory and some code examples to explain better the use of packages.

Attachment I am sending the patch

Fernando Pujaico Rivera <trucomanx>

## Attached Files

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

Attach Files:

Comment:

Attached Files
file #37070:  bsltl_refman.tar.gz added by trucomanx (56KiB - application/gzip - documentation offline standalone)

## Dependencies

Depends on the following items: None found

Items that depend on this one: None found

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

Do you think this task is very important?
This task has 0 encouragements so far.

Only logged-in users can vote.

## History

Date Changed by Updated Field Previous Value => Replaced by
2016-07-14 lachlan StatusIn Progress Done
Open/ClosedOpen Closed