doc/info/README

   1 Guidelines
   2 ==========
   3
   4 There currently are no formal rules for adding documentation.
   5
   6 There are some guidelines, though:
   7  * separate exposition and examples
   8  * examples recapitulate exposition
   9  * order exposition by decreasing importance
  10  * be precise, be complete, get to the point
  11
  12
  13 How to test the documentation?
  14 ==============================
  15
  16 In order to test if the new document works the following steps
  17 have proven helpful:
  18
  19 - Do the TeXinfo and HTML documentations build without producing new warning
  20   or error messages? Both will be created after typing the following command:
  21
  22   make
  23
  24 - Does the pdf documentation build? This type of documentation can be created
  25   by typing
  26
  27   make pdf
  28
  29   The japanese documentation (enabled with --enable-lang-ja) can not be build
  30   with the usual TeX engine use
  31   make pdf PDFTEX=xetex
  32   to select xetex for building it.
  33
  34
  35 - Do all of the documentation types look like they should
  36
  37 - Is the documentation accessible to the ? and ?? commands of maxima?
  38
  39 Documentation interna
  40 =====================
  41
  42 The central file the documentation is generated from
  43 include-maxima.texi.in
  44
  45 All maxima-specific extensions to texinfo that aren't contained in mmref.tex
  46 (which makes hyperlinks in the pdf output work, but for some reason would cause
  47 the html output to begin in a literal "\input texinfo" can be found in
  48 category-macros.texi
  49
  50 Other possibly important details (in random order)
  51 include-maxima.texi is included by maxima.texi or (if the pdf manual is generated
  52 using "make pdf" by maxima_pdf.texi) and texinfo.tex: The logic that allows pdfTeX
  53 to interpret .texi files.
  54 The newest version of texinfo.tex is always available at
  55 https://ftp.gnu.org/gnu/texinfo/texinfo.tex - and it probably makes sense
  56 to update the "texinfo.tex" files shipped with maxima from time to time.
  57
  58 The files header.hhp, maxima.hhp (and the generated files contents.hhc and index.hhk)
  59 are for the generation of Microsoft HTML Help (Option --enable-chm).
  60
  61
  62
  63 TO DO
  64 =====
  65
  66 Duplicate nodes
  67 ---------------
  68
  69 Compiling the manual generates tons of warnings about doubly-defined nodes.
  70 Most of them originate from the fact that some functions have the same name
  71 as variables and that @deffn or @defvr both generate nodes named like the
  72 function or veriable they document.
  73
  74 - Is there a way to get around this? And if there is a way to do so:
  75 - Is there a way to avoid conflicts if two packages in share/ use the same
  76   function names?
  77
  78
  79 PDF Hyperlinks
  80 --------------
  81
  82 Is there any way to avoid needing a separate input file for PDF generation?
  83 There has to be a way to make the "\input mmref" conditional without breaking
  84 things.
  85
  86 Documented TODOs
  87 ----------------
  88
  89 The .texi sources of the manual contain many comments that show excellent
  90 starting points on where to start when wanting to improve the manual.