1Swim(3)               User Contributed Perl Documentation              Swim(3)
2
3
4

NAME

6       Swim - See What I Mean?!
7

VERSION

9       This document describes Swim version 0.1.46.
10

SYNOPSIS

12           > swim --to=pod doc/MyModule.swim > MyModule.pod
13
14           my $pod = Swim->new(file => "doc/MyModule.swim")->to_pod;
15

DESCRIPTION

17       Swim is a plain text markup language that converts to many formats:
18
19       ·   HTML
20
21           ·   Rich - Lots of classes and annotations
22
23           ·   Sparse - Just the tags and content
24
25           ·   Custom - HTML the way you want it
26
27       ·   MarkDown
28
29           ·   GitHub Flavored Markdown
30
31       ·   Pod
32
33       ·   Formatted Plain Text
34
35       ·   LaTeX
36
37       ·   DocBook
38
39       ·   Manpage
40
41       ·   AsciiDoc
42
43       ·   MediaWiki
44
45       The Swim framework is easily extensible, so adding new outputs is easy.
46
47   What Makes Swim Different
48       There are already a lot of text-to-html languages in the world. How is
49       Swim different?
50
51       Here are a few points:
52
53       ·   Very rich capabilities:
54
55           Swim aims to be a feature superset of the other markups since it
56           converts to all of them.
57
58           Most of the other markups don't support things like multiple
59           paragraphs in a bullet point (like you are reading right now!).
60
61       ·   Simple, consistent markup:
62
63           Even though Swim intends to be very rich, it will use a simple set
64           of syntax idioms to accomplish its tasks. One of my favorite
65           sayings comes from Larry Wall of Perl fame: "Make simple things
66           simple and hard things possible". Swim does just that (hopefully
67           without looking too much like Perl ;).
68
69       ·   Extensible:
70
71           Swim is easy to extend at many levels. You can add new backend
72           formats. You can also define your own markup syntaxes. You can even
73           define sections that parse using a different syntax grammar. For
74           instance, you could inline a markdown section like this:
75
76               <<< markdown
77               This is [Markdown](http://daringfireball.net/projects/markdown/) text.
78               >>>
79
80       ·   Multiple Implementations:
81
82           Swim is written using the Pegex parser framework. This provides 2
83           very powerful concepts. Firstly, that Swim language is defined in a
84           very simple PEG topdown grammar. That means it is easy to grok,
85           maintain and extend. Second, Pegex parsers work in many languages.
86           That means that you can use Pegex natively in languages like Ruby,
87           JavaScript, Perl, Python and many others.
88
89       ·   Comments and blank lines:
90
91           Most markups don't support comments and eat extra blank lines.
92           These things are useful. Swim not only supports comments, they are
93           part of the data model.  ie They get rendered as HTML (or comments
94           in other target languages that support comments). Swim also support
95           throwaway comments, for times when you want to hide part of a
96           document.
97
98   Syntax Concepts
99       Before diving into the actual markup syntax, let's discuss the concepts
100       that drive the decisions that Swim makes.
101
102       Most documents are just plain language using letters and numbers and a
103       few punctuation chars like comma, dash, apostrophe, parentheses and
104       colon. Also endings: period, exclamation point and question mark. We
105       leave those alone (at least in the normal prose context).
106
107       This leaves a bunch of punctuation characters that we can do special
108       things with. Namely: "@#$%^&*_=+|/~[]<>{}". Sometimes context matters.
109       For instance it is very rare for a prose line to start with a period,
110       so we can use that as a markup.
111
112       The important thing in all this is that we be able to reverse the
113       meaning for edge cases. ie We need a way to make markup characters be
114       viewed as regular characters. Swim uses a backslash before a character
115       to make it not be seen as markup. For instance this text "*not bold*"
116       is not bold because it was written like this: "\*not bold\*".
117
118       Swim has a document model that views things as blocks and phrases. This
119       is very similar to HTML's DIV and SPAN concepts. Swim views a document
120       as a sequence of top level blocks. Blocks are further subdivided into
121       either a sequence of blocks or a sequence of phrases. Phrases can only
122       be subdivided into more phrases.
123
124       Consider this example document:
125
126           A paragraph *is* a block. It gets divided into phrases like 'pure text' and
127           *bold text*. A bold phrase can be divided: *all bold /some italic/*.
128
129           * Lists are blocks.
130           * Each item is a block.
131             * A sublist is a block.
132             * The text within in contains *phrases*.
133
134       Common blocks and phrases have an implicit (DWIM) syntax, that reads
135       very natural. For instance a paragraph is just left justified text that
136       is terminated by a blank line. There is also an explicit syntax for
137       blocks and phrases. Every implicit syntax can be written explicitly.
138       For instance, here is an implicit syntax example followed by its
139       explicit equivalent:
140
141           A paragraph with some *bold text* in it.
142
143           <<< para
144           A paragraph with some <bold bold text> in it.
145           >>>
146
147       Two Space Indent
148
149       Swim uses a 2 space indentation and it is very instrumental to its
150       design. It allows for a very nice and natural embedding of blocks
151       within blocks. Consider this list:
152
153           * Point one has
154             text on 2 lines
155             * Subpoint a
156           * Point two
157
158             A paragraph for point 2 followed by some preformatted text:
159               # Code example
160           * Point three
161
162       As you can see, 2 space indent is very natural here and allows for
163       putting blocks inside blocks in a way that is not available in most
164       markups.
165
166   Swim Syntax
167       There are 4 sets of syntax to define: block/implicit, phrase/implicit,
168       block/explicit and phrase/explicit. There are also escaping mechanisms.
169
170       Block/Implicit Syntaxes
171
172       A paragraph is a contiguous set of plain text lines. It is terminated
173       by a blank line or by another block syntax at that level.
174
175       To be continued
176

AUTHOR

178       Ingy döt Net <ingy@cpan.org>
179
181       Copyright 2014-2017. Ingy döt Net.
182
183       This program is free software; you can redistribute it and/or modify it
184       under the same terms as Perl itself.
185
186       See <http://www.perl.com/perl/misc/Artistic.html>
187
188
189
190perl v5.28.1                      2017-02-12                           Swim(3)
Impressum