lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Logan Bell <loganb...@gmail.com>
Subject Re: [lucy-dev] Markdown for documentation
Date Tue, 15 May 2012 14:25:34 GMT
+1 to uses markdown for documentation, even if there is this tension with
github and the markdown specification.

I read through the various recommendations (Sundown, upskirt, etc) and
Sundown seems to be the most active and attempts to comply with markdown
specifications. Even though it sounds like Sundown may cater more to github
style markdown they have this message right on their homepage:

"Sundown passes out of the box the official Markdown v1.0.0 and v1.0.3 test
suites, and has been extensively tested with additional corner cases to
make sure its output is as sane as possible at all times."

Also, +1 to using B<param_name>, that was new to me as well.

Cheers,
Logan

On Sun, May 13, 2012 at 11:44 AM, Marvin Humphrey <marvin@rectangular.com>wrote:

> 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<http://search.cpan.org/%7Elogie/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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message