lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marvin Humphrey <mar...@rectangular.com>
Subject Re: [lucy-dev] Markdown for documentation
Date Sun, 13 May 2012 18:44:23 GMT
On Sat, May 12, 2012 at 10:01 PM, David E. Wheeler
<david@justatheory.com> 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`.

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.

So... in vanilla Markdown, we can use bullet lists in conjunction with
backticks -- and thus I don't believe that definition lists are required.

    * `foo` - A Foo.
    * `bar` - A Bar.

> 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.

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.

(I hope Sundown can be persuaded to support vanilla Markdown rather than
Github-flavored Markdown.)

> * [Discount](http://www.pell.portland.or.us/~orc/Code/discount/). BSD
>   license. Fast, but kind of weird, both in its additional syntax (definition
>   lists are kind of ugly) and in its interface.

Looks like Discount is Unix-only. :(

> * [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.

> * [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.

Marvin Humphrey

Mime
View raw message