Re: cross manual references in html manuals, second

[Dumas Patrice]

> @verbatim, @tex, and @html are environments (with corresponding @end),
> so they can't be included in node names.

Right.
 
> @verb, on the other hand, seems like it could be allowed.
> It would just "expand" to its argument.

Right too

>     Accented letters are transformed into their 8-bit equivalent character,
>     according to the iso latin 1 mapping.
> 
> There are accented letters not in Latin 1.  Perhaps we have use utf-8.

Argh. This is quite annoying, as we then have to use an encoding of special
chars like _xxxx (if I'm not wrong about the number of hexadecimal characters 
used to describe an utf-8 character) for anything else than ascii 7bit. Not
a real problem though, but it has to be fully acknowledged.

>     The following @ commands have no real reason to be used in node names, 
> thus
>     it is recommended to use the plain text equivalent:
> 
> I'm not sure what this means.  I don't think it matters though.

I was trying to say that people doing manuals should avoid using the @commands
and use instead what will be expanded, for example people should avoid doing

@node a @equiv b 

but rather write
@node a == b

>     @equiv equiv OR ==
>     ...
> 
> I think the symbolic representation (==) would be better than the word
> `equiv'.

Right

>     @today today
> 
> Should probably be the actual date.

Hum. In node name expansion in documents, yes, but for cross reference 
to other manuals I think it is better not ot use the date of generation 
of manual as it has chances to be wrong.

>     @copyright (C)
>     ...
>     @exclamdown ! OR 8-bits equivalent
>     @questiondown ? OR 8-bits equivalent
>     @pounds pounds OR 8-bits equivalent
> 
> The 8-bit character seems like the right thing for all of these.

Or utf-8 if we go for utf-8 for accented characters.

>     I don't remember what the following does ;-)
>     @tie SPACE
> 
> It produces an interword space at which a line break is not allowed.
> Like ~ in plain TeX and LaTeX.

Allright.

>     @email is replaced by the text, and if not present the mail adress.
> 
> @email could appear in a node name as much as anything else.
> 
>     The letters in hexadecimal should be in small caps.
> 
> Lowercase, not small caps.

Of course, sorry for that mistake. In fact I mistaken caps for case everywhere
in the proposal... (by the way don't hesitate to correct me, I am not a
native english speaker, and that's pretty bad when I try to do formal 
proposals :).

>     (the local software may also skip the file name as browsers (or servers ?)
> 
> Servers.  Browsers just do `GET /' or whatever.  It's up to the server
> to decide whether to return index.html, or index.htm, or run index.cgi,
> or whatever.  (See the DirectoryIndex directive in Apache.)

Right.

>     The manual name should only contain the following characters:
>     [A-Za-z0-9-_/], / having a special meaning.
> 
> And `.', also with a special meaning.  (For example, the Emacs manuals
> say address@hidden ../info/emacs'; not that I think this is a good idea,
> but it's the way it is.)

Right.

>     and anchor names and generate a file per filename constructed as above. 
> 
> Really?  I don't think we necessarily have to generate a file for every
> node.  (If that's the `filename constructed as above' that you mean.)
> That would make --no-split impossible to implement, and users wouldn't
> be happy about that.

Argh. I specified that (a file per node) in order to avoid at best having 
to resort to javascript, and also for (a sort of) backward compatibility
with what does makeinfo... But if you like better the other possibility
it also has some advantages too. For example all the links are in a file,
there are no unusefull files generated, we don't have to hassle with file
names.

> Instead, how about always generating the xref to the top level of the manual?
> http://distant/manual/index.html#target
> 
> In the no-split case, that will just work.  If the distant manual is
> split (in whatever way), then the distant software makes the above url
> redirect (using your javascript method) to:
> http://distant/manual/targetfile.html#target

No problem. I will do another proposal, then.
 
>     Also makeinfo keeps the caps in file names.
> Did I miss something?  Don't we get to use both A-Z and a-z?  Are you
> proposing case-folding somewhere along the way?  I didn't see that.

If you look closely at my proposal, the files used only [a-z], as somebody
said that on windows the case didn't matter. But it doesn't matter if
the only filename really used is index.html.

Pat