Re: generate_html: new characteristic - Adding field (additional documentation:url) to index.html of the online package documentation

[TrucomanX XnamocurT]

Hi Olaf

2016-05-14 5:09 GMT-03:00 Olaf Till <address@hidden>:

Hi Fernando,

FYI, some packages (to my knowledge 'interval', 'optim', 'parallel',
'database') solve this problem differently -- by _including_ such
additional information into the package documentation in Octave
Forge. The link is named "Package Documentation" and is between the
links "Function Reference" and "NEWS".

This _including_ of this information, together with the practice of
generating it from a texinfo source, has the advantage that an
interface can be provided to access the equivalent information from
within Octave.

If an additional link to a third party server is provided, it probably
should be named "External Documentation". It may be worth discussing
if such a link should be provided or not. My personal opinion is that
if the documentation belongs to the package, it should be provided
with the package, not by an external link.

Olaf

--
public key id EAFE0591, e.g. on x-hkp://pool.sks-keyservers.net

I have tried make my documentation using texinfo using the characteristic that you say me, but the problem is that it not support the display of equations.

Then, I don't like the idea of to use texinfo to document my package.
By other side,
I have problems of  think that all the documentation is attached with the source code, because it can turn in packages very heavy;
being that the source code use only small percentage of weight. (To packages with many figures and theory, in your documentation)

I think the octave packages only should have  the reference manual (generated  automatically from source) and a mini tutorial (generated  using texinfo).

Thus, we would have two tar.gz:
packagename-1.0.0.tar.gz
packagename-doc-1.0.0.tar.gz

So that, packagename-doc-1.0.0.tar.gz has a off-line standalone version of documentation in packagename-1.0.0.tar.gz besides a lot of additional material.

Because of all this, I  would like suggest that the reference manual (website) of each package should have a link to "external documentation", where I can post, a manual wrote in latex, post video-tutorials, links to papers,  Examples of use, etc.

Fernando