cross references in html, next

[Dumas Patrice]

Hi,

Next proposal for cross references in html manuals.

Links are basically constructed using the pair (node name, manual).
A link consists in 4 components, an host name, a directories part, a 
file name and a target part. The file is simply 'index.html'. The 
target is constructed using the node name. The host and directories 
are constructed using the manual name. Of course the host, directories, 
file and target are to be used to construct an url 
(like http://host/directories/index.html#target).

I first describe how to map the (node name, manual) to the 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.

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.

@ commands in node names are not supported in makeinfo or texi2dvi, thus
it is adviced not to use them. However as they are not ruled out by design
of texinfo and as Karl said that maybe one day it will be supported, they
are included in this proposal for sake of completness.

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, @tex, @html, @verbatim, @today
and corresponding @end command.

Accented letters are transformed into their utf-8 equivalent character,

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 command is removed. 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
@* SPACE
@! !
@? ?
@. .
@: NOTHING
@tie SPACE
@equiv corresponding utf-8 character
@point -!-
@result =>
@expansion ==>
@print print -|
@error error-->
@exdent NOTHING
@noindent NOTHING
@page NOTHING
@refill NOTHING
@bullet *
@TeX TeX
@minus -
@copyright (C)
@dots ...
@enddots ....
@exclamdown utf-8 character 
@questiondown utf-8 character
@pounds pounds utf-8 character
@@ @
@{ {
@} }
@- NOTHING

For the following @ commands, the @ command and braces are removed and 
replaced with the text within argument which is recursively 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.
@verb is processed as usual and replaced by the corresponding text.

The following @ commands shouldn't appear in node names, but, still for 
completness, they are considered:

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

node name expansion
-------------------

multiple spaces and tabs are transformed into just one space.

letters, numbers, and '-' ([A-Za-z0-9-]) are not modified.
ascii 7 bit characters are transformed into _xx where xx is the ascii
character in hexadecimal. '_' is itself mapped to _5f.
Other characters are transformed into _xxxx where xxxx is the utf-8
code of the character in hexadecimal.
The letters in hexadecimal should be in lower case.

target generation
-----------------

The target name is simply the expanded node name. The reason why only
[A-Za-z0-9-_] appear in expanded node names is that the targets are
in <a name=> or in id= attributes, and only those characters are allowed
in xhtml. It is possible to have 2 different nodes expanding to
the same target name, if there are @ commands in node name (for example
@code{node} and @dfn{node} both leads to node).

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

The manual name should only contain the following characters:
[A-Za-z0-9-_/.], / and . 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 reference targets
-------------------------------

The software generating the manual target should generate a file named
index.html. It also should process all node and anchor names such that
all the url leading to index.html#target with 'target' a node or anchor 
name expanded as explained above are redirected to the url containing
that node or anchor.

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

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.

Pat

For those interested, here is a trick using javascript which can be used
to redirect many target to the right files (here it could be usefull for
the index.html file).

Here is the javascript:
function redirect() {
        switch (location.hash) {
                case "#node1" : 
                        location.replace("doc_NOD1.html#NOD1"); break;
                case "#node2" : 
                        location.replace("doc_NOD2.html#some_target"); break;
                default:;
        }
}

And here is the <body> in document:
<body onLoad="redirect();">