On Tue, Dec 2, 2014 at 10:13 AM, Nick Wellnhofer <[email protected]> wrote:
> I just landed a new branch `markdown_v2` with many improvements including
> better HTML output and links to methods and functions using fragment
> identifiers.
Having prefixes greyed is a nice touch!
> Unfortunately, we can't easily link to specific methods in our
> Perl POD because information about method parameters appears in the section
> headers.
Certainly that's something we could change.
> The Clownfish URI scheme now supports the following type of links:
>
> clownfish:class:{parcel}:{struct_sym}
> clownfish:class:{struct_sym}
> clownfish:method:{parcel}:{struct_sym}:{macro_sym}
> clownfish:method:{struct_sym}:{macro_sym}
> clownfish:method:{macro_sym}
> clownfish:function:{parcel}:{struct_sym}:{micro_sym}
> clownfish:function:{struct_sym}:{micro_sym}
> clownfish:function:{micro_sym}
Suggestions:
* Use dot separation.
* We should be able to glean enough information from our naming conventions
to eliminate "class", "method", etc.
* Empty brackets imply that we should insert a host-appropriate alias.
[Lucy](cfish:org.apache.lucy) # parcel
[](cfish:org.apache.lucy.Query) # class
[](cfish:org.apache.lucy.Hits.Next) # method
[](cfish:org.apache.lucy.Freezer.freeze) # function
[](cfish:null)
> If the `parcel` or `struct_sym` components are missing, the values of the
> current class are used. This allows for shorter URIs.
I think you can achieve the same functionality with only a leading dot to
differentiate methods and functions from classes and parcels.
[](cfish:Query) # class in the current parcel
[](cfish:.Next) # method in the current parcel and class
[](cfish:.freeze) # function in the current parcel and class
[](cfish:Hits.Next) # method, same parcel different class
[](cfish:Freezer.freeze) # function, same parcel different class
> I'm also thinking
> about using `cfish` instead of `clownfish` as URI scheme.
Sure, that works. Protocols generally have short names.
> I'm also working on a `clownfish:null` pseudo-URI that can be used to fill
> in the host language's name for an undefined value. Then all of the old
> `perlify_pod` hacks can be eliminated.
Well, there's still the issue of method name aliasing to suit the conventions
of the host language. For Perl, `Method_Name()` gets downcased to
`method_name()`; for Go, it would be `MethodName()`, for Java,
JavaScript and the
like it would be `methodName()`, etc.
(Method name aliasing is also an unsolved issue in certain other contexts,
such as C string literal error messages.)
Marvin Humphrey
