On 03/12/2014 15:06, Nick Wellnhofer wrote:
On 03/12/2014 05:16, Marvin Humphrey wrote:
On Tue, Dec 2, 2014 at 10:13 AM, Nick Wellnhofer <[email protected]> wrote:
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.
OK.
* 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)
My original plan was to always use the host alias if it's different from the
Clownfish name. This is already implemented for Perl method names. But we can
change that to replace the link text only if it's empty.
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
That should work. But I'd like to keep the URI syntax extensible. This could
be achieved by using other symbols:
cfish:@null
cfish:$null
cfish:#null
I'm also thinking
about using `cfish` instead of `clownfish` as URI scheme.
Sure, that works. Protocols generally have short names.
OK.
All of this is now implemented.
The only remaining issue is how to treat the global error variable. Currently,
we replace the text "Err_error" with "Clownfish->error" in the Perl POD. But
Err_error isn't a valid symbol (maybe it was at some point?), so we should use
something else for the C documentation. It should work to use a pseudo-link
like `[](cfish:@error)` with the following replacements:
C: "[the global error](cfish:cfish.Err.get_error)"
Perl: "Clownfish->error"
(Typical usage in the documentation is something like "...sets Err_error
when...").
Nick
