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

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


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.
