12.3.1 Invoking gendocs.sh

The script gendocs.sh eases the task of generating the Texinfo documentation output for your web pages section above. It has a companion template file, used as the basis for the HTML index pages. Both are available from the Texinfo CVS sources:

http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh
http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template

There is also a minimalistic template, available from:

http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template_min

Invoke the script like this, in the directory containing the Texinfo source:

gendocs.sh --email yourbuglist yourmanual "GNU yourmanual manual"

where yourmanual is the short name for your package and yourbuglist is the email address for bug reports (which should be bug-package@gnu.org). The script processes the file ‘yourmanual.texinfo’ (or ‘.texi’ or ‘.txi’). For example:

cd .../texinfo/doc
# download gendocs.sh and gendocs_template
gendocs.sh --email bug-texinfo@gnu.org texinfo "GNU Texinfo manual"

gendocs.sh creates a subdirectory ‘manual/’ containing the manual generated in all the standard output formats: Info, HTML, DVI, and so on, as well as the Texinfo source. You then need to move all those files, retaining the subdirectories, into the web pages for your package.

You can specify the option ‘-o outdir’ to override the name ‘manual’. Any previous contents of outdir will be deleted.

The second argument, with the description, is included as part of the HTML <title> of the overall ‘manual/index.html’ file. It should include the name of the package being documented, as shown. ‘manual/index.html’ is created by substitution from the file ‘gendocs_template’. (Feel free to modify the generic template for your own purposes.)

If you have several manuals, you’ll need to run this script several times with different arguments, specifying a different output directory with ‘-o’ each time, and moving all the output to your web page. Then write (by hand) an overall index.html with links to them all. For example:

cd .../texinfo/doc
gendocs.sh --email bug-texinfo@gnu.org -o texinfo texinfo "GNU Texinfo manual"
gendocs.sh --email bug-texinfo@gnu.org -o info info "GNU Info manual"
gendocs.sh --email bug-texinfo@gnu.org -o info-stnd info-stnd "GNU info-stnd manual"

By default, the script uses makeinfo for generating HTML output. If you prefer to use texi2html, use the ‘--texi2html’ command line option, e.g.:

gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual"

The template files will automatically produce entries for additional HTML output generated by texi2html (i.e., split by sections and chapters).

You can set the environment variables MAKEINFO, TEXI2DVI, TEXI2HTML and DVIPS to control the programs that get executed, and GENDOCS_TEMPLATE_DIR to control where the ‘gendocs_template’ file is found.

As usual, run ‘gendocs.sh --help’ for a description of all the options, environment variables, and more information.

Please email bug reports, enhancement requests, or other correspondence to bug-texinfo@gnu.org.