[prev in list] [next in list] [prev in thread] [next in thread] 

List:       lua-l
Subject:    Re: Lua library bank?
From:       marbux <marbux () gmail ! com>
Date:       2013-03-10 7:56:24
Message-ID: CAJ1g4g_cfLSEZd6a4q94jM=sqvUyXZ=O=opu7VJ_B+mSM5GofQ () mail ! gmail ! com
[Download RAW message or body]

On Sat, Mar 9, 2013 at 9:18 PM, Dirk Laurie <dirk.laurie@gmail.com> wrote:

> Let's turn it into a constructive proposal.
>
> 1.  Once the debate on your guidelines (there is bound to be some
>     disagreement — this is lua-l!) has settled down, we start a page
>     LibraryBank (or whatever) linked to LuaAddons on LuaWiki saying:
>     these are the guidelines, and here is a list of modules claimed to
>     conform to them, each complete with a short description and a link
>     that takes you to the repository where it can be found.
>
> 2.  The normal dynamics of a Wiki maintains that page: anyone may add a
>     new item: the developer, an enthusastic user, anyone. Since LuaWiki
>     does not have Talk pages, negative experiences should just be added
>     by the dissatisfied user (keep it short: "last updated February
>     2009", "fails to build on Solaris" etc.).
>
> 3.  Software developers can consult that page before releasing their
>     software to decide whether to aim for those standards. We must not
>     be too strict: we should not exclude software which, for a good and
>     unavoidable reason, fails to follow some particular guideline. For
>     example: we may decide that all modules written in C should conform
>     to the same standard of general portability as the Lua source code,
>     but someone may write software for which C99 is essential. Such a
>     transgression should not be grounds for exclusion, as long as it
>     is clearly stated and well motivated.

RFC 2119 [1] (requirements keywords) covers that pretty well in its
definition of "SHOULD" and in paragraph 6, although it would take an
additional provision to add the disclosure requirement.  Specifying
the reason for the departure might also be added as a requirement as
an aid to the potential user's evaluation of the module's suitability
for their purpose.

I've got some experience in writing normative language and could
assist to that extent.

> 4.  We could design our own .css style for documentation, different
>     enough from PUC-Rio's style to make confusion unlikely, but used for
>     all software that makes the LibraryBank grade. Authors could provide
>     documentation in Markdown to make the HTML conversion automatic.

My major technical "want" on documentation is that it be easily
editable for annotations. I'm currently unwinding PUC-Rio's
HTML-framed documentation for IUP so that I can annotate it; it's a
PITA. So no frames, please.

Best regards,

Paul

___

[1] <http://www.ietf.org/rfc/rfc2119.txt>

[prev in list] [next in list] [prev in thread] [next in thread]