On May 13, 2012, at 2:44 PM, Marvin Humphrey wrote: > On Sat, May 12, 2012 at 10:01 PM, David E. Wheeler > <[email protected]> wrote: >> The one complaint I have about Sundown is its lack of support for definition >> lists. >> >> https://github.com/tanoku/sundown/issues/10 >> >> This is especially important, I find, for documenting lists of parameters >> for methods. Definition lists are perfect for this. POD does that, too, with >> the `=item text` syntax. > > We don't use `=item text` in Lucy's POD for parameter lists, though. I hate > the fact that perldoc doesn't indent the label text, even if you use > `=over 8`.
It indents the definition text. Example from DBIx::Connector: > Constructs and returns a DBIx::Connector object. The supported > arguments are exactly the same as those supported by the DBI. Default > values for those parameters vary from the DBI as follows: > > "RaiseError" > Defaults to true if unspecified, and if "HandleError" is > unspecified. Use of the "RaiseError" attribute, or a "HandleError" > attribute that always throws exceptions (such as that provided by > Exception::Class::DBI), is required for the exceptionâhandling > functionality of "run()", "txn()", and "svp()" to work properly. > Their explicit use is therefor recommended if for proper error > handling with these execution methods. > > "AutoInactiveDestroy" > Added in DBI 1.613. Defaults to true if unspecified. This is > important for safe disconnects across forking processes. I think this is great, because I can scan the definition labels quickly to find what I want. If you mean HTML, that's nothing to do with Pod. It's a CSS issue. > Here are the two approaches contrasted: > > http://search.cpan.org/~dwheeler/Text-Markup-0.17/lib/Text/Markup.pm#new > > http://search.cpan.org/~logie/Lucy-0.3.1/lib/Lucy/Search/IndexSearcher.pod#hits%28_[labeled_params]_%29 > > I like your use of C<param_name> as opposed to our B<param_name>! We should > switch to that. I prefer definition lists to bulleted lists, myself. You might need to use B<C<>> to make the labels stand out in a bulleted list, so they are easier to scan. >> But Sundown does not. At least, not yet. Maybe >> you'd want to add it? Last time I asked tanoku about it, he said that the >> PHP Markdown syntax is terrible to parse. > > Here's the thing. There's only one Markdown specification: Gruber's original. > Then there are a zillion different implementations which extend Markdown > in incompatible ways. Well, MultiMarkdown is pretty well accepted as the #2 definition. Most implementations follow its examples (FBOFW). > If this was only for our own internal use, it wouldn't matter. But we're > defining a public API: the syntax for Clownfish documentation. IMO, the only > sane approach is to lock the API to the unchanging vanilla Markdown spec, > rather than to the shifting implementation details of what happens to be > supported by one particular library. MultiMarkdown is pretty stable. Note that Sundown supports quite a lot more than just vanilla Markdown. How would you enforce that? > (I hope Sundown can be persuaded to support vanilla Markdown rather than > Github-flavored Markdown.) I expect they would accept a patch. >> * [peg-multimarkdown](https://github.com/fletcher/peg-multimarkdown). But >> that's just too bloody big, isn't it? > > The size isn't outrageous, and it looks portable -- but the build seems to be > fairly complex. It would take an unknown amount of work to integrate it. Yeah, I thought it was too much to bother with. >> * [upskirt](http://fossil.instinctive.eu/libupskirt/index). From which >> Sundown was forked. Bare-bones parser-only implementation. Might require >> more work to use, I don't know. > > I'm a little concerned about ongoing maintenance. > > http://fossil.instinctive.eu/libupskirt/wiki?name=about-the-name > > The whole github-triggered curse has been extremely painful for me. It's by > far the worst coding-related experience I ever went through. That made me > retire from Open Source. > > However I still feel a sense of duty, to fix whatever bugs it might > contain, > and occasionally going through the process of releasing a batch of > fixes in a > new version. Even for 1 user (myself excluded this time) I feel can't just > leave like that. I feel responsible for maintaining the code base as long > as > it's used somewhere by someone. > > However I don't know yet how long the sense of duty will stand against the > increasingly strong disgust for whole thing. > > However, even abandoned code might be OK for us, since this is for use by CFC > rather than Lucy, and the needs of a compiler vis a vis security maintenance > are vastly less than for a web-facing library. Yeah, and you could fork it if you wanted. David
