html cross refs proposal
Dumas Patrice <[email protected]> Fri, 30 Jan 2004 14:31:37 +0100
| Newsgroups | gmane.comp.tex.texinfo.pretest |
|---|---|
| Message-ID | <[email protected]> |
Hi,
I can't see any issue with that proposal. As far as I am concerned I find
it acceptable. You might disagree :). I also don't see any problem with
using it for internal refs too. The only problem I see is that my writing
is a bit pedantic...
Introduction
------------
We try to support references to external manuals in monolithic form
and split. A monolithic manual has all the nodes within, and a split
manual has a file for each node.
Links are basically constructed using the pair (node name, manual
description) found in the texinfo code itself.
There are also informations needed which aren't in the manual code.
These informations are called here external information. This external
information is found in a file in a format we'll explain later.
There are defaults proposed, in case this external information isn't present.
A link consists in 4 components, an host name, a directories part, a
file name and a target part. The target is constructed using the node
name. The file name is constructed using the node name in the split case.
In the mono case the host, directory and file are constructed using the
external information. In the split case the the host and directory are
constructed using the external information.
If the external information isn't found, in the mono case the file name is
found using the manual name, and in the split case the directory
is partly found using the manual name.
The host, directories, file and target are to be used to construct an url
like http://host/directories/index.html#target.
I describe how to map the (node name, manual description, external info)
to the components as well as how the external information is found. We
consider that there is a software generating the cross reference (ie the
software which tries to refer to another manual) and the software generating
the target of cross reference manuals. Beware that target is also used for
the target part of an href, that is thee part after #.
Expansion of node name
----------------------
First @-commands are expanded. Non 7 bit characters are also expanded.
These expansions are explained at the end of this specification as
@-commands and non 7 bit characters are exceptions in node names.
multiple spaces, tabs and newlines are transformed into just one space
(there shouldn't be any newline, but who knows).
Leading and trailing spaces are removed.
letters and numbers, and ([A-Za-z0-9]) are not modified.
spaces are converted into '-'.
ascii 7 bit characters are transformed into _00xx where xx is the ascii
character in hexadecimal. '_' is itself mapped to _005f.
The letters in hexadecimal should be in lower case.
For example
@node A node --- with _'%
leads to
A-node-_002d_002d_002d-with-_005f_0027_0025
Notice
_ -> _005f
- -> _002d
A node -> A-node
manual name expansion
---------------------
The manual description should only contain the following characters:
[A-Za-z0-9-_/.], / and . having a special meaning. It is interpreted as
a file name. The last element of the file with extension stripped is the
manual name.
target construction
-------------------
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.
file name construction
----------------------
If the reference is split the file name is the expanded node name with
`.html' appended. There is an exception for the Top node which is mapped to
`index.html'.
external information
--------------------
The information for the reference is searched in the files present in the
following directories:
<srcdir>/.texinfo_manuals/, ~/.texinfo_manuals/, SYSCONFDIR/texinfo_manuals/,
DATADIR/texinfo/texinfo_manuals/
The first match should be used.
The name for the files can be anything.
The file is line-oriented, with the following format:
<manualname> <whitespace> <keyword> <whitespace> <urlprefix>
with <keyword> being "mono" or "split". Thus
texinfo split http://www.gnu.org/software/texinfo/manual/texinfo/html_node/
texinfo mono http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html
If the keyword is 'split', that is the target is split, the urlprefix gives
the directory and host name.
If the keyword is 'mono', that is the target is mono, the urlprefix gives
directory, host and file name.
'#' followed by a space begins comments. '#' followed by another character
cannot begin comments as there are # in urls.
The packagers could put a file with a sensible value when packaging software.
This value could be a link to the local host if the html manual is installed
on the local host, or a link to a host on internet if the manual is there.
default directory, file name and host for cross reference generation
--------------------------------------------------------------------
If a line corresponding with the manual is found in a file located in the
directories described above, everything is ready to do the cross reference.
If both split and mono manuals are present the software may chose whatever it
wants. Maybe choosing the same style than the manual being generated makes
more sense. Of course the software may override this and chose anything else.
If there is no external information about a cross reference the defaults are
to be chosen. The software may chose anything for the style (mono or split),
for the host and directory, and for the file name in case the manual is mono.
We nevertheless specify here some sensible defaults.
The style used is the style of the generated manual.
The host is the local host.
If the manual is split and the cross reference is a reference to a split
manual the directory is `../' with the manual name appended. If the reference
is a reference to a mono manual the directory is `../' and the file name
is the manual name with `.html' appended.
If the manual is mono and the cross reference is a reference to a split
manual the directory is the manual name. If the reference is a reference
to a mono manual the directory is the local directory and the file name
is the manual name with `.html' appended.
generation of reference targets
-------------------------------
There are two possibilities for manuals, split and mono.
If you prefer a split manual a file for each node with name described above
and targets as described above should be generated within these files.
And all the url leading to node-name.html#node-name should lead to the
corresponding node, with index.html as the file for the Top node.
For each anchor, a file should also be generated with the same convention
for name and targets, and when the file is reached, it should redirect to
the real file containing the anchor.
It is recommended to put these files in a directory with name the manual name,
because the manual name will be mapped to that directory name in the default
case. The software may override this.
If you prefer a mono manual the targets are as explained above and the file
name is, by convention, the manual name with `.html' appended. Still this
may be overrided.
It is possible to prevent against things going bad in case the reference is
not compatible with the target. There are two possibilities:
1. Reference is mono but target is split.
In that case a javascript trick may be used to redirect to the right file.
It is given in appendix.
2. Reference is split but the target is mono.
In that case it is possible to generate a file per node as explained above,
redirecting to the monolithic manual.
The whole picture
-----------------
To summarize, we have (reference to the node foo in manual manual):
mono ref: manual.html#foo
split ref: manual/foo.html#foo
If the reference and the target are compatible we simply have
mono ref / mono target -> target in manual.html
split ref / split target -> target in manual/foo.html
Now if the reference is not the same than the target, it may fail, but it
is still possible to have the right thing happening, as explained above:
mono ref / split target -> fail or js in manual.html redirects to foo.html
split ref / mono target -> fail or target in manual/foo.html redirecting to
the mono manual
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, @exdent, @noindent,
@page, @refill, @footnote, @sp, @*ref, @uref
and corresponding @end command.
Accented letters are transformed into their unicode equivalent character
in normal form C.
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 '@TeX{a text}' leads to 'TeX a text'. 'SPACE' means
a space.
@(space) SPACE
@(tab) SPACE
@(newline) SPACE
@* SPACE
@! !
@? ?
@. .
@: NOTHING
@tie SPACE
@equiv utf-8 character 2261
@print -|
@error error-->
@enddots ....
@TeX TeX
@exclamdown utf-8 character 00A1
@questiondown utf-8 character 00BF
@pounds pounds utf-8 character 00A3
@@ @
@{ {
@} }
@- NOTHING
@point utf8 character 2217
@result utf8 character 21D2
@expansion utf8 character 2192
@bullet utf8 character 2022
@minus utf8 character 2212
@copyright utf8 character 00A9
@dots utf8 character 2026
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.
@image is replaced by the first arg.
Other characters expansion
--------------------------
Non 7 bit characters are transformed into the unicode corresponding
character in normalization form C. It means that it is converted into a
serie of unicode points. In this serie the 7 bit characters are converted
as explained above and other characters are transformed into _xxxx where
xxxx is the unicode point in hexadecimal (still letters in lower case).
@node A node @b{@^{H} in _'%} and @TeX{} @u{B} @point{}@enddots{}
leads to
A-node-_0124-in_005f_0027_0025-and-Tex-B_0306-_2605_002e_002e_002e_002e
Notice
@enddots{} -> .... -> _002e_002e_002e_002e
@u{B} -> B followed by breve accent in unicode -> B_0306
Notes
-----
A node called index and the Top node are mapped to the same file name, namely
index.html. The targets are different, namely index and Top.
On case-folding systems nodes differing by the case are mapped to the same
file.
In other cases each node will map to a different file name.
In any case the targets are different as targets in html are case sensitive.
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 manual.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();">
Here are lists formatted as perl structures of unicode points associated
with texinfo characters. I may have made mistakes, forgotten some letters...
I found all that on http://www.alanwood.net/unicode/
(if you want that I convert those lists to another format, C table, or
whatever, I could do it very easily with simple perl script).
The precomposed unicode points are here for rememberance only as what is used
is the normalized form C for the character.
%unicode_map = (
'bullet' => '2022',
'copyright' => '00A9',
'dots' => '2026',
'enddots' => '',
'equiv' => '2261',
'error' => '',
'expansion' => '2192',
'minus' => '2212', # in mathematical operators
# 'minus' => '002D', # in latin1
'point' => '2217',
'print' => '',
'result' => '21D2',
'aa' => '00E5',
'AA' => '00C5',
'ae' => '00E6',
'oe' => '0153',
'AE' => '00C6',
'OE' => '0152',
'o' => '00F8',
'O' => '00D8',
'ss' => '00DF',
'l' => '0142',
'L' => '0141',
'exclamdown' => '00A1',
'questiondown' => '00BF',
'pounds' => '00A3'
);
%ascii_map = (
' ' => '0020',
'!' => '0021',
'"' => '0022',
'#' => '0023',
'$' => '0024',
'%' => '0025',
'&' => '0026',
"'" => '0027',
'(' => '0028',
')' => '0029',
'*' => '002A',
'+' => '002B',
',' => '002C',
'-' => '002D',
'.' => '002E',
'/' => '002F',
':' => '003A',
';' => '003B',
'<' => '003C',
'=' => '003D',
'>' => '003E',
'?' => '003F',
'@' => '0040',
'[' => '005B',
'\\' => '005C',
']' => '005D',
'^' => '005E',
'_' => '005F',
'`' => '0060',
'{' => '007B',
'|' => '007C',
'}' => '007D',
'~' => '007E',
);
Precomposed unicode characters
%unicode_accents = (
'dotaccent' => { # dot above
'A' => '0226', #C moz-1.2
'a' => '0227', #c moz-1.2
'B' => '1E02',
'b' => '1E03',
'C' => '010A',
'c' => '010B',
'D' => '1E0A',
'd' => '1E0B',
'E' => '0116',
'e' => '0117',
'F' => '1E1E',
'f' => '1E1F',
'G' => '0120',
'g' => '0121',
'H' => '1E22',
'h' => '1E23',
'i' => '0069',
'I' => '0130',
'N' => '1E44',
'n' => '1E45',
'O' => '022E', #Y moz-1.2
'o' => '022F', #v moz-1.2
'P' => '1E56',
'p' => '1E57',
'R' => '1E58',
'r' => '1E59',
'S' => '1E60',
's' => '1E61',
'T' => '1E6A',
't' => '1E6B',
'W' => '1E86',
'w' => '1E87',
'X' => '1E8A',
'x' => '1E8B',
'Y' => '1E8E',
'y' => '1E8F',
'Z' => '017B',
'z' => '017C',
},
'udotaccent' => { # dot below
'B' => '1E04',
'b' => '1E05',
'D' => '1E0C',
'd' => '1E0D',
'E' => '1EB8',
'e' => '1EB9',
'H' => '1E24',
'h' => '1E25',
'I' => '1ECA',
'i' => '1ECB',
'K' => '1E32',
'k' => '1E33',
'L' => '1E36',
'l' => '1E37',
'M' => '1E42',
'm' => '1E43',
'N' => '1E46',
'n' => '1E47',
'O' => '1ECC',
'o' => '1ECD',
'R' => '1E5A',
'r' => '1E5B',
'S' => '1E62',
's' => '1E63',
'T' => '1E6C',
't' => '1E6D',
'U' => '1EE4',
'u' => '1EE5',
'V' => '1E7E',
'v' => '1E7F',
'W' => '1E88',
'w' => '1E89',
'Y' => '1EF4',
'y' => '1EF5',
'Z' => '1E92',
'z' => '1E93',
},
'ubaraccent' => { # line below
'B' => '1E06',
'b' => '1E07',
'D' => '1E0E',
'd' => '1E0F',
'h' => '1E96',
'K' => '1E34',
'k' => '1E35',
'L' => '1E3A',
'l' => '1E3B',
'N' => '1E48',
'n' => '1E49',
'R' => '1E5E',
'r' => '1E5F',
'T' => '1E6E',
't' => '1E6F',
'Z' => '1E94',
'z' => '1E95',
},
',' => { # cedilla
'C' => '00C7',
'c' => '00E7',
'D' => '1E10',
'd' => '1E11',
'E' => '0228', #C moz-1.2
'e' => '0229', #c moz-1.2
'G' => '0122',
'g' => '0123',
'H' => '1E28',
'h' => '1E29',
'K' => '0136',
'k' => '0137',
'L' => '013B',
'l' => '013C',
'N' => '0145',
'n' => '0146',
'R' => '0156',
'r' => '0157',
'S' => '015E',
's' => '015F',
'T' => '0162',
't' => '0163',
},
'=' => { # macron
'A' => '0100',
'a' => '0101',
'E' => '0112',
'e' => '0113',
'I' => '012A',
'i' => '012B',
'G' => '1E20',
'g' => '1E21',
'O' => '014C',
'o' => '014D',
'U' => '016A',
'u' => '016B',
'Y' => '0232', #? moz-1.2
'y' => '0233', #? moz-1.2
},
'"' => { # diaeresis
'A' => '00C4',
'a' => '00E4',
'E' => '00CB',
'e' => '00EB',
'H' => '1E26',
'h' => '1E27',
'I' => '00CF',
'i' => '00EF',
'O' => '00D6',
'o' => '00F6',
't' => '1E97',
'U' => '00DC',
'u' => '00FC',
'W' => '1E84',
'w' => '1E85',
'X' => '1E8C',
'x' => '1E8D',
'Y' => '0178',
'y' => '00FF',
},
'u' => { # breve
'A' => '0101',
'a' => '0102',
'E' => '0114',
'e' => '0115',
'G' => '011E',
'g' => '011F',
'I' => '012C',
'i' => '012D',
'O' => '014E',
'o' => '014F',
'U' => '016C',
'u' => '016D',
},
"'" => { # acute
'A' => '00C1',
'a' => '00E1',
'C' => '0106',
'c' => '0107',
'E' => '00C9',
'e' => '00E9',
'G' => '01F4',
'g' => '01F5',
'I' => '00CD',
'i' => '00ED',
'K' => '1E30',
'k' => '1E31',
'L' => '0139',
'l' => '013A',
'M' => '1E3E',
'm' => '1E3F',
'N' => '0143',
'n' => '0144',
'O' => '00D3',
'o' => '00F3',
'P' => '1E54',
'p' => '1E55',
'R' => '0154',
'r' => '0155',
'S' => '015A',
's' => '015B',
'U' => '00DA',
'u' => '00FA',
'W' => '1E82',
'w' => '1E83',
'Y' => '00DD',
'y' => '00FD',
'Z' => '0179',
'z' => '018A',
},
'~' => { # tilde
'A' => '00C3',
'a' => '00E3',
'E' => '1EBC',
'e' => '1EBD',
'I' => '0128',
'i' => '0129',
'N' => '00D1',
'n' => '00F1',
'O' => '00D5',
'o' => '00F5',
'U' => '0168',
'u' => '0169',
'V' => '1E7C',
'v' => '1E7D',
'Y' => '1EF8',
'y' => '1EF9',
},
'`' => { # grave
'A' => '00C0',
'a' => '00E0',
'E' => '00C8',
'e' => '00E8',
'I' => '00CC',
'i' => '00EC',
'N' => '01F8',
'n' => '01F9',
'O' => '00D2',
'o' => '00F2',
'U' => '00D9',
'u' => '00F9',
'W' => '1E80',
'w' => '1E81',
'Y' => '1EF2',
'y' => '1EF3',
},
'^' => { # circumflex
'A' => '00C2',
'a' => '00E2',
'C' => '0108',
'c' => '0109',
'E' => '00CA',
'e' => '00EA',
'G' => '011C',
'g' => '011D',
'H' => '0124',
'h' => '0125',
'I' => '00CE',
'i' => '00EE',
'J' => '0134',
'j' => '0135',
'O' => '00D4',
'o' => '00F4',
'S' => '015C',
's' => '015D',
'U' => '00DB',
'u' => '00FB',
'W' => '0174',
'w' => '0175',
'Y' => '0176',
'y' => '0177',
'Z' => '1E90',
'z' => '1E91',
},
'ringaccent' => { # ring
'A' => '00C5',
'a' => '00E5',
'U' => '016E',
'u' => '016F',
'w' => '1E98',
'y' => '1E99',
},
'v' => { # caron
'A' => '01CD',
'a' => '01CE',
'C' => '010C',
'c' => '010D',
'D' => '010E',
'd' => '010F',
'E' => '011A',
'e' => '011B',
'G' => '01E6',
'g' => '01E7',
'H' => '021E', #K with moz-1.2
'h' => '021F', #k with moz-1.2
'I' => '01CF',
'i' => '01D0',
'K' => '01E8',
'k' => '01E9',
'L' => '013D', #L' with moz-1.2
'l' => '013E', #l' with moz-1.2
'N' => '0147',
'n' => '0148',
'O' => '01D1',
'o' => '01D2',
'R' => '0158',
'r' => '0159',
'S' => '0160',
's' => '0161',
'T' => '0164',
't' => '0165',
'U' => '01D3',
'u' => '01D4',
'Z' => '017D',
'z' => '017E',
},
'H' => { # double acute
'O' => '0150',
'o' => '0151',
'U' => '0170',
'u' => '0171',
},
);
Pat
_______________________________________________
Texinfo home page: http://www.gnu.org/software/texinfo/
[email protected]
http://ff0.org/mailman/listinfo/texinfo-pretest