Grant Proposal: Swim to Pod
Mon, 15-Sep-2014 by
_We have received the following grant application "Swim to Pod". Please leave feedback in the comments field by September 25th, 2014._
# Swim to Pod
- Ingy döt Net
- David Oswald
- Amount Requested
Provide Swim tools that allow Perl programmers to produce elaborate Pod
Provide all the functionality of Pod in a syntax better than Markdown.
Provide 5 plugins for extending Swim in ways useful to Perl people.
## Benefits to the Perl Community
Pod excels in providing a great __model__ for documentation. That means it
supports all (most of) the semantic concepts needed to write great docs. Where
Pod falls down is on syntax. The syntax is so verbose that common idioms (like
creating lists of lists) are often avoided because they are to hard to write.
Many Perl people use Markdown which offers simpler syntax, but lacks many of
the common semantic idioms in Pod. For instance, Markdown has no ability to do
'Data Definition' lists that are so common in CPAN docs (`dl/dt/dd` HTML
tags). Markdown is also weak in nesting semantic blocks.
This summer Ingy created Swim, after thinking about it and discussing it for 8
years. He has converted all the documentation in over 80 of his CPAN (and
other language) distributions. The result is incredibly easy to write and
maintain doc, all published to Pod for CPAN and GitHub rendering.
1. Tested support for full Pod semantics in Swim
2. Tools to convert Swim to Pod
- From `.swim` files
- From `.pm` files embedded
3. Provide 5 new Swim plugin modules
- Useful Perl/doc things
- Examples to write more
4. Module automation plugins for turning Swim to Pod
5. Pod-to-Swim conversion tool
## Project Details
Here are the things that Swim currently does:
- Supports all basic markup semantics
- Converts to Pod, HTML, Markdown, nroff (manpages) Text, DVI, PDF and more
- Extensible by plugins A Travis badge plugin is currently on CPAN
- Swim is Pegex based
- Defined by a readable (human friendly) grammar
1. Write tests for all the semantic capabilities of Pod.
2. Make basic `swim --to=pod` pass those tests.
3. Write a Pod parsing grammar for Pod-to-Swim tool.
4. Swim plugin module candidates:
- Unicode escapes `` ``
- HTML table support
- Video embedding
- Side-by-side comarison widget
- Syntax highlighting code blocks
5. Dist::Zilla plugin that transforms:
- from: `doc/My/Module.swim`
- or from: `lib/My/Module.pm`
- to: `lib/My/Module.pod`
## Project Schedule
This project will take 2 months and can be started immediately upon
## Completeness Criteria
Above modules released to CPAN with all functionality and tests in place.
Passing all tests.
Ingy döt Net has created markup languages in the past including the Kwiki wiki
markup and the Socialtext wiki markup. He is extremely familiar with parsing,
syntax and semantics issues in this space.
David Oswald has been a Perl user for over a decade, is an author of several
CPAN modules, and maintainer of more. David also runs Salt Lake Perl Mongers.
Ingy and David work well together and have decided to collaborate on a number
of projects that will benefit Perl and Software Development.
This document was written entirely in Swim and converted to Pod.
See these links:
- A complex Swim/Pod pair:
- Swim Grammar:
- Swim/Pod CPAN example:
Purely personal view:
I use either POD (where applicable) or Markdown (because itÂ´s the most widely supported document markup language) and theyÂ´ve usually been sufficient.
If for whatever reason I still wanted to use another markup language IÂ´d first have a look around for other languages with an already established followership: Org-mode, reStructuredText and AsciiDoc come to mind.
Unless the Swim authors come up with comparisons to these languages which clearly show why Swim would be superior I see no reason to fund the development of yet another document markup language...
I have several questions:
1) Other than by Ingy dÃ¶t Net, who else has used swim? Does this have cross-platform support, or are we suggesting something similar to pod, in that it will only be used within the Perl community?
2) Is this being suggested as a replacement for POD in the Perl core? If so, do we have buy-ins from the relevant people? Do we have general agreement that p5p thinks this is a good idea? What does the pumpking think? If this *isn't* being suggested as a replacement for pod in the Perl core, then why are we doing it?
3) What are the other competitors in this space. This document mentions Markdown, which has broad support from key programmer sites, e.g. github, stackoverflow, reddit.., and has many GUI tools and even books written about it. What does swim offer that wouldn't be better served by a markdown extensions?
While Swim may work well for the authors of this grant proposal, I do not see any compelling reason why this should be funded.
- Why Swim, the language? Markdown is much better known. Certain widely-used Markdown extensions such as Markdown Extra do support features like definition lists.
- Why Swim, in its current state of development? I looked at the current Swim docs, but couldn't even find a comprehensive overview of the syntax! In parts, the docs read like a vision document rather than like documentation or a specification. I therefore conclude that Swim isn't production ready at this time.
- Why Swim, the ecosystem? This proposal suggests a Swim-to-POD conversion mode. Why is this part of a swim tool that requires extra build steps? Why does it suggest new plugins for Dist::Zilla and Module::Install? Why doesn't it use existing infrastructure in the form of Pod::Elemental::Transformer that is used by Pod::Weaver which in turn has excellent integration with Dist::Zilla?
Thanks for the feedback! We've been using Swim to great effect personally, and got some positive feedback from a few notable CPAN authors, so we thought we should float it out there. While we're fairly certain we can make a solid case for Swim (and Perl), it's obvious that it's not yet ready to present for a grant in this fashion.
We'll go back to the planning board and make sure that these comments are well explained and supported before we propose this again.
We'll start by writing up a blog post that addresses much of the concern raised and link to that from another comment here.
Feel free to join #swimtext on freenode if you want to IRC chat about this project.
â€” Ingy and David
As this is about another markup language, I would see more value in a grant for an implementation of a CommonMark parser. CommonMark is a recent effort at writing a formal grammar for Markdown (because Markdown definition is ambiguous, and implementations have incompatibilities)