Re: [Epydoc-devel] Epydoc URLs and external API linking

[Edward L. <ed...@gr...>]

On Feb 18, 2007, at 7:04 PM, Daniele Varrazzo wrote:
> A simple naming scheme could be:
>
>   - prefix each uppercase and underscore with an underscore
>   - prefix each name with a letter (let's say N, for "name")
>
> The mapping should be injective even considering non-case-sensitive
> comparisons. Examples:
>
>   MyName    -> N_My_Name
>   _my_name  -> N__my__name
>   __init__  -> N____init____

I'd say to go ahead with this, for anchors only, but let's try to  
keep the mangled names as readable as possible.

First, I don't think adding a prefix is necessary, because (1) we  
don't generate many other anchors anyway, and (2) when we do generate  
them, they all currently contain "-".  We could continue that with  
any new anchors, thereby avoiding any conflicts.

Second, I don't like using underscore for escaping, because the  
result looks like it could be a different identifier.  If we're going  
to have a character to designate upcase, why not have it be something  
that doesn't occur in normal names, so it's clear that it's not part  
of the name?  Here's what we're allowed to use in xhtml for an id:

Id         ::=   (Letter | '_' | ':') (NameChar)*
NameChar   ::=   Letter | Digit | '.' | '-' | '_' |
                  ':' | CombiningChar | Extender

So how about using ":" to mark upcase letters?  We could then leave  
lower-case letters and underscores untouched.  Example cases:

>   original -> transformed      Example url
>    
> ---------------------------------------------------------------------- 
> -
>   MyName   -> :My:Name         http://foo/bar/SomeClass.html#:My:Name
>   _my_name -> _my_name         http://foo/bar/SomeClass.html#_my_name
>   __init__ -> __init__         http://foo/bar/SomeClass.html#__init__
>   MY_CONST -> :M:Y_:C:O:N:S:T  http://foo/bar/ 
> SomeClass.html#:M:Y_:C:O:N:S:T

Recall that this mangling is *only* used for anchors of functions,  
methods, & variables -- not for classes.  So in the common case,  
where functions, methods, and vars are written in all lower case, the  
mangling will be an identity function.  If we wanted to make the  
MY_CONST look better, at the expense of complexity, we could use  
these rule instead:

   - If name is all-caps, return name surrounded by ":"
   - Otherwise, prefix each capital letter w/ ":"

Making the examples:

>   MyName   -> :My:Name        http://foo/bar/SomeClass.html#:My:Name
>   _my_name -> _my_name        http://foo/bar/SomeClass.html#_my_name
>   __init__ -> __init__        http://foo/bar/SomeClass.html#__init__
>   MY_CONST -> :MY_CONST:      http://foo/bar/SomeClass.html#:MY_CONST:

-Edward