texinfo/doc texinfo.txi,1.36,1.37

[karl]

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

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

Index: texinfo.txi
===================================================================
RCS file: /cvsroot/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.36
retrieving revision 1.37
diff -C2 -d -r1.36 -r1.37
*** texinfo.txi 14 Mar 2004 00:59:09 -0000      1.36
--- texinfo.txi 14 Mar 2004 22:52:53 -0000      1.37
***************
*** 15952,15957 ****
  @cindex Cross-references, in HTML output
  
! @c xxcoming in next pretest
  
  
  @node Command List
--- 15952,16048 ----
  @cindex Cross-references, in HTML output
  
! Cross-references between Texinfo manuals in HTML format amount, in the
! end, to a standard HTML @code{<a>} link, but the details are
! unfortunately complex.  This section describes the algorithm used in
! detail, so that Texinfo can cooperate with other programs, such as
! @command{texi2html}, by writing mutually compatible HTML files.
! 
! This algorithm may or may not be used for links @emph{within} HTML
! output for a Texinfo file.  Since no issues of compatibility arise in
! such cases, we do not need to specify this.
! 
! We try to support references to such ``external'' manuals in both
! monolithic and split forms.  A @dfn{monolithic} (mono) manual is
! entirely contained in one file, and a @dfn{split} manual has a file
! for each node.  (@xref{HTML Splitting}.)
! 
! @cindex Dumas, Patrice
! Acknowledgement: this algorithm was primarily devised by Patrice Dumas
! in 2003--04.
! 
! @menu
! * HTML Xref Link Basics::
! * HTML Xref Node Name Expansion::
! @end menu
  
+ 
+ @node HTML Xref Link Basics
+ @subsection HTML Cross-reference Link Basics
+ @cindex HTML cross-reference link basics
+ 
+ For our purposes, an HTML link consists of four components: a host
+ name, a directory part, a file part, and a target part.  We
+ always assume the @code{http} protocol.  For example:
+ 
+ @example
+ http://@var{host}/@var{dir}/@address@hidden
+ @end example
+ 
+ The information to construct a link comes from the node name and
+ manual name in the cross-reference command in the Texinfo source
+ (@pxref{Cross References}), and from @dfn{external information}, which
+ is currently simply hardwired.  In the future, it may come from an
+ external data file.
+ 
+ We now consider each part in turn.
+ 
+ The @var{host} is hardwired to be the local host.  This could either
+ be the literal string @samp{localhost}, or, according to the rules for
+ HTML links, the @samp{//localhost} could be omitted entirely.
+ 
+ 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
+ @item
+ If the present manual is split, and the referent manual is also split,
+ the directory is @samp{../@var{referent/}} and the file is the
+ expanded node name (described later).
+ 
+ @item
+ If the present manual is split, and the referent manual is mono, the
+ directory is @samp{../} and the file is @address@hidden
+ 
+ @item
+ If the present manual is mono, and the referent manual is split, the
+ directory is @address@hidden/} and the file is the expanded node
+ name.
+ 
+ @item
+ If the present manual is mono, and the referent manual is also mono,
+ the directory is @file{./} (or just the empty string), and the file is
+ @address@hidden
+ 
+ @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
+ option; @command{makeinfo} defaults to split, with the
+ @option{--no-split} option overriding this.
+ 
+ Whether the referent manual is split or mono is another bit of the
+ external information.  For now, @command{makeinfo} simply assumes the
+ referent manual is the same as the present manual.
+ 
+ 
+ @node HTML Xref Node Name Expansion
+ @subsection HTML Cross-reference Node Name Expansion
+ @cindex HTML cross-reference node name expansion
+ @cindex node name expansion, in HTML cross-references
+ @cindex expansion, of node names in HTML cross-references
  
  @node Command List