lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David E. Wheeler" <>
Subject Re: [lucy-dev] Markdown for documentation
Date Tue, 15 May 2012 14:51:21 GMT
On May 13, 2012, at 2:44 PM, Marvin Humphrey wrote:

> On Sat, May 12, 2012 at 10:01 PM, David E. Wheeler
> <> wrote:
>> The one complaint I have about Sundown is its lack of support for definition lists.
>> 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:
> 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]( 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]( 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.
>    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.


View raw message