cross manual references in html manuals

[Dumas Patrice]

Hi,

Some proposals about cross manual references in html manuals. I tried to make
it precise and formal, because I thing it is easier to discuss about formal
things, but this are only proposals.

First of all I think that the issue of cross manual references should be 
explicitely and as exhaustively as possible stated somewhere as it is 
something which should be needed for software outside of the texinfo 
package. For example manuals in other formats should want to reference 
info manuals and other formatters than makeinfo (texi2html...) should 
be able to produce manuals with similar cross links.

Here we go:

link are basically constructed using the pair (node name, manual).
A link consists in 3 components, an host name, a directories part and a 
file name. The file name is constructed using the node name. The host and 
directories are constructed using the manual name. Of course the host,
directories and file are to be used to construct an url.

I first describe how to map the (node name, manual) to these 3 components
in the general case, and then fill the gaps in the case of the software
generating the cross reference (ie the software which tries to refer to
another manual) and the software generating the target.

construction of file name from node name
----------------------------------------
When no node name is given no file is used (or index.html is assumed).
When the node name is any case combination of 'Top' no file (or
index.html) is used.

expansion of @ commands
=======================

If the node name contains a @value or a user defined macro (defined with 
@macro), they are expanded. Comments are also removed. @if* commands
are also supposed to be allready expanded.

The following @ commands are not allowed (ie the resulting file name is 
unspecified):

@math, @menu, @afourlatex , @afourpaper, @afourwide, @alias, @anchor, 
@node, sectionning commands (@headings, @section, @appendix......), @bye,
@center, @centerchap, @?index, @printindex, @*table, @columnfractions,
@contents, @shortcontents, @summarycontents, @cropmarks, @defindex, 
@defcodeindexn, all the @deffn like commands, @example and the like,
@enumerate, @itemize, @definfoenclose, @dircategory, @direntry,
@document*, @titlepage, @exampleindent, @*footing, @*heading, @flush*,
@footnotestyle, @group, @include, @item, @itemx, @kbdinputstyle, @raisesections
@lowersections, @macro, @*headings, @math, @need, @pagesizes,
@settitle, @setfilename, @author, @cartouche, @set*contentsaftertitlepage,
@*titlepage, @this*, @title, @titlefont, @unmacro, @rmacro, @vskip,
@verbatiminclude, @copying, @insertcopying, @paragraphindent   
and corresponding @end command.

It also seems to me that @verbatim, @verb, @tex and @html should not be 
allowed too, but I am not certain about these, however (especially @verb 
and @html).

accented letters are transformed into their info equivalent (see 
(texinfo)Inserting Accents).

the following @ commands are transformed into text. I write the command, and 
then what it should be transformed too. 'NOTHING' has a special meaning, it 
means that the comand is removed. An 'OR' means that I am not certain which one
is the good one. If the command has braces and there is something in the 
braces, the text in the braces is transformed, and then the substituted command
name is followed by a space and the transformed text. For example 
'@bullet{a text}' leads to '* a text'. 'SPACE' means a space.

@(space) SPACE
@(tab) SPACE
@(newline) SPACE
@! !
@? ?
@. .
@: NOTHING
@@ @
@{ {
@} }
@* SPACE
@tie SPACE
@- NOTHING
@exclamdown !
@questiondown ?
@copyright (C)
@dots ...
@enddots ....
@equiv equiv OR ==
@point point OR -!-
@result result OR =>
@expansion expansion OR ==>
@print print OR -|
@error error OR error-->
@exdent NOTHING
@noindent NOTHING
@minus -
@pounds pounds 
@page NOTHING
@refill NOTHING
@bullet *
@TeX TeX
@today today

For the following @ commands, the @ command and braces are removed and 
replaced with the text within argument which is transformed:

@dotless, @acronym, @asis, @b, @command, @cite, @code, @dfn, @dmn, @emph,
@env, @file, @kbd, @key, @samp, @sc, @strong, @t, @var, @url, @w

For @sc letters are capitalized.

@email is replaced by the text, and if not present the mail adress.
@uref is replaced by the third arg, or the second if not present or the first
@image is replaced by the first arg
@footnote and its argument are removed
@sp and the number following it are removed
@*ref is replaced by the first argument (the node name)

construction of file name
=========================

@ commands are expanded as explained above.

multiple spaces and tabs are transformed into just one space.

letters, numbers, '-', '_' are not modified.

All the characters other than [A-Za-z0-9_-] are transformed into '-'.

'.html' is appended to the resulting file name.

With this scheme it may happen that a file name is associated with 2 different
node names.

construction of host and directories from manual name
-----------------------------------------------------

The manual name should only contain the following characters:
[A-Za-z0-9-_/], / having a special meaning.
If the manual name is absolute, then it is assumed to be a local file.
Otherwise, the manual name is assumed to be a trailing directory component
of the path relative to a given base directory on a given host. This 
base directory and this host cannot be further deduced from the manual
name in the general case.

generation of cross reference
-----------------------------

Given a node name and a manual name what remains to be found is the 
base directory and host name. I think that a recommendation could be done,
to follow a file mapping a manual to an host/directory as Karl said. The
location, name and format of this file should be specified as precisely as
possible such that different application can share the same file.
Otherwise the default host/directory could be ../ (ie parent dir on the
localhost) as makeinfo allready does. Of course, the software may override
this default and also what is specified in the file.

generation of targets
---------------------

The software generating the manual target of the cross reference should 
generate a file per node and anchor with name as explained above and 
put the files in a directory. Each file should contain that node or 
redirect to another file (or url) containing that node.

For the directory name, it is recommended to use the file name given 
in setfilename without .info as directory name, but the software may override 
this. That's because the manual name will be mapped to that directory name 
by software generating cross references.

In the case of multiple nodes with the same file name, the software should 
warn the user, and it is only required that the file leads to one of 
these nodes. Thus some nodes may not be attainable.




To end I will try to explain how this differs from what makeinfo currently 
does (4.5). The main difference is for translation of node names into file 
names in case there are some @ commmands in the node name. In that case 
makeinfo translate it into html before doing the removing of special 
characters, and '.' is left as is. I think '.' should also be considered 
special, and also the file names should not be related to html, as it 
implies that other software (and different versions of makeinfo) can produce 
the same html. 

Also this proposal permits some things in node names which breaks makeinfo
(for example @,{c} which is in my opinion licit, and others, less needed
like @page, and some more).

Pat