proposal for html manual cross links
Dumas Patrice <[email protected]> Mon, 8 Dec 2003 14:09:29 +0100
| Newsgroups | gmane.comp.tex.texinfo.pretest |
|---|---|
| Message-ID | <[email protected]> |
Hi,
I thought that this list would be better for such things. I can post on
bug-texinfo too if you wish.
Here is an updated version of the html cross manual references proposal.
Summary of changes
------------------
I merged in Karl comments.
I added some precisions about what to do when there is no utf8 character
for a given texinfo accented letter. I also propose to change spaces
to '-' and escape '-' like any other character to have a better readability
of simple text nodes with ascii 7 bit letters and spaces. And I also added
something about '---', '--', '' and ``.
I also propose the following change:
@point utf8 character 2217
@result utf8 character 21D2
@expansion utf8 character 2192
@bullet utf8 character 2022
@minus utf8 character 2212 (or 002D ?)
@copyright utf8 character 00A9
@dots utf8 character 2026
For '-' there are two possibilities: 2212 (mathematical symbols) and 002D
(latin1). What should we use ?
For '--' in normal text, it seems to me that the utf-8 character is '2010'
(hyphen), and for '---' it is '2014' (em dash).
Now the proposal:
Introduction
------------
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, @exdent, @noindent,
@page, @refill, @footnote, @sp, @*ref, @uref
and corresponding @end command.
Accented letters are transformed into their utf-8 equivalent character,
if such a thing exists. If there are more than one possibility for the
utf-8 character, which may happen for characters in the latin1 range and
in another range (@v{Z}, @v{s}, @ae{}...), the value not in the latin1 range
should be choosen. If no utf-8 character exists, the makeinfo convention
is used. I added a list of utf-8 characters associated with texinfo
constructs in the end of that mail.
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 (or 002D ?)
@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
node name expansion
-------------------
'--', '---', `` and '' which don't appear in the following @-commands
@code, @command, @env, @file, @kbd, @option, @samp, @verb,
should be transformed as follows:
--- corresponding utf-8 characters (hyphen) 2010
-- corresponding utf-8 characters (em dash) 2014
`` "
'' "
multiple spaces and tabs are transformed into just one space.
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.
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.
Notes
-----
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();">
Here are lists formatted as perl structures of utf-8 characters 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).
%utf8_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',
# 'oe' => '009C', in latin1
'AE' => '00C6',
'OE' => '0152',
# 'OE' => '008C', in latin1
'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',
);
%utf8_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' => '009F',
# 'y' => '00FF', # in latin1
'Y' => '0177',
},
'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' => '008A', # in latin1
# 's' => '009A', # in latin1
'S' => '0160',
's' => '0161',
'T' => '0164',
't' => '0165',
'U' => '01D3',
'u' => '01D4',
# 'Z' => '008E', # in latin1
# 'z' => '009E', # in latin1
'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