Project and Google Summer of Code

[marbux]

Hi, all,

In reviewing the history of the discussion leading us to what now
seems to be tentatively named the reborn Kepler Project to assemble
some notes, I discovered that its origin was a discussion on lua-l
about possible Google Summer of Code projects. Is there anything in
the new project that would benefit from a Google SOC scholarship? If
so, we need to define it and get an application in. Quoting from a
post by Eric Wing:

So the application process starts this Monday (March 18) and is open
until March 29. Are we serious about trying this, this year?

If so, we need a mentoring organization, administrators, project
proposals written up, and mentors.

Main page:
http://www.google-melange.com/gsoc/homepage/google/gsoc2013

About page:
http://www.google-melange.com/gsoc/document/show/gsoc_program/google/gsoc2013/about_page

FAQ:
http://www.google-melange.com/gsoc/document/show/gsoc_program/google/gsoc2013/help_page

Best regards,

Paul

[Hisham]

On 25 March 2013 00:47, marbux <mar...@gmail.com> wrote:
> Hi, all,
>
> In reviewing the history of the discussion leading us to what now
> seems to be tentatively named the reborn Kepler Project to assemble
> some notes, I discovered that its origin was a discussion on lua-l
> about possible Google Summer of Code projects. Is there anything in
> the new project that would benefit from a Google SOC scholarship? If
> so, we need to define it and get an application in. Quoting from a
> post by Eric Wing:
>
> So the application process starts this Monday (March 18) and is open
> until March 29. Are we serious about trying this, this year?
>
> If so, we need a mentoring organization, administrators, project
> proposals written up, and mentors.

We've noticed this and we've been discussing it at PUC.

[ Oh, to add one more item to the salad of names, projects, etc: we
have a research lab at PUC called LabLua, which is the actual physical
lab where I hang out. This is our very outdated website (which has
been in need of an overhaul for a while):
http://www.lua.inf.puc-rio.br/ ]

A fellow PhD student at LabLua is really interested in being a GSoC
student this year, and wants to get more involved with Lua open source
development. He's been asking people around here about the GSoC thing
-- everyone seems to like the idea, but we don't know exactly how to
proceed yet: starting from what organization should we present
ourselves as (Lua.org? LabLua? Lua? ...Kepler?) Then there's questions
of who would mentor, which are the tasks, how could the Lua community
beyond PUC be involved, etc.

I don't know yet to which extent the Lua team would be involved in
this. My impression is that they're already swamped with activities,
so most likely we would at best get their blessing to use a somewhat
official name such as LabLua, but then we'd have to figure out the
rest by ourselves.

I haven't look closely into this myself, but I spoke to another prof
at PUC who's involved with Lua (Ana Lucia de Moura, some of you might
remember her name from the TOPLAS paper on coroutines) and she offered
to help.

So, long story short, if you guys think it would be helpful to get a
PUC connection for GSoC, I can try to get the gears going down here in
Rio. (I just don't want us to hold things back with university
bureaucracy, of course.)

-- Hisham

[marbux]

Thanks, Hisham.

Although I don't know if we could pull together a sufficiently
detailed product specification in time for a proposal submitted by
March 29, the biggest hole I'm seeing at the moment in our
hypothesized software map is the software for the documentation
component.

We have three major tools that seem to be the most widely used so far:

-- LuaDoc (abandoned project) [1]
-- LDoc (successor to LuaDoc and mostly compatible with LuaDoc input) [2]
-- WebBook (PUC-RIO documentation tool) [3]

There seems to be consensus so far that we want to arrive at a
standardized input and ouput of documentation so that we might, for
example:

1. Make a module of all modules' documentation that could be
separately downloaded and navigated;
2. A coresponding web site, web both the web site and the module
updated as needed by the CI process;
3. Conversion of the output reference format to a variety of formats
has also been mentioned as a requirement. Existing multiplatform
converters such as Pandoc [4] might play a role here.

The LDoc and WebBook inputs and outputs are incompatible. LDoc works
from documentation embedded in code comments, accepting either HTML or
Markdown for inline formatting, and outputs HTML+CSS to achieve a
sidebar table of contents plus a main content area that displays the
currently selected item's content. WebBook works from aggregated HTML
documents to produce a table of contents side bar in an HTML/CSS frame
with other frames that add some goodies, eg., java-script-based
search. Another difference is that WebBook enables a nested table of
contents while I've seen nothing but a plain list in LDoc. One major
drawback of WebBook is that because of its use of frames, annotation
by the user is difficult.

My sense is that we have agreement that we need a standard for
documentation and the means to implement it. But we have not discussed
thus far what that standard might be, how to implement it, and whether
the implementation might include conversion from LuaDoc, LDoc, or
WebBook. That is why I think we might have difficulty pulling together
a proposal before March 29.

On the other hand, if part of the project were to identify specific
product requirements, then a more general description of requirements
would be possible and we might then meet that deadline.

If we could, there are reasons to suspect that such a proposal might
be well received at Google if we emphasize:

-- Lua's under-publicized popularity;

-- The need for standardized documentation for Lua modules, in
conjunction with the Kepler Project's goal of package distribution.

-- The old Kepler project's web component modules (anything that
generates web pages is good for Google's business); and

-- The resulting opportunities for Google's products to process the
standardized documentation to better serve Lua users, e.g., syntax
highlighting, searching function definitions, etc.

-- Other?

Best regards,

Paul


[1] http://keplerproject.github.com/luadoc/
[2] https://github.com/stevedonovan/LDoc
[3] http://www.tecgraf.puc-rio.br/webbook/
[4] http://johnmacfarlane.net/pandoc/

[steve donovan]

On Mon, Mar 25, 2013 at 9:08 AM, marbux <mar...@gmail.com> wrote:
> My sense is that we have agreement that we need a standard for
> documentation and the means to implement it. But we have not discussed
> thus far what that standard might be, how to implement it, and whether
> the implementation might include conversion from LuaDoc, LDoc, or
> WebBook. That is why I think we might have difficulty pulling together
> a proposal before March 29.

It seems a tricky candidate for a GSoC project, which should ideally
be a focussed piece of technical work (as in a higher degree).

Documentation is a social problem. It also involves a great deal of
kludging, since we're usually grateful for _any_ documentation.

Lua module writers are basically cats; they dislike filling in forms,
using an 'approved' documentation system, and so forth. Not a
criticism, just an observation.

A better candidate IMHO would be a non-trivial binding to a useful library.

steve d.

[marbux]

On Mon, Mar 25, 2013 at 12:36 AM, steve donovan
<steve.j...@gmail.com> wrote:

> Documentation is a social problem. It also involves a great deal of
> kludging, since we're usually grateful for _any_ documentation.
>
> Lua module writers are basically cats; they dislike filling in forms,
> using an 'approved' documentation system, and so forth. Not a
> criticism, just an observation.

Sure. And no one likes to expend effort on a different way to do
things when the present method "works well enough for me." I agree
it's largely a social problem.

> A better candidate IMHO would be a non-trivial binding to a useful library.

Any libraries to suggest?

Best regards,

Paul