Swim - See What I Mean?!

This is a basic Info doc for the Swim markup language.

Swim is a new text markup language in the line of Markdown and wiki markups. It's goals are:

• Superset of all common markup models

• Generate other markups: HTML, Markdown, Pod, ReST, nroff(manpage)

• Generate binary: MSWord, PDF, DVI

• Best-of syntax for most common things

• Generic extension syntax for other stuff

• More nestable than typical markups

  • ie things like Lists of tables of code

• Defined by a nice top-down PEG (grammar)

• (Identical) Implementations in (at least) Perl, Ruby, JavaScript

• Plugin architecture to support more extravagant things

• Support various domains including:

  • Documentation

  • Blogs

  • Articles

  • Books

This document is a very high level overview, with pointer to more info:

Swim in the Wild

Here are some rather complex Swim documents in the wild (with output in Pod for viewing on GitHub):

• https://github.com/ingydotnet/git-hub/blob/master/doc/git-hub.swim

  • https://github.com/ingydotnet/git-hub#readme

• https://github.com/ingydotnet/swim-pm/blob/master/doc/Swim.swim

  • https://github.com/ingydotnet/swim-pm#readme

I'll add more soon.

Extension Markup

Simple things like bold italic _underline_ --strike-- and code are done:

Simple things like *bold* /italic/ _underline_ --strike-- and `code` are done:

NOTE: If you are looking at the Pod translation, Pod can't support strikethrough, afaict.

There is also a generic syntax that these things and more can be done with:

<name arguments go here>

For instance this:

is made with:

<badge travis coveralls ingydotnet/swim-pm>

Also things like <bold bold text> can be done explicitly:

Also things like <bold bold text> can be done explicitly:

The block extension syntax is:

<<< name arguments go here
text for extension
>>>

This is in keeping with various 1-char / 3-char syntaxes out there like GitHub-flavored Markdown's:

Some `code`:

```
some code
```

Or CoffeeScript's:

# Line comment

###
Block
comment
###

str =~ /regexp/
str =~ ///
  multiline
  regex
///

or Python's:

s = "string"
s = """
multiline
string
"""

Plugins

The main Swim implementation is:

• https://metacpan.org/release/Swim

And the one plugin so far is:

• https://metacpan.org/release/Swim-Plugin-badge

The Swim Grammar

Swim is defined by a Pegex (PEG) grammar here:

• https://github.com/ingydotnet/swim-pgx/blob/master/swim.pgx

This affords:

• Pegex can more easily be implemented in several languages

• New features can be added in one place

• Bugs can be fixed in one place

Swim to Pod on CPAN

All of the CPAN modules listed here have had their Pod turned into Swim in their source code. It gets turned back into nearly the original Pod when the modules go to CPAN.

If you clone one of these repos, try running these commands:

make cpan

This creates a CPAN directory, that is Dist::Zilla ready. All the Swim is now Pod.

make dist

Create the package that is ready for CPAN.

make help

More cool make targets.

Of Interest

The markup for multiple blank lines is...

multiple blank lines!