texinfo/doc texinfo.txi,1.37,1.38

[karl]

Update of /cvsroot/texinfo/texinfo/doc
In directory sheep:/tmp/cvs-serv12581

Modified Files:
        texinfo.txi 
Log Message:
html xref checkpoint

Index: texinfo.txi
===================================================================
RCS file: /cvsroot/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.37
retrieving revision 1.38
diff -C2 -d -r1.37 -r1.38
*** texinfo.txi 14 Mar 2004 22:52:53 -0000      1.37
--- texinfo.txi 15 Mar 2004 16:22:32 -0000      1.38
***************
*** 605,609 ****
  * HTML Splitting::         How HTML output is split.
  * HTML CSS::               Influencing HTML output with Cascading Style 
Sheets.
! * HTML Cross-references::  Cross-references in HTML output.
  
  @@-Command List
--- 605,609 ----
  * HTML Splitting::         How HTML output is split.
  * HTML CSS::               Influencing HTML output with Cascading Style 
Sheets.
! * HTML Xref::              Cross-references in HTML output.
  
  @@-Command List
***************
*** 15773,15777 ****
  * HTML Splitting::         How HTML output is split.
  * HTML CSS::               Influencing HTML output with Cascading Style 
Sheets.
! * HTML Cross-references::  Cross-references in HTML output.
  @end menu
  
--- 15773,15777 ----
  * HTML Splitting::         How HTML output is split.
  * HTML CSS::               Influencing HTML output with Cascading Style 
Sheets.
! * HTML Xref::              Cross-references in HTML output.
  @end menu
  
***************
*** 15947,15951 ****
  
  
! @node HTML Cross-references
  @section HTML Cross-references
  @cindex HTML cross-references
--- 15947,15951 ----
  
  
! @node HTML Xref
  @section HTML Cross-references
  @cindex HTML cross-references
***************
*** 15972,15977 ****
  
  @menu
! * HTML Xref Link Basics::
! * HTML Xref Node Name Expansion::
  @end menu
  
--- 15972,15980 ----
  
  @menu
! * Link Basics:       HTML Xref Link Basics:
! * Node Expansion:    HTML Xref Node Name Expansion:
! * Command Expansion: HTML Xref Command Expansion:
! * 8-bit Expansion:   HTML Xref 8-bit Character Expansion:
! * Mismatch:          HTML Xref Mismatch:
  @end menu
  
***************
*** 16003,16007 ****
  The @var{dir} and @var{file} parts are more complicated, and depend on
  the relative split/mono nature of both the manual being processed and
! the manual that the cross-reference refers to:
  
  @itemize @bullet
--- 16006,16013 ----
  The @var{dir} and @var{file} parts are more complicated, and depend on
  the relative split/mono nature of both the manual being processed and
! the manual that the cross-reference refers to.  The underlying idea is
! that there is one directory for Texinfo manuals in HTML, and each
! manual is either available as a monolithic file @file{manual.html}, or a
! split subdirectory @file{manual/*.html}.  Here are the cases:
  
  @itemize @bullet
***************
*** 16027,16033 ****
  @end itemize
  
! The @var{target} part is always the expanded node name.  (Technically,
! node or anchor name (@pxref{anchor}), but anchors are treated
! identically to nodes in this context.)
  
  Whether the present manual is split or mono is determined by user
--- 16033,16037 ----
  @end itemize
  
! Finally, the @var{target} part is always the expanded node name.
  
  Whether the present manual is split or mono is determined by user
***************
*** 16039,16042 ****
--- 16043,16050 ----
  referent manual is the same as the present manual.
  
+ There can be a mismatch between the format of the referent manual that
+ the generating software assumes, and the format it's actually present
+ in.  @xref{HTML Xref Mismatch}.
+ 
  
  @node HTML Xref Node Name Expansion
***************
*** 16045,16048 ****
--- 16053,16337 ----
  @cindex node name expansion, in HTML cross-references
  @cindex expansion, of node names in HTML cross-references
+ 
+ As mentioned in the previous section, the key part of the HTML
+ cross-reference algorithm is the conversion of node names in the
+ Texinfo source into strings suitable for HTML identifiers and
+ filenames.  The restrictions are similar for each: plain ASCII
+ letters, numbers, and the @samp{-} and @samp{_} characters are all
+ that can be used.
+ 
+ (Cross-references in Texinfo can actually refer either to nodes or
+ anchors (@pxref{anchor}), but anchors are treated identically to nodes
+ in this context, so we'll continue to say ``node'' names for
+ simplicity.)
+ 
+ @@-commands and 8-bit characters are not presently handled by
+ @command{makeinfo} for HTML cross-references.  See the next section.
+ 
+ A special exception: the Top node (@pxref{The Top Node}) is always
+ mapped to the file @file{index.html}, to match web server software.
+ However, the HTML target remains @samp{Top}.
+ 
+ @enumerate
+ @item
+ The standard ASCII letters (a-z and A-z), and numbers (0-9) are not
+ modified.  All other characters are changed as specified below.
+ 
+ @item
+ Multiple consecutive space, tab and newline characters are transformed
+ into just one space.  (It's not possible to have newlines in node
+ names with the current implementation, but we specify it anyway, just
+ in case.)
+ 
+ @item
+ Leading and trailing spaces are removed.
+ 
+ @item
+ After the above has been applied, each remaining space character is
+ converted into a @samp{-} character.
+ 
+ @item
+ Other ASCII 7-bit characters are transformed into @address@hidden,
+ where @var{xx} is the ASCII character code in (lowercase) hexadecimal.
+ This includes @samp{_}, which is mapped to @samp{_005f}.
+ 
+ @end enumerate
+ 
+ For example:
+ 
+ @example
+ @@node A  node --- with _'%
+ @result{} A-node-_002d_002d_002d-with-_005f_0027_0025
+ @end example
+ 
+ Notice in particular:
+ 
+ @itemize @bullet
+ @item @samp{_} @result{} @samp{_005f}
+ @item @samp{-} @result{} @samp{_002d}
+ @item @samp{A  node} @result{} @samp{A-node}
+ @end itemize
+ 
+ On case-folding computer systems, nodes differing only by case will be
+ mapped to the same file.  Many other distinct node names will be
+ mapped to the same file name, on any system.
+ 
+ In particular, as mentioned above, Top always maps to the file
+ @file{index.html}.  Thus, on a case-folding system, Top and a node
+ named `Index' will both be written to @file{index.html}.
+ 
+ Fortunately, the targets serve to distinguish these cases, since HTML
+ target names are always case-sensitive, independent of operating
+ system.
+ 
+ 
+ @node HTML Xref Command Expansion
+ @subsection HTML Cross-reference Command Expansion
+ @cindex HTML cross-reference command expansion
+ 
+ In standard Texinfo, node names may not contain @@-commands.
+ @command{makeinfo} has an option @option{--commands-in-node-names}
+ which partially supports it (@pxref{Invoking makeinfo}), but it is not
+ robust and not recommended.
+ 
+ Thus, @command{makeinfo} also does not fully implement this part of
+ the HTML cross-reference algorithm, but it is documented here for the
+ sake of completeness.
+ 
+ First, comments are removed.
+ 
+ Next, any @code{@@value} commands (@pxref{set value}) and macro invocations
+ (@pxref{Invoking Macros}) are fully expanded.
+ 
+ Then, for the following commands, the command name and braces are removed,
+ the text of the argument is recursively transformed: @code{
+ @@acronym
+ @@asis
+ @@b
+ @@cite
+ @@code
+ @@command
+ @@dfn
+ @@dmn
+ @@dotless
+ @@emph,
+ @@env
+ @@file
+ @@kbd
+ @@key
+ @@samp
+ @@sc
+ @@strong
+ @@t
+ @@url
+ @@var
+ @@w
+ }.  For @code{@@sc}, any letters are capitalized.
+ 
+ The following commands are replaced by constant text, as shown.  If
+ any of these commands have non-empty arguments, as in
+ @code{@@address@hidden@}}, it is an error, and the result is unspecified.
+ `(space)' means a space character, `(nothing)' means the empty string,
+ etc.  The notation address@hidden' means Unicode code point @var{xxxx}.
+ There are further transformations of many of these expansions for the
+ final file or target name, such as space characters to @samp{-}, etc.,
+ according to the other rules.
+ 
+ @multitable @columnfractions .3 .5
+ @item @code{@@(space)}          @tab (space)
+ @item @code{@@(tab)}            @tab (space)
+ @item @code{@@(newline)}        @tab (space)
+ @item @code{@@*}                @tab (space)
+ @item @code{@@!}                @tab @samp{!}
+ @item @code{@@?}                @tab @samp{?}
+ @item @code{@@.}                @tab @samp{.}
+ @item @code{@@:}                @tab (nothing)
+ @item @code{@@tie}              @tab (space)
+ @item @code{@@equiv}            @tab U+2261
+ @item @code{@@print}            @tab @samp{-|}
+ @item @code{@@error}            @tab @samp{error-->}
+ @item @code{@@enddots}          @tab @samp{...}
+ @item @code{@@TeX}              @tab @samp{TeX}
+ @item @code{@@exclamdown}       @tab U+00A1
+ @item @code{@@questiondown}     @tab U+00BF
+ @item @code{@@pounds}           @tab U+00A3
+ @item @code{@@@@}               @tab @samp{@@}
+ @item @code{@@@{}               @tab @address@hidden
+ @item @code{@@@}}               @tab @address@hidden
+ @item @code{@@-}                @tab (nothing)
+ @item @code{@@point}            @tab U+2217
+ @item @code{@@result}           @tab U+21D2
+ @item @code{@@expansion}        @tab U+2192
+ @item @code{@@bullet}           @tab U+2022
+ @item @code{@@minus}            @tab U+2212
+ @item @code{@@copyright}        @tab U+00A9
+ @item @code{@@dots}             @tab U+2026
+ @end multitable
+ 
+ An @code{@@email} command is replaced by the @var{text} argument if
+ present, else the address.  @xref{email}.
+ 
+ An @code{@@image} command is replaced by the filename (first)
+ argument.  @xref{Images}.
+ 
+ A @code{@@verb} command is replaced by its transformed argument.
+ @xref{verb}.
+ 
+ Any other command is an error, and the result is unspecified.
+ 
+ 
+ @node HTML Xref 8-bit Character Expansion
+ @subsection HTML Cross-reference 8-bit Character Expansion
+ @cindex HTML cross-reference 8-bit character expansion
+ @cindex 8-bit characters, in HTML cross-references
+ @cindex Expansion of 8-bit characters in HTML cross-references
+ 
+ Characters other than plain 7-bit ASCII are transformed into the
+ corresponding Unicode code point(s), in Normalization Form C, which
+ uses precomposed characters where available.  (This is the
+ normalization form recommended by the W3C and other bodies.)
+ 
+ These will then be further transformed by the rules above into the
+ string @address@hidden, where @var{xxxx} is the code point in hex.
+ 
+ For example, combining this rule and the previous section:
+ 
+ @example
+ @@node @@address@hidden@} @@address@hidden@} @@address@hidden@} 
@@address@hidden@}@@address@hidden@}
+ @result{} A-TeX-B_0306-_2605_002e_002e_002e
+ @end example
+ 
+ Notice: 1)@address@hidden@@enddots} expands to three periods which in turn 
expands
+ to three @samp{_002e}'s; 2)@address@hidden@@address@hidden@}} is a `B' with a 
breve
+ accent, which does not exist as a pre-accented Unicode character,
+ therefore expands to @samp{B_0306} (B with combining breve).
+ 
+ For the definition of Unicode Normalization Form C, see Unicode report
+ UAX#15, @uref{http://www.unicode.org/reports/tr15/}.  Many related
+ documents and implementations are available elsewhere on the web.
+ 
+ 
+ @node HTML Xref Mismatch
+ @subsection HTML Cross-reference Mismatch
+ @cindex HTML cross-reference mismatch
+ @cindex Mismatched HTML cross-reference source and target
+ 
+ As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating
+ software has to guess whether a given manual being cross-referenced is
+ available in split or monolithic form---and, inevitably, it might
+ guess wrong.  However, it is possible when the referent manual itself
+ is generated, it is possible to handle at least some mismatches.
+ 
+ In the case where we assume the referent is split, but it is actually
+ available in mono, the only recourse would be to generate a
+ @file{manual/} subdirectory full of HTML files which redirect back to
+ the monolithic @file{manual.html}.  Since this is essentially the same
+ as a split manual in the first place, it's not very appealing.
+ 
+ On the other hand, in the case where we assume the referent is mono,
+ but it is actually available in split, it is possible to use
+ JavaScript to redirect from the putatively monolithic
+ @file{manual.html} to the different @file{manual/node.html} files.
+ Here's an example:
+ 
+ @example
+ function redirect() @{
+   switch (location.hash) @{
+     case "#Node1":
+       location.replace("manual/Node1.html#Node1"); break;
+     case "#Node2" :
+       location.replace("manual/Node2.html#Node2"); break;
+     @dots{}
+     default:;
+   @}
+ @}
+ @end example
+ 
+ Then, in the @code{<body>} tag of @file{manual.html}:
+ 
+ @example
+ <body onLoad="redirect();">
+ @end example
+ 
+ Once again, this is something the software which generated the
+ @emph{referent} manual has to do in advance, it's not something the
+ software generating the actual cross-reference in the present manual
+ can control.
+ 
+ Ultimately, we hope to allow for an external configuration file to
+ control which manuals are available from where, and how.
+ 
+ 
+ @ignore
+ -- not yet --
+ 
+ external information
+ --------------------
+ 
+ The information for the reference is searched in the file
+ `htmlxref.cnf' present in the following directories:
+ <srcdir>/.texinfo/, ~/.texinfo/,  SYSCONFDIR/texinfo/,
+ DATADIR/texinfo/
+ The first match should be used.
+ 
+ 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. 
+ @end ignore
+ 
  
  @node Command List