Manual for GNU Octave package (Octave-Forge)

[Oliver Heimlich]

I have recentently started to learn GNU Texinfo and, for example, create 
the NEWS file for my Octave Forge package from Texinfo sources, which 
saves me from the dull work of aligning plaintext paragraphs/list by hand.

Now I want to start a user manual for my package.

At first I worked on a manual page in the wiki, which was very 
beneficial in the early days of the package. I could publish 
documentation and package releases independently. It sped up 
development, because I could work on the software and its documentation 
asynchronously.

The wiki documentation is no longer an advantage and I want the package 
release to contain a matching documentation (for many different reasons) 
from now on. I started a doc/manual.texinfo file, which is naturally 
also going to be in the release tarball. However, the “pkg install” will 
probably drop it and the user is never going to see the manual. How 
should I release the manual?

1. Should I generate a HTML version of the package manual and include it 
in the [package]-html.tar.gz for publication on Octave Forge? I could 
use the HTML template from the generate_html package to get a matching 
design. I could patch the package's index.html to contain a link to the 
manual next to the function reference.

2. Should I bundle any compiled version of the manual in the package 
release tarball? Or should I leave this to downstream distributors? Are 
there any conventions, which downstream distributors expect?

3. Can you recommend any graphical editors for Texinfo files? I am 
looking for something similar to LyX. Probably it does not exists, 
because everybody uses Emacs.

Oliver