1Swim(3)               User Contributed Perl Documentation              Swim(3)
2
3
4
5<<<cpan-head>>>
6

SYNOPSIS

8           > swim --to=pod doc/MyModule.swim > MyModule.pod
9
10           my $pod = Swim->new(file => "doc/MyModule.swim")->to_pod;
11

DESCRIPTION

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