-
Notifications
You must be signed in to change notification settings - Fork 293
/
pod.pod6
557 lines (379 loc) · 14.7 KB
/
pod.pod6
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
=begin pod :tag<perl6>
=TITLE Perl 6 Pod
=SUBTITLE An easy-to-use markup language
Pod is an easy-to-use markup language. Pod can be used for writing language
documentation, for documenting programs and modules, as well as for
other types of document composition.
Every Pod document has to begin with C<=begin pod> and end with C<=end pod>.
Everything between these two delimiters will be processed and used to generate documentation.
=begin code
=begin pod
A very simple Perl 6 Pod document
=end pod
=end code
=head1 Block Structure
A Pod document may consist of multiple Pod blocks.
There are four ways to define a block (delimited, paragraph, abbreviated, and declarator);
the first three yield the same result but the fourth differs.
You can use whichever form is most convenient for your particular documentation task.
=head2 Delimited blocks
Delimited blocks are bounded by C<=begin> and C<=end> markers, both of
which are followed by a valid Perl 6 identifier, which is the
C<typename> of the block. Typenames that are entirely lowercase (for
example: C<=begin head1>) or entirely uppercase (for example: C<=begin
SYNOPSIS>) are reserved.
=begin code
=begin head1
Top Level Heading
=end head1
=end code
=head3 Configuration information
After the typename, the rest of the C<=begin> marker line is treated as
configuration information for the block. This information is used in
different ways by different types of blocks, but is always specified using
Perl6-ish option pairs. That is, any of:
=begin table
Value is... Specify with... Or with... Or with...
=============== =================== ============== ===========
List :key[$e1, $e2, ...] :key($e1, $e2, ...)
Hash :key{$k1=>$v1, $k2=>$v2}
Boolean (true) :key :key(True) :key[True]
Boolean (false) :!key :key(False) :key[False]
String :key<str> :key('str') :key("str")
Int :key(42) :key[42]
Number :key(2.3) :key[2.3]
=end table
Where '$e1, $e2, ...' are list elements of type String, Int, Number, or
Boolean. Lists may have mixed element types. Note that one-element
lists are converted to the type of their element (String, Int, Number, or
Boolean). Also note that "bigints" can be used if required.
For hashes, '$k1, $k2, ...' are keys of type Str and '$v1, $2, ...'
are values of type String, Int, Number, or Boolean.
Strings are delimited by single or double quotes. Whitespace is insignificant outside
of strings. Hash keys need not be quote-delimited unless they contain
significant whitespace.
All option keys and values must, of course, be constants since Pod is a
specification language, not a programming language. Specifically, option
values cannot be closures. See Synopsis 2 for details of the various
Perl 6 pair notations.
The configuration section may be extended over subsequent lines by
starting those lines with an C<=> in the first (virtual) column followed
by a whitespace character. (NOTE: This feature is not yet implemented.
All configuration information currently must be provided on the same
line as the C<=begin> marker line.)
=head2 Paragraph blocks
Paragraph blocks begin by a C<=for> marker and end by
the next Pod directive or the first blank line.
The C<=for> marker is followed by the typename of the block.
=begin code
=for head1
Top Level Heading
=end code
=head2 Abbreviated blocks
Abbreviated blocks begin by an C<'='> sign, which is followed immediately by the typename of the
block. The block ends at the next Pod directive or the
first blank line.
=begin code
=head1 Top Level Heading
=end code
=head2 Declarator blocks
Declarator blocks differ from the others by not having a specific type,
instead they are attached to some source code.
Declarator blocks are introduced by a special comment: either C<#=> or C<#|>,
which must be immediately followed by either a space or an opening bracket.
If followed by a space, the block is terminated by the end of line;
if followed by one or more opening brackets, the block is terminated by the matching
sequence of closing brackets.
Blocks starting with C<#|> are attached to the code after them,
and blocks starting with C<#=> are attached to the code before them.
Since declarator blocks are attached to source code, they can be used to document
classes, roles, subroutines etc.
The C<WHY> method can be used on these classes, roles, subroutines etc. to return the attached Pod value.
=begin code :skip-test
#| Base class for magicians
class Magician {
has Int $.level;
has Str @.spells;
}
#| Fight mechanics
sub duel(Magician $a, Magician $b) {
}
#= Magicians only, no mortals.
say Magician.WHY; # OUTPUT: «Base class for magicians»
say &duel.WHY.leading; # OUTPUT: «Fight mechanics»
say &duel.WHY.trailing; # OUTPUT: «Magicians only, no mortals.»
=end code
=head1 Block types
Pod offers a wide range of standard block types.
=head2 Headings
Headings can be defined using C<=headN>,
where N is greater than zero (e.g., C<=head1>, C<=head2>, …).
=begin code
=head1 A Top Level Heading
=head2 A Second Level Heading
=head3 A Third Level Heading
=end code
=head2 Ordinary paragraphs
Ordinary paragraph consist of text that is to be formatted into a document at the current level of nesting,
with whitespace squeezed, lines filled, and any special inline mark-up applied.
Ordinary paragraphs consist of one or more consecutive lines of text,
each of which starts with a non-whitespace character.
The paragraph is terminated by the first blank line or block directive.
For example:
=begin code :skip-test
=head1 This is a heading block
This is an ordinary paragraph.
Its text will be squeezed and
short lines filled. It is terminated by
the first blank line.
This is another ordinary paragraph.
Its text will also be squeezed and
short lines filled. It is terminated by
the trailing directive on the next line.
=head2 This is another heading block
This is yet another ordinary paragraph,
at the first virtual column set by the
previous directive
=end code
Ordinary paragraphs do not require an explicit marker or delimiters.
Alternatively, there is also an explicit C<=para> marker that can be used to explicitly mark a paragraph.
=begin code
=para
This is an ordinary paragraph.
Its text will be squeezed and
short lines filled.
=end code
In addition, the longer C<=begin para> and C<=end para> form can be used.
For example:
=begin code
=begin para
This is an ordinary paragraph.
Its text will be squeezed and
short lines filled.
This is still part of the same paragraph,
which continues until an...
=end para
=end code
As demonstrated by the previous example, within a delimited C<=begin para> and C<=end para> block, any blank lines are preserved.
=head2 Code blocks
Code blocks are used to specify source code, which should be rendered without re-justification,
without whitespace-squeezing, and without recognizing any inline formatting codes.
Typically these blocks are used to show examples of code, mark-up,
or other textual specifications, and are rendered using a fixed-width font.
A code block may be implicitly specified as one or more lines of text,
each of which starts with a whitespace character.
The implicit code block is then terminated by a blank line.
For example:
=begin code :skip-test
This ordinary paragraph introduces a code block:
my $name = 'John Doe';
say $name;
=end code
Code blocks can also be explicitly defined by enclosing them in C<=begin code> and C<=end code>
=begin code
=begin code
my $name = 'John Doe';
say $name;
=end code
=end code
=head2 I/O blocks
Pod provides blocks for specifying the input and output of programs.
The C<=input> block is used to specify pre-formatted keyboard input,
which should be rendered without re-justification or squeezing of whitespace.
The C<=output> block is used to specify pre-formatted terminal or file output,
which should also be rendered without re-justification or whitespace-squeezing.
=head2 Lists
=head3 Unordered Lists
Lists in Pod are specified as a series of C<=item> blocks.
For example:
=begin code :skip-test
The three suspects are:
=item Happy
=item Sleepy
=item Grumpy
=end code
The three suspects are:
=item Happy
=item Sleepy
=item Grumpy
=head3 Multi-level Lists
Lists may be multi-level, with items at each level specified using the C<=item1>, C<=item2>, C<=item3>, etc. blocks.
Note that C<=item> is just an abbreviation for C<=item1>.
For example:
=begin code
=item1 Animal
=item2 Vertebrate
=item2 Invertebrate
=item1 Phase
=item2 Solid
=item2 Liquid
=item2 Gas
=end code
=item1 Animal
=item2 Vertebrate
=item2 Invertebrate
=item1 Phase
=item2 Solid
=item2 Liquid
=item2 Gas
=head3 Multi-paragraph Lists
Using the delimited form of the C<=item> block (C<=begin item> and C<=end item>),
we can specify items that contain multiple paragraphs.
For example:
=begin code :skip-test
Let's consider two common proverbs:
=begin item
I<The rain in Spain falls mainly on the plain.>
This is a common myth and an unconscionable slur on the Spanish
people, the majority of whom are extremely attractive.
=end item
=begin item
I<The early bird gets the worm.>
In deciding whether to become an early riser, it is worth
considering whether you would actually enjoy annelids
for breakfast.
=end item
As you can see, folk wisdom is often of dubious value.
=end code
Let's consider two common proverbs:
=begin item
I<The rain in Spain falls mainly on the plain.>
This is a common myth and an unconscionable slur on the Spanish
people, the majority of whom are extremely attractive.
=end item
=begin item
I<The early bird gets the worm.>
In deciding whether to become an early riser, it is worth
considering whether you would actually enjoy annelids
for breakfast.
=end item
As you can see, folk wisdom is often of dubious value.
=head2 Tables
Check out this page for documentation related to L<Tables|https://docs.perl6.org/language/tables>
Z<Eventually copy everything from tables.pod6 and put it here>
=head2 Pod comments
Pod comments are comments that Pod renderers ignore.
Comments are useful for meta-documentation (documenting the documentation):
=begin code
=comment Add more here about the algorithm
=end code
=head2 Semantic blocks
All uppercase block typenames are reserved for specifying standard documentation,
publishing, source components, or meta-information.
=begin code
=NAME
=AUTHOR
=VERSION
=TITLE
=SUBTITLE
=end code
=head1 Formatting Codes
Formatting codes provide a way to add inline mark-up to a piece of text.
All Pod formatting codes consist of a single capital letter followed immediately by a set of angle brackets.
Formatting codes may nest other formatting codes.
=head2 Bold
To format a text in bold enclose it in C<B< >>
=for code :skip-test
Perl 6 is B<awesome>
Perl 6 is B<awesome>
=head2 Italic
To format a text in italic enclose it in C<I< >>
=for code :skip-test
Perl 6 is I<awesome>
Perl 6 is I<awesome>
=head2 Underlined
To underline a text enclose it in C<U< >>
=for code :skip-test
Perl 6 is U<awesome>
Z<If used will bust Pod::To::BigPage>
=head2 Code
To flag text as Code and treat it verbatim enclose it in C<C< >>
=for code :skip-test
C<my $var = 1; say $var;>
C<my $var = 1; say $var;>
=head2 Links
To create a link enclose it in C<L< >>
=for code :skip-test
Perl 6 homepage L<https://perl6.org>
L<Perl 6 homepage|https://perl6.org>
Perl 6 homepage L<https://perl6.org>
L<Perl 6 homepage|https://perl6.org>
To create a link to a section in the same document:
=for code :skip-test
Comments L<#Comments>
Comments L<#Comments>
=head2 Comments
A comment is text that is never rendered.
To create a comment enclose it in C<Z< >>
=for code :skip-test
Perl 6 is awesome Z<Of course it is!>
Perl 6 is awesome Z<Of course it is!>
=head2 Notes
Notes are rendered as footnotes.
To create a note enclose it in C<N< >>
=for code :skip-test
Perl 6 is multi-paradigmatic N<Supporting Procedural, Object Oriented, and Functional programming>
Z<Perl 6 is multi-paradigmatic N<Supporting Procedural, Object Oriented, and Functional programming> >
=head2 Keyboard input
To flag text as keyboard input enclose it in C<K< >>
=for code :skip-test
Enter your name K<John Doe>
Z<If used will bust Pod::To::BigPage>
=head2 Terminal Output
To flag text as terminal output enclose it in C<T< >>
=for code :skip-test
Hello T<John Doe>
Z<If used will bust Pod::To::BigPage>
=head2 Unicode
To include Unicode code points or HTML5 character references in a Pod document, enclose them in C<E< >>
C<E< >> can enclose a number, that number is treated as the decimal Unicode value for the desired code point.
It can also enclose explicit binary, octal, decimal, or hexadecimal numbers using the Perl 6 notations for explicitly based numbers.
=begin code :skip-test
Perl 6 makes considerable use of the E<171> and E<187> characters.
Perl 6 makes considerable use of the E<laquo> and E<raquo> characters.
Perl 6 makes considerable use of the E<0b10101011> and E<0b10111011> characters.
Perl 6 makes considerable use of the E<0o253> and E<0o273> characters.
Perl 6 makes considerable use of the E<0d171> and E<0d187> characters.
Perl 6 makes considerable use of the E<0xAB> and E<0xBB> characters.
=end code
Perl 6 makes considerable use of the « and » characters.
=head1 Rendering Pod
=head2 HTML
In order to generate HTML from Pod, you need the C<Pod::To::HTML> module.
If it is not already installed, install it by running the following command:
C<zef install Pod::To::HTML>
Using the terminal run the following command:
=begin code :lang<shell>
perl6 --doc=HTML input.pod6 > output.html
=end code
=head2 Markdown
In order to generate Markdown from Pod, you need the C<Pod::To::Markdown> module.
If it is not already installed, install it by running the following command:
C<zef install Pod::To::Markdown>
Using the terminal run the following command:
=begin code :lang<shell>
perl6 --doc=Markdown input.pod6 > output.md
=end code
=head2 Text
In order to generate Text from Pod, you can use the default
C<Pod::To::Text> module.
Using the terminal, run the following command:
=begin code :lang<shell>
perl6 --doc=Text input.pod6 > output.txt
=end code
You can omit the C<=Text> portion:
=begin code :lang<shell>
perl6 --doc input.pod6 > output.txt
=end code
You can even embed Pod directly in your program and add the
traditional Unix command line "--man" option to your program with a
multi MAIN subroutine like this:
=begin code
multi MAIN(Bool :$man)
{
run $*EXECUTABLE, '--doc', $*PROGRAM;
}
=end code
Now C<myprogram --man> will output your Pod rendered as a man page.
=end pod
# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6