GSoC 2011 proposal (draft)

gistfile1.tex

\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}

\title{GSoC 2011 Proposal – Pod parser for Rakudo}

\begin{document}

Tadeusz Sośnierz \\
tadzikes@gmail.com \\
Pod parser for Rakudo

\section{Abstract}

Write a Perl 6 Pod parser for Rakudo, being capable of generating the
documentation from the Perl 6 code as well as accesing the documentation
from the Perl 6 code itself.

\section{Benefits to the Perl/Open Source Community}

Synopsis 26, which specifies the Perl 6 Pod format, is an obligatory
part of a complete Perl 6 implementation. Right now Pod is silently
ignored in Rakudo, while it should be accessible as an attribute of
almost every object in the code. A Pod parser in Rakudo will also open
a way to numerous userspace tools for generating formatted
documentation, testing the docs coverage etc.

\section{Deliverables}

\begin{itemize}

\item Rakudo recognizes Pod in the Perl code as something more than
a comment, parses it and produces the syntax tree, which can be used
to generate the documentation in some other format like XHTML, TeX etc. 
There is an output generator in Rakudo producing the plaintext output.

\item The contents of Declarator Blocks are added to the compiled code
and accessible via the .WHY method of an object, which is also
spectested.

\item The Pod parser from Rakudo can be used in a Perl 6 code.

\end{itemize}

\section{Project Details}

There are already a few Perl 6 Pod parsers available:
Perl6::Perldoc::Parser and Perl6::Pod for Perl 5, and Pod::Parser
for Perl 6. What makes my project different is that
it's not a separate parser module, but a significant part of the
Rakudo compiler itself, thus opening the way for making Declarator
Blocks accesible at runtime. Rather than concentrating on the
userspace tools to generate output, this projects aims for a
comprehensive and well-tested Pod parser, fulfilling the Synopsis 26.
Of course having a good implementation will make it possible to write
a documentation generators like a perldoc utility, or for displaying
the module reference for a Perl 6 module website, like
modules.perl6.org or (one day) CPAN. The project also features fixing
and extending Synopsis 26 if there is a need to do this.

The idea is to develop the parser as a separate class at the beginning,
mainly to reduce the compilation time in the early stage of development,
but also to make the biggest possible amount of code reuseable by the
other implementations of Perl 6. Still, the most important goal of the
project is a parser included and integrated with Rakudo

If anything comes bad and the project won't end up as expected, there is
no possible chance that the Rakudo project will stay empty-handed. If
not all the features will be  implemented, there will be a specified and
well-tested codebase possible to pick up and extend.

If the project gets finished earlier, and I will have time to write
something more, I would like to work on some userspace tools mentioned
earlier, to improve the experience of not only the developers, but the
users too.

\section{Project Schedule}

\begin{itemize}

\item \textbf{Week \#1-2,} 24 – 28 May

That week is still my exam session on the University. No work will
probably be done then. The exam session ends on May 30th, so that
affects the second week too.

\item \textbf{Week \#2,} 29 May – 4 June

Write classes that represent POD AST nodes, along with tests to
construct them and extract information from them. Analyze Perl 5 module
Perl6::Pod and regular Rakudo AST nodes as a potential source of
inspiration.

\item \textbf{Week \#3,} 5 – 11 June

Make Rakudo able to parse the paragraph blocks and the abbreviated
blocks in addition to delimeted block which it can parse now. Write
extensive tests for that.

\item \textbf{Week \#4,} 12 – 18 June

Make the specialized blocks (code, comment, list) parsed correctly.
Add tests for those.

\item \textbf{Week \#5,} 19 – 25 June

Implement parsing one-letter blocks (B<>, I<>, L<> etc.) and nesting
them. Add tests.

\item \textbf{Week \#6,} 26 June – 2 July

Implement tables and as much of the spec as possible for the next week.
Write a tests for tables and what was implemented.

\item \textbf{Week \#7,} 3 – 8 July

Make sure that the are tests for the whole spec.
The parser should pass at least 80\% of it at this moment.

\item \textbf{Week \#8,} 10 – 16 July

Make the parse results accessible in the \$=POD variable.
Prepare the Midterm report, describe the status of the project
and further plans.

\item \textbf{MIDTERMS}

\item \textbf{Week \#9,} 17 – 23 July

Make the documentation for classes, methods and subroutines accesible
with the .WHY method. Add a spectests for that.

\item \textbf{Week \#10,} 24 – 30 July

Make Rakudo capable of firing the DOC phasers (DOC use, DOC INIT).
Write a basic output generator for the --doc command-line option.

\item \textbf{Week \#11,} 31 July – 6 August

Complete the output generator, implement the --doc command-line option
and document it in Rakudo docs.

\item \textbf{Week \#12,} 7 – 13 August

Make sure that the Pod parser is accesible in the Perl 6 code and
document its usage.

\item \textbf{Week \#13,} 14 – 22 August

Finish what was left undone, make sure the tests are well-written,
the coverage is high
and the documentation covers every aspect of a project.
\end{itemize}

\section{References and Likely Mentors}

I have spoken to Moritz Lenz, Carl Masak and Martin Berends about the
project, from whom the first two are listed as a mentors for this task.
They gave me excellent feedback clearing up my doubts and showing me
the most important and desired parts of the task.

\section{License}

The project, being the part of the Rakudo compiler, will be licensed
under the same terms as Rakudo itself.

\section{Bio}

My name is Tadeusz Sośnierz, I am on a second year of Computer Science
on Warsaw University of Technology in Poland. I have been using Perl 6
and Rakudo since spring 2010, publishing my Perl 6 code since July
that year. I am involved in the module management, I am an author of
neutro (now abandoned), and Panda, the only working module manager
for Perl 6. I'm also an author of numerous modules
(File::Find, Term::ANSIColor, Config::INI) and contributed to many
others (including JSON, Web, HTTP::Server::Simple and Yapsi).
I am a Rakudo contributor since autumn 2010, and I was a release
manager in January 2011. The experience in working with Rakudo and Perl
6 itself, and knowing Rakudo's capabilities and limitations makes me
a good candidate to work on this project.

Besides Perl and Perl 6, I'm involved in
the Parrot project, I have contributed to Cardinal, the Ruby compiler
for Parrot. I am also proficient with the C programming language.

\section{Eligibility}

I am an eligible student with paperwork to prove it if necessary.

\end{document}

gistfile1.txt

Tadeusz Sośnierz
tadzikes@gmail.com
Pod parser for Rakudo

1 Abstract

Write a Perl 6 Pod parser for Rakudo, being capable of generating the documentation from the Perl 6 code as well as accesing the documentation from the
Perl 6 code itself.

2 Benefits to the Perl/Open Source Community

Synopsis 26, which specifies the Perl 6 Pod format, is an obligatory part of a
complete Perl 6 implementation. Right now Pod is silently ignored in Rakudo,
while it should be accessible as an attribute of almost every object in the code.
A Pod parser in Rakudo will also open a way to numerous userspace tools for
generating formatted documentation, testing the docs coverage etc.

3 Deliverables
• Rakudo recognizes Pod in the Perl code as something more than a comment, parses it and produces the syntax tree, which can be used to generate
the documentation in some other format like XHTML, TeX etc. There is
an output generator in Rakudo producing the plaintext output.
• The contents of Declarator Blocks are added to the compiled code and
accessible via the .WHY method of an object, which is also spectested.
• The Pod parser from Rakudo can be used in a Perl 6 code.

4 Project Details

There are already a few Perl 6 Pod parsers available: Perl6::Perldoc::Parser and
Perl6::Pod for Perl 5, and Pod::Parser for Perl 6. What makes my project different is that it’s not a separate parser module, but a significant part of the Rakudo
compiler itself, thus opening the way for making Declarator Blocks accesible at
runtime. Rather than concentrating on the userspace tools to generate output,
this projects aims for a comprehensive and well-tested Pod parser, fulfilling the
Synopsis 26. Of course having a good implementation will make it possible to
write a documentation generators like a perldoc utility, or for displaying the
module reference for a Perl 6 module website, like modules.perl6.org or (one
day) CPAN. The project also features fixing and extending Synopsis 26 if there
is a need to do this.

The idea is to develop the parser as a separate class at the beginning, mainly
to reduce the compilation time in the early stage of development, but also to
make the biggest possible amount of code reuseable by the other implementations of Perl 6. Still, the most important goal of the project is a parser included
and integrated with Rakudo
If anything comes bad and the project won’t end up as expected, there is no
possible chance that the Rakudo project will stay empty-handed. If not all the
features will be implemented, there will be a specified and well-tested codebase
possible to pick up and extend.
If the project gets finished earlier, and I will have time to write something
more, I would like to work on some userspace tools mentioned earlier, to improve
the experience of not only the developers, but the users too.

5 Project Schedule

• Week #1-2, 24 – 28 May
Write classes that represent POD AST nodes, along with tests to construct them and extract information from them. Analyze Perl 5 module
Perl6::Pod and regular Rakudo AST nodes as a potential source of inspiration.

• Week #2, 29 May – 4 June
Make Rakudo able to parse the paragraph blocks and the abbreviated
blocks in addition to delimeted block which it can parse now. Write extensive tests for that.

• Week #3 and #4, 5 – 14 June
Make the specialized blocks (code, comment, list) parsed correctly. Add
tests for those.

• 15 – 30 June (Week #5 and #6) is my exam session at the university.
No work will probably be done then.

• Week #7, 1 – 8 July
Implement parsing one-letter blocks (B<>, I<>, L<> etc.) and nesting
them. Implement tables. Write tests for the implemented things.

• Week #7, 3 – 8 July
Make sure the test suite covers the whole spec. Fix any slips caused by
the exam session.

• Week #8, 10 – 16 July
Make the parse results accessible in the $=POD variable. Prepare the
Midterm report, describe the status of the project and further plans.

• MIDTERMS

• Week #9, 17 – 23 July
Make the documentation for classes, methods and subroutines accesible
with the .WHY method. Add a spectests for that.

• Week #10, 24 – 30 July
Make Rakudo capable of firing the DOC phasers (DOC use, DOC INIT).
Write a basic output generator for the –doc command-line option.

• Week #11, 31 July – 6 August
Complete the output generator, implement the –doc command-line option
and document it in Rakudo docs.

• Week #12, 7 – 13 August
Make sure that the Pod parser is accesible in the Perl 6 code and document
its usage.

• Week #13, 14 – 22 August
Finish what was left undone, make sure the tests are well-written, the
coverage is high and the documentation covers every aspect of a project.

6 References and Likely Mentors

I have spoken to Moritz Lenz, Carl Masak and Martin Berends about the
project, from whom the first two are listed as a mentors for this task. They
gave me excellent feedback clearing up my doubts and showing me the most
important and desired parts of the task.

7 License

The project, being the part of the Rakudo compiler, will be licensed under the
same terms as Rakudo itself.

8 Bio

My name is Tadeusz Sośnierz, I am on a second year of Computer Science on
Warsaw University of Technology in Poland. I have been using Perl 6 and
Rakudo since spring 2010, publishing my Perl 6 code since July that year. I am
involved in the module management, I am an author of neutro (now abandoned),
and Panda, the only working module manager for Perl 6. I’m also an author of
numerous modules (File::Find, Term::ANSIColor, Config::INI) and contributed
to many others (including JSON, Web, HTTP::Server::Simple and Yapsi). I
am a Rakudo contributor since autumn 2010, and I was a release manager in
January 2011. The experience in working with Rakudo and Perl 6 itself, and
knowing Rakudo’s capabilities and limitations makes me a good candidate to
work on this project.
Besides Perl and Perl 6, I’m involved in the Parrot project, I have contributed
to Cardinal, the Ruby compiler for Parrot. I am also proficient with the C
programming language.

9 Eligibility

I am an eligible student with paperwork to prove it if necessary.

I know I'm not a TPF mentor, but I can offer a little bit of feedback anyway.

Timelines are important, add a lot more detail here. What are the specific milestones and deliverables each week? Can you define a success/fail metric for each week, or at least most weeks? This will help out during the summer to gauge whether you are on target or not. Also, how does your work on testing and documentation overlap with the code work you've outlined? You can either mention that a code feature is not "complete" until it's properly documented and tested, or you can mention explicit test and documentation goals for each week, in addition to your code goals.

It's good to have some overflow weeks at the end of the project in case things start going extremely badly. It's equally good to include a list of additional features which you could pursue to fill time if things are going very well. A short list of optional features with estimates of implementation effort would help inform you and your mentor about what to pursue if you have completed your primary objectives.

Good luck with your proposal and (I hope) your project!