Mailing-List: contact lucy-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: lucy-dev@incubator.apache.org
Received-SPF: pass (athena.apache.org: local policy)
Date: Sat, 12 Mar 2011 16:21:42 -0800
From: Marvin Humphrey <marvin@rectangular.com>
To: lucy-dev@incubator.apache.org
Message-ID: <20110313002142.GA23132@rectangular.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.5.18 (2008-05-17)
Subject: [lucy-dev] Revise CustomQueryParser cookbook entry

Greets,

Thanks to the ruling at <https://issues.apache.org/jira/browse/LEGAL-86>, our
usage of Parse::RecDescent and JSON::XS no longer blocks Lucy's
0.1.0-incubating release.  Nevertheless, we plan to eliminate
Parse::RecDescent from Clownfish::Parser and JSON::XS from Lucy::Util::Json
sooner rather than later.  

Our only other usages of Parse::RecDescent are here:

    trunk/perl/lib/Lucy/Docs/Cookbook/CustomQueryParser.pod
    trunk/perl/sample/FlatQueryParser.pm

The two files are closely related; FlatQueryParser.pm is the end-product of
the Lucy::Docs::Cookbook::CustomQueryParser cookbook entry.

I propose to modify CustomQueryParser and by extension FlatQueryParser:

   1. Purge Parse::RecDescent.
   2. Shorten and improve the recipe.

Right now, these are the sub headings of CustomQueryParser:

    =head1 NAME

    =head1 ABSTRACT

    =head1 Grammar-based vs. hand-rolled

    =head1 The language

    =head1 Single-field regex-based parser

    =head1 Single-field Parse::RecDescent-based parser

    =head1 Multi-field Parse::RecDescent-based parser

    =head1 Extending the query language

    =head1 Usage

The revised version will focus on the specific capabilities of Lucy's
QueryParser, eliminating more general material on grammar-based parser
generators:

    =head1 NAME

    =head1 ABSTRACT

    =head1 The language

    =head1 Single-field parser

    =head1 Multi-field parser

    =head1 Extending the query language

    =head1 Usage

While we are apparently not legally required to remove usage of
Parse::RecDescent from our cookbook, I believe that as an ASF project, we
*should*.  Consider this William Rowe comment from the legal-discuss list in
April 2009, regarding the decision by the Apache Pivot project to migrate
sample code incorporating incompatibly licensed materials out of the ASF to an
outside site:

    http://s.apache.org/ctR

    Understanding that these are demos/examples, that's a substantially
    disappointing direction.  You pretty much ensure that the world can't
    really count on basing their code on the demos or examples without being
    locked into a copyleft schema (or questioning the providence of the code
    and again, being unable to use this).

All the better if we can eliminate such licensing concerns while improving the
quality of our documentation in a single initiative.

Marvin Humphrey