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

[Oliver Heimlich]

Follow-up Comment #5, patch #8990 (project octave):

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.

    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/patch/?8990>

_______________________________________________
  Nachricht gesendet von/durch Savannah
  http://savannah.gnu.org/