[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: cross manual references in html manuals

From: Karl Berry
Subject: Re: cross manual references in html manuals
Date: Mon, 19 May 2003 18:42:37 -0400

Passing over the question of @ commands in node names, which I already
talked about, here are a few more thoughts:

    The manual name should only contain the following characters:
    [A-Za-z0-9-_/], / having a special meaning.

I don't think it's a critical point, but I don't think we actually need
to restrict manual names, at least not as far as html goes, since we can
easily escape any special characters in html.  (Info is another story,
but that's a whole different problem.)  In practice, I don't know of any
public manuals that use any "bizarre" characters in the @setfilename.

    and '.' is left as is. I think '.' should also be considered 
    special, and also the file names should not be related to html, 

Sorry, I don't understand either of these points.  How is . special?
How are the file names related to html?

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

I don't think this is going to be acceptable to the users.  They need to
be able to write any (valid) node names they want, for example, there
might be a node $foo and a node %foo, both mapping to -foo.  I think
we have to allow this -- because Top maps to index.html, and
`Index' is a common node, and win32 is not case-sensitive, so both Top
and Index nodes will end up in the file `index.html' (or `Index.html',
take your pick).

And, I think this is achievable, because Eli implemented it for
makeinfo.  We just generate an anchor for each node, as in (putting the
node name as the text of the anchor here is not functional, but anyway
Node:&nbsp;<a name="$foo">$foo</a>,
Node:&nbsp;<a name="%25foo">%foo</a>,

Then the references to the two nodes become -foo.html#$foo and
-foo.html#%25foo, respectively.  Do you see a problem with this?

It's somewhat annoying since the common case of no conflicts still has
to be handled the same way (foo.html#foo.html), making the xrefs more
verbose, but I don't see a way to handle that.

Thanks Patrice, it's very nice to see this written out so carefully.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]