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


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 interna
=====================

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).



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.
