The texinfo format provides 3 commands @ref, @xref and @pxref to make cross
references to existing @nodes in the document; it also provides a command
@anchor to place arbitrary targets for cross-reference.
Because these will be handy for the Installation Manual that already does
some references, this patch implements the 4 commands:
- change the '@node' command, that did nothing, to now track potential
reference points;
- add the '@anchor' command to register a new target for x-ref;
- implement the 3 '@*ref' commands with similar behaviour as the texinfo
format states, with support for all arguments, generating a temporary
"@x##@" pattern for the line target;
- generate a new file (*.xrf, a sed script) at the end with the
replacement for x-ref patterns with the correct line number, and perform
a few consistency checks;
- during the final search-and-replace used to insert the Table of Content,
include the x-ref replacement.
The current script has some limitations:
- because we cannot know in advance the target line number for the x-ref,
we insert it with a constant size of 5 characters to avoid breaking the
justification alignment when doing the replace;
- there is a strict order to respect between @node and @chapter/@section,
which is needed because we have to include a line offset to get it right
when using the order given in the texinfo manual.
Signed-off-by: Christophe CURIS <christophe.curis@free.fr>
The texinfo format provides a command '@table' which is useful to provide
a list of object (function, variables, options, ...) with their associated
description.
As this will be very handy for the Installation Manual, this patch
implements the command in the script.
Signed-off-by: Christophe CURIS <christophe.curis@free.fr>
The texinfo format provides a command to generate list of item which are
prefixed by an auto-incremented number or letter.
This command was not implemented but as it will be used by the Installation
Manual of Window Maker, this patch implements it, reusing much of the code
that was handling the unordered lists.
Signed-off-by: Christophe CURIS <christophe.curis@free.fr>
There are some cases where it can be useful to embed a list of item into
another list; the script was almost ready to handle this case, this patch
brings the missing stuff to get it to work properly.
Signed-off-by: Christophe CURIS <christophe.curis@free.fr>
This 'switch' control statement is actually a GNU extension, so it is not
portable to other awk implementations.
This patch replace them with the traditional 'if...else' sequence which
will work everywhere.
Signed-off-by: Christophe CURIS <christophe.curis@free.fr>
As reported by Doug Torrance, the 3rd argument to the 'match' function is
actually a GNU extension, so it breaks compatibility when run with another
version of awk, for instance mawk.
This script changes the code to stuck to the 2 arguments version which is
posix.
Signed-off-by: Christophe CURIS <christophe.curis@free.fr>
The support for variables in the text-from-texi script is used to
automatically insert the current version of Window Maker, inherited from
the definition in the AC_INIT command, so it will be always correctly
updated without the need for hand work.
Having this version information is recommended by GNU texinfo because if
the document happens to get distributed outside a package it can help user
avoid problems.
The second use is to define a variable 'emailsupport' which contains the
email address of the development team, so we can also inherit it from the
AC_INIT setting.
The third use is for a special variable 'cctexi2txt' to differentiate
between texi2any and our script, because when using texi2any the title
page is not generated, so we need to duplicate some information in the
source, but we do not want it to appear twice in our generated doc.
Signed-off-by: Christophe CURIS <christophe.curis@free.fr>
The source of the documentation is in Texinfo format to have the
possibility someday to distribute in more format that just plain text;
There is a new Makefile to generate automatically the plain text file to be
distributed from the source; this doc is also generated by 'autogen.sh'
because a user would expect to find it before compiling the program, so
even before the 'configure' script have been generated, in the case he is
compiling from a git checkout;
There is a new script to generate the documentation, because from the way
we generate it we cannot assume that 'texi2any' is available and working
on the user's computer; it is also the opportunity to generate a better
looking document (see the description at the beginning of the script);
In this commit, the documentation only contains the base skeleton, it does
not contain yet any useful content because it is worth it's own commit.
Signed-off-by: Christophe CURIS <christophe.curis@free.fr>
