Return-Path: 
 <dev-return-2563-apmail-lucy-dev-archive=lucy.apache.org@lucy.apache.org>
X-Original-To: apmail-lucy-dev-archive@www.apache.org
Delivered-To: apmail-lucy-dev-archive@www.apache.org
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
	by minotaur.apache.org (Postfix) with SMTP id 861E7C1EE
	for <apmail-lucy-dev-archive@www.apache.org>;
 Fri, 18 May 2012 18:40:37 +0000 (UTC)
Received: (qmail 98024 invoked by uid 500); 18 May 2012 18:40:37 -0000
Delivered-To: apmail-lucy-dev-archive@lucy.apache.org
Received: (qmail 97990 invoked by uid 500); 18 May 2012 18:40:37 -0000
Mailing-List: contact dev-help@lucy.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:dev-help@lucy.apache.org>
List-Unsubscribe: <mailto:dev-unsubscribe@lucy.apache.org>
List-Post: <mailto:dev@lucy.apache.org>
List-Id: <dev.lucy.apache.org>
Reply-To: dev@lucy.apache.org
Delivered-To: mailing list dev@lucy.apache.org
Received: (qmail 97982 invoked by uid 99); 18 May 2012 18:40:37 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 18 May 2012 18:40:37 +0000
X-ASF-Spam-Status: No, hits=-0.0 required=5.0
	tests=RCVD_IN_DNSWL_LOW,SPF_NEUTRAL
X-Spam-Check-By: apache.org
Received-SPF: neutral (athena.apache.org: local policy)
Received: from [209.85.210.51] (HELO mail-pz0-f51.google.com) (209.85.210.51)
    by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 18 May 2012 18:40:33 +0000
Received: by dajt11 with SMTP id t11so3733317daj.10
        for <dev@lucy.apache.org>; Fri, 18 May 2012 11:40:12 -0700 (PDT)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=google.com; s=20120113;
        h=mime-version:x-originating-ip:in-reply-to:references:date
         :message-id:subject:from:to:content-type:content-transfer-encoding
         :x-gm-message-state;
        bh=ZygfKBdtem9wfNOEuaLM0rgi0Q+y2hKvUdtRn97M5ow=;
        b=e2X1BY1/7uPIbyObP/kPqFXjzuZulyrvHKethr1127CONRWC9PrXkD12S/atQn9UNS
         LsISd8xzodro/MeCQZWNElY8q6tH+VHd87wz2P7J5kR7KyLZ0+6MQ3qKvtLzaL2qKMbz
         H+iadXSwwzbqmcUYTihuvY936ZrlVSk5IDt/sgvVd6RLvbbgf4/EpIAxae3GKwYVz35V
         tm0oVj42+BAITQu4FoYsrIKm9MaE4FT+v7Jl7hq6ZxmZBXV+QqgDnE8fERnC68XJBu7q
         jcXQMbtH/5W/hcc39Xdvku6WWrQMGDSFLt+272iCD6TQ7wcv+LWz297FDUKpFvPloO6G
         Ph9A==
MIME-Version: 1.0
Received: by 10.68.227.227 with SMTP id sd3mr41333173pbc.53.1337366412074;
 Fri, 18 May 2012 11:40:12 -0700 (PDT)
Received: by 10.142.153.13 with HTTP; Fri, 18 May 2012 11:40:12 -0700 (PDT)
X-Originating-IP: [184.189.118.13]
In-Reply-To: <078191F9-4240-462D-8B71-178A8504FA2E@justatheory.com>
References: 
 <CAAS6=7iJuWF-4M1BTnYNsEWjWmrWT00kSYRpzYNzq9FuqUgbuw@mail.gmail.com>
	<97A7DC4C-8524-490F-92B6-1251A86DC1A8@justatheory.com>
	<CAAS6=7jWN0-Wv5wBnY_whKDE5ySXX25KeiKMwpjwVx+L3QpgiQ@mail.gmail.com>
	<2B79A5C0-4637-4EE0-93D7-1D5C9C6FF889@justatheory.com>
	<CAAS6=7i_c_n3mKRd+4o-aANPyas7zJo8DJJ=rYB0jWLfBDBnOw@mail.gmail.com>
	<078191F9-4240-462D-8B71-178A8504FA2E@justatheory.com>
Date: Fri, 18 May 2012 11:40:12 -0700
Message-ID: 
 <CAAS6=7gbR9DqPZu2ny+_JRwBDyna7Hi92Xcfza1Mx+R3o+XyQg@mail.gmail.com>
From: Marvin Humphrey <marvin@rectangular.com>
To: dev@lucy.apache.org
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
X-Gm-Message-State: 
 ALoCoQlho/pe3MS7tSodGJMa3o5shhGsUwFCuQoUHVdUc9dkMwx4LLDsn+NygbyHgDej2TYp2gMg
X-Virus-Checked: Checked by ClamAV on apache.org
Subject: Re: [lucy-dev] Markdown for documentation

On Thu, May 17, 2012 at 10:01 PM, David E. Wheeler
<david@justatheory.com> wrote:
> On May 17, 2012, at 11:18 PM, Marvin Humphrey wrote:

>> Perhaps we should consider reStructuredText as an alternative.
>
> That might be okay, though it is not as nice as Markdown in plain text.

reStructuredText is probably a little noisier to read, true.  But at least
they're both quite readable in comparison to HTML, or XML as used in C#
comments:

    http://broadcast.oreilly.com/2010/06/understanding-c-xml-comments.html

     /// <summary>
     /// The constructor sets the name, age and cash
     /// </summary>
     /// <param name=3D"name">The name of the guy</param>
     /// <param name=3D"age">The guy's age</param>
     /// <param name=3D"cash">The amount of cash the guy starts with</param=
>
     public Guy(string name, int age, int cash) {
          this.name =3D name;
          this.age =3D age;
          Cash =3D cash;
     }

>> =A0 =A0A DocuComment has two sections.
>>
>> =A0 =A0 =A0 =A0body
>> =A0 =A0 =A0 =A0 =A0 =A0Description, formatted in Markdown. =A0The first =
sentence must be a
>> =A0 =A0 =A0 =A0 =A0 =A0summary that can stand on its own. =A0Terminated =
by the first line
>> =A0 =A0 =A0 =A0 =A0 =A0which begins with an "@" character or by the end =
of the comment.
>>
>> =A0 =A0 =A0 =A0tags
>> =A0 =A0 =A0 =A0 =A0 =A0The comment may end with an optional tags block. =
=A0Each tag begins
>> =A0 =A0 =A0 =A0 =A0 =A0with a supported @label at the beginning of a lin=
e, and is
>> =A0 =A0 =A0 =A0 =A0 =A0terminated by either the next tag or the end of t=
he comment.
>
> Is this ReST? I don't recognize it as Markdown.

Haha, it's neither.  It's an actual proposal, formatted as plain text. I tr=
ied
to make it look like a definition list to please you. :)

> As I said, I am unfamiliar with the @param syntax. Is it part of Sundown?

Those @tags, including @param, @return, etc, are a convention used in Javad=
oc,
Scaladoc, Doxygen, and others.

    http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.ht=
ml#param
    https://wiki.scala-lang.org/display/SW/Tags+and+Annotations
    http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparam

The idea is to treat the comment as an object which has properties, rather
than as a single blob of markup.  That gives downstream renderers more choi=
ces
for output.  For example, we might choose to output each @param tag as a
bullet list, or as a definition list.

It's a powerful and elegant system -- but arguably another extension to
Markdown, if you want to see it that way.

However, there's more than one way to specify properties, as the C# XML sys=
tem
illustrates -- @tags are great, but it's not mandatory that we use that
particular syntax.

In reStructuredText, I think we can use "field lists":

    http://docutils.sourceforge.net/docs/user/rst/quickref.html#field-lists
    http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#fiel=
d-lists

Example:

    :param foo: A Foo.
    :param bar: A Bar.
    :return:    true on success, false on failure.

> =A0http://www.justatheory.com/computers/markup/markdown-table-rfc.html

For giggles, here's a version of your table example in reStructuredText:

    http://rst.ninjs.org/?n=3D4e1d41f32466afe278bd69c310d12cf1&theme=3Dbasi=
c

    +------+-------------+------------------------------+--------+
    |  id  |    name     |         description          | price  |
    +=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D+
    |    1 | gizmo       | Takes care of the doohickies |   1.99 |
    +------+-------------+------------------------------+--------+
    |    2 | doodad      | Collects *gizmos*            |  23.80 |
    +------+-------------+------------------------------+--------+
    |   10 | dojigger    | Handles:                     | 102.98 |
    |      |             |                              |        |
    |      |             | * gizmos                     |        |
    |      |             | * doodads                    |        |
    |      |             | * thingamobobs               |        |
    +------+-------------+------------------------------+--------+
    | 1024 | thingamabob | Self-explanatory, no?        |   0.99 |
    +------+-------------+------------------------------+--------+

> But of course, no table or definition list proposal (I had one of those,
> too) has been accepted.

reStructuredText has definition lists, too, FTR.

    http://docutils.sourceforge.net/docs/user/rst/quickref.html#definition-=
lists

Marvin Humphrey