On 14/05/2013 05:52, Marvin Humphrey wrote:
Experience has shown that the uppercase/lowercase thing is a horrible trap,
though -- that really needs to be fixed (by hiding the implementing function),
not just explained.
For users from outside a parcel it is kind of fixed by symbol
visibility. Using a lowercase name for a method will result in a link
error. This has been discussed already:
http://s.apache.org/pIr
I seem to remember you made a more concrete proposal somewhere, but
maybe I'm wrong. Another possible approach would be to hide the
implementing functions via #ifdefs.
I wouldn't want to block the release because we haven't dealt with the
Markdown transition yet. It's not really straight-up Markdown either -- at
the least it's a custom Markdown extension which supports @tags and funky
links.
We can hack in individual features as short term fixes rather than solving all
these problems and integrating a parser as a dependencey. For instance, we
can replace the <code></code> construct with backticks. Detecting
markdown-style links and hacking in our own treatment wouldn't be much harder.
I can also work with the current constructs as they are. I think it's
only POD-style links and <code>.
When I'm finished with the man pages, I plan to use a man-to-html converter
and put the result on the Lucy website.
FWIW... In this day and age, the HTML is probably going to get read a lot more
often.
True. It would be better to generate HTML directly. But like the man
page generator, this will be really easy.
Nick
