Guidelines
==========

There currently are no formal rules for adding documentation.

There are some guidelines, though:
 * separate exposition and examples
 * examples recapitulate exposition
 * order exposition by decreasing importance
 * be precise, be complete, get to the point

Defining functions
------------------
When defining a single functions use `deffn`.  When defining related
functions, but with different names, use `deffn` and `deffnx`.  For
example, `bfpsi` and `bfpsi0` are closely related functions that are
described together in the same text.  This uses `deffn` and `deffnx`:
```
@deffn  {Function} bfpsi (@var{n}, @var{z}, @var{fpprec})
@deffnx {Function} bfpsi0 (@var{z}, @var{fpprec})
```

However, for the function `array`, there are three related functions
of the same name but with different arguments.  In this case, use
`deffn` and `@fname` to define these functions:
```
@deffn  {Function} array @
@fname{array} (@var{name}, @var{dim_1}, @dots{}, @var{dim_n}) @
@fname{array} (@var{name}, @var{type}, @var{dim_1}, @dots{}, @var{dim_n}) @
@fname{array} ([@var{name_1}, @dots{}, @var{name_m}], @var{dim_1}, @dots{}, @var{dim_n})
```

Defining functions this way is very helpful when the user asks for
help.  If `deffnx` were used to define the different forms of the
`array` function, `? array` would say there are three functions and
the user would need to select one (or all) without knowing how they
differ.  But using `@fname`, there's only one function and the help is
imediately displayed.

How to test the documentation?
==============================

In order to test if the new document works the following steps
have proven helpful:

- Do the TeXinfo and HTML documentations build without producing new warning
  or error messages? Both will be created after typing the following command:

  make

- Does the pdf documentation build? This type of documentation can be created
  by typing

  make pdf

  The japanese documentation (enabled with --enable-lang-ja) can not be build
  with the usual TeX engine use
  make pdf PDFTEX=xetex
  to select xetex for building it.


- Do all of the documentation types look like they should?

- Is the documentation accessible to the ? and ?? commands of maxima?

Documentation internals
=======================

The central file the documentation is generated from
include-maxima.texi.in

All maxima-specific extensions to texinfo that aren't contained in mmref.tex
(which makes hyperlinks in the pdf output work, but for some reason would cause
the html output to begin in a literal "\input texinfo" can be found in
category-macros.texi

Other possibly important details (in random order)
include-maxima.texi is included by maxima.texi or (if the pdf manual is generated
using "make pdf" by maxima_pdf.texi) and texinfo.tex: The logic that allows pdfTeX
to interpret .texi files.
The newest version of texinfo.tex is always available at
https://ftp.gnu.org/gnu/texinfo/texinfo.tex - and it probably makes sense
to update the "texinfo.tex" files shipped with maxima from time to time.

The files header.hhp, maxima.hhp (and the generated files contents.hhc and index.hhk)
are for the generation of Microsoft HTML Help (Option --enable-chm).

The file `texi2html.init` (generated from `texi2html.init.in`)
contains customizations for `makeinfo` when generating the HTML
version of the user manual.  This includes things like loading MathJax
(for nice display of formulas) and syntax highlighting for the
examples.

TO DO
=====

Duplicate nodes
---------------

Compiling the manual generates tons of warnings about doubly-defined nodes.
Most of them originate from the fact that some functions have the same name
as variables and that @deffn or @defvr both generate nodes named like the
function or veriable they document.

- Is there a way to get around this? And if there is a way to do so:
- Is there a way to avoid conflicts if two packages in share/ use the same
  function names?


PDF Hyperlinks
--------------

Is there any way to avoid needing a separate input file for PDF generation?
There has to be a way to make the "\input mmref" conditional without breaking
things.

Documented TODOs
----------------

The .texi sources of the manual contain many comments that show excellent
starting points on where to start when wanting to improve the manual.

