Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 2935 lines (2170 sloc) 92.139 kb
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1 =begin pod
2
4520b7f [S26] Let's eat some more of our own dog food by using semantic Pod bloc...
hinrik authored
3 =comment
4 This file is deliberately specified in Perl 6 Pod format
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
5
4520b7f [S26] Let's eat some more of our own dog food by using semantic Pod bloc...
hinrik authored
6 =TITLE
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
7 Synopsis 26 - Documentation
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
8
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
9 =for AUTHOR
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
10 Damian Conway <L<C<damian@conway.org>|mailto:damian@conway.org>>
c88d29b r6@Gort: damian | 2006-03-16 10:31:40 +1100
damian authored
11
4520b7f [S26] Let's eat some more of our own dog food by using semantic Pod bloc...
hinrik authored
12 =begin VERSION
a563db4 [S26] checked in Damian's latest changes
masak authored
13 =table
14 Maintainer: Damian Conway
15 Date: 9 Apr 2005
412b4c3 [S26] Attempts at clarifying language
jani authored
16 Last Modified: 31 Jul 2010
4520b7f [S26] Let's eat some more of our own dog food by using semantic Pod bloc...
hinrik authored
17 =end VERSION
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
18
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
19 =head1
20 Pod
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
21
a563db4 [S26] checked in Damian's latest changes
masak authored
22 D<Pod> is an easy-to-use markup language with a simple, consistent
23 underlying document object model. Pod can be used for writing language
24 documentation, for documenting programs and modules, as well as for
25 other types of document composition.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
26
a563db4 [S26] checked in Damian's latest changes
masak authored
27 Pod is an evolution of Perl 5's L<I<Plain Ol' Documentation>|doc:perlpod>
28 (POD) markup. Compared to POD, Perl 6's Pod is much more
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
29 uniform, somewhat more compact, and considerably more expressive. The
30 Pod dialect also differs in that it is a purely descriptive mark-up
31 notation, with no presentational components.
32
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
33
34 =head2 General syntactic structure
35
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
36 Pod documents are specified using D<directives|directive>, which are
37 used to declare configuration information and to delimit blocks of
38 textual content. All Pod directives are considered to be special types
39 of comments in Perl 6.
a563db4 [S26] checked in Damian's latest changes
masak authored
40
41 Every directive starts either with an equals sign (C<=>) followed
412b4c3 [S26] Attempts at clarifying language
jani authored
42 immediately by an identifier N<as specified in Synopsis 2>, or with
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
43 a C<#=> or C<#|> followed immediately by whitespace or an opening bracket.
a563db4 [S26] checked in Damian's latest changes
masak authored
44
45 Directives that start with C<=> can be indented like the code they
46 interleave, but their initial C<=> must still be the first non-whitespace
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
47 character on their line. Directives that start with C<#=> or C<#|> can be placed
412b4c3 [S26] Attempts at clarifying language
jani authored
48 anywhere that a Perl 6 comment can appear, though they are meaningful
49 only in a subset of those places; see L<#Declarator blocks>.
a563db4 [S26] checked in Damian's latest changes
masak authored
50
412b4c3 [S26] Attempts at clarifying language
jani authored
51 An indented Pod block is considered to have a I<virtual left margin>,
52 determined by the indentation of its opening delimiter.
53
54 In other words, if a directive is indented from the left margin, the
55 column at which the first character of its opening delimiter appears is
56 thereafter considered the first column of the entire block's contents.
57
58 As with Perl 6 heredocs, the virtual margin treats leading tabs as
59 aligning to tabstops spaced every C<($?TABSTOP // 8)> characters.
a563db4 [S26] checked in Damian's latest changes
masak authored
60
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
61 =head2
62 Pod blocks
a563db4 [S26] checked in Damian's latest changes
masak authored
63
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
64 The content of a document is specified within one or more D<blocks|block>.
a563db4 [S26] checked in Damian's latest changes
masak authored
65 Every Pod block may be declared in any of four forms:
412b4c3 [S26] Attempts at clarifying language
jani authored
66
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
67 L<I<delimited style>|#Delimited blocks>, L<I<paragraph style>|#Paragraph
a563db4 [S26] checked in Damian's latest changes
masak authored
68 blocks>, L<I<abbreviated style>|#Abbreviated blocks>, or L<I<declarator
69 style>|#Declarator blocks>. The first three forms are all equivalent; the
70 fourth is distinct.
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
71
72 Anything in a document that is neither a Pod directive nor contained
73 within a Pod block is treated as "ambient" material. Typically this
74 would be the source code of the program that the Pod is documenting. Pod
75 parsers still parse this text into the internal representation of the
412b4c3 [S26] Attempts at clarifying language
jani authored
76 file, representing it as a C<Pod6::Block::Ambient> block. Renderers
77 will I<usually> ignore such blocks, but see L<#Aliases>.
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
78
79 In Perl 5's POD format, once a POD directive is encountered, the parser
80 considers everything that follows to be POD, until an explicit C<=cut>
a563db4 [S26] checked in Damian's latest changes
masak authored
81 directive is encountered, at which point the parser flips back to
82 parsing ambient source code. The Perl 6 Pod format is different. All Pod
83 directives have a defined terminator and the Pod parser always reverts to
84 "ambient" at the end of each Pod directive or block. To cause the parser
85 to remain in Pod mode, you must enclose the desired Pod region in a
86 C<pod> block:
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
87
88 =begin code :allow<B>
89 B<=begin pod>
90
91 =head1 A heading
92
93 This is Pod too. Specifically, this is a simple C<para> block
94
95 $this = pod('also'); # Specifically, a code block
96
97 B<=end pod>
98 =end code
99
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
100 =head3 Delimited blocks
101
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
102 Delimited blocks are bounded by C<=begin> and C<=end> markers, both of
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
103 which are followed by a valid Perl 6 identifier, which is the
104 D<typename> of the block. Typenames that are entirely lowercase (for
105 example: C<=begin head1>) or entirely uppercase (for example: C<=begin
106 SYNOPSIS>) are reserved.
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
107
108 After the typename, the rest of the C<=begin> marker line is treated as
109 configuration information for the block. This information is used in
753e1c5 re-syncing from Perl6-Perldoc-v0.0.5
diakopter authored
110 different ways by different types of blocks, but is always specified using
111 Perl6-ish option pairs. That is, any of:
112
113 =for table :nested
a563db4 [S26] checked in Damian's latest changes
masak authored
114 Value is... Specify with... Or with... Or with...
115 =============== =================== ============== ======================
fb1ceb2 @moritz convert S26 from Latin-1 to UTF-8
moritz authored
116 Boolean (true) C«:key» C«:key(1)» C«key => 1»
117 Boolean (false) C«:!key» C«:key(0)» C«key => 0»
118 String C«:key<str>» C«:key('str')» C«key => 'str'»
119 List C«:key<1 2 3>» C«:key[1,2,3]» C«key => [1,2,3]»
120 Hash C«:key{a=>1, b=>2}» C«key => {a=>1, b=>2}»
a563db4 [S26] checked in Damian's latest changes
masak authored
121
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
122 All option keys and values must, of course, be constants since Pod is a
123 specification language, not a programming language. Specifically, option
124 values cannot be closures. See Synopsis 2 for details of the various
125 Perl 6 pair notations.
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
126
127 The configuration section may be extended over subsequent lines by
a563db4 [S26] checked in Damian's latest changes
masak authored
128 starting those lines with an C<=> in the first (virtual) column followed
129 by a whitespace character.
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
130
753e1c5 re-syncing from Perl6-Perldoc-v0.0.5
diakopter authored
131 The lines following the opening delimiter and configuration are the
a563db4 [S26] checked in Damian's latest changes
masak authored
132 data or contents of the block, which continue until the block's matching
133 C<=end> marker line. For most block types, these contents may be
134 indented if you wish, without them being treated as L<code blocks|#Code
135 blocks>. Unlike Perl 5, indented text is only treated as code within
136 C<=pod>, L<C<=nested>|#Nesting blocks>, L<C<=item>|#Lists>, C<=code>,
137 and L<semantic|#Semantic blocks> blocks.
753e1c5 re-syncing from Perl6-Perldoc-v0.0.5
diakopter authored
138
139 The general syntax is:
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
140
141 =begin code :allow< R >
142 =begin R<BLOCK_TYPE> R<OPTIONAL CONFIG INFO>
143 = R<OPTIONAL EXTRA CONFIG INFO>
144 R<BLOCK CONTENTS>
145 =end R<BLOCK_TYPE>
146 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
147
148 For example:
149
a563db4 [S26] checked in Damian's latest changes
masak authored
150 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
151 =begin table :caption<Table of Contents>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
152 Constants 1
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
153
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
154 Variables 10
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
155
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
156 Subroutines 33
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
157
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
158 Everything else 57
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
159 =end table
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
160
a563db4 [S26] checked in Damian's latest changes
masak authored
161 =begin Name :required
162 = :width(50)
163 The applicant's full name
164 =end Name
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
165
a563db4 [S26] checked in Damian's latest changes
masak authored
166 =begin Contact :optional
167 The applicant's contact details
168 =end Contact
169 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
170
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
171 Note that no blank lines are required around the directives; blank
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
172 lines within the contents are always treated as part of the contents.
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
173 This is a universal feature of Pod.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
174
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
175 Note also that in the following specifications, a "blank line" is a line
176 that is either empty or that contains only whitespace characters. That
177 is, a blank line matches the Perl 6 pattern: C</^^ \h* $$/>. Pod uses
a563db4 [S26] checked in Damian's latest changes
masak authored
178 blank lines as delimiters, rather than empty lines, to minimize unpleasant
179 surprises when stray spaces or tabs mysteriously turn up in hitherto
180 empty lines.
c9f3329 Various items for further discussion at the hackathon.
lwall authored
181
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
182
183 =head3 Paragraph blocks
184
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
185 Paragraph blocks are introduced by a C<=for> marker and terminated by
186 the next Pod directive or the first blank line (which is I<not>
187 considered to be part of the block's contents). The C<=for> marker is
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
188 followed by the name of the block and optional configuration
189 information. The general syntax is:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
190
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
191 =begin code :allow< R >
192 =for R<BLOCK_TYPE> R<OPTIONAL CONFIG INFO>
193 = R<OPTIONAL EXTRA CONFIG INFO>
194 R<BLOCK DATA>
195 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
196
197 For example:
198
a563db4 [S26] checked in Damian's latest changes
masak authored
199 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
200 =for table :caption<Table of Contents>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
201 Constants 1
202 Variables 10
203 Subroutines 33
204 Everything else 57
205
a563db4 [S26] checked in Damian's latest changes
masak authored
206 =for Name :required
207 = :width(50)
208 The applicant's full name
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
209
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
210 =for Contact :optional
a563db4 [S26] checked in Damian's latest changes
masak authored
211 The applicant's contact details
212
213 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
214
215
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
216 =head3 Abbreviated blocks
c9f3329 Various items for further discussion at the hackathon.
lwall authored
217
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
218 Abbreviated blocks are introduced by an C<'='> sign in the
219 first column, which is followed immediately by the typename of the
220 block. The rest of the line is treated as block data, rather than as
221 configuration. The content terminates at the next Pod directive or the
222 first blank line (which is not part of the block data). The general
223 syntax is:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
224
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
225 =begin code :allow< R >
226 =R<BLOCK_TYPE> R<BLOCK DATA>
227 R<MORE BLOCK DATA>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
228
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
229 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
230
231 For example:
232
a563db4 [S26] checked in Damian's latest changes
masak authored
233 =begin code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
234 =table
235 Constants 1
236 Variables 10
237 Subroutines 33
238 Everything else 57
239
a563db4 [S26] checked in Damian's latest changes
masak authored
240 =Name The applicant's full name
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
241 =Contact The applicant's contact details
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
242
a563db4 [S26] checked in Damian's latest changes
masak authored
243 =end code
244
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
245 Note that abbreviated blocks cannot specify configuration information. If
246 configuration is required, use a C<=for> or C<=begin>/C<=end> instead.
247
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
248
a563db4 [S26] checked in Damian's latest changes
masak authored
249 =head3 Declarator blocks
250
251 The fourth form of Pod block differs from the first three in that it
252 does not specify an explicit typename. Instead, it obtains its identity
253 and purpose from the Perl 6 source code to which it is attached;
254 specifically, from some nearby declarator.
255
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
256 Declarator blocks are introduced by a special Perl comment: either C<#=>
257 or C<#|>, which must be immediately followed by either by a space or an
258 opening bracket. If followed by a space, the block is terminated by the
259 end of line; if followed by one or more opening brackets, the block is
260 terminated by the matching sequence of closing brackets.
a563db4 [S26] checked in Damian's latest changes
masak authored
261
262 That is, declarator Pod blocks are syntactically like ordinary Perl 6
263 single-line comments and embedded comments. The general syntax is:
264
265 =begin code :allow< R >
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
266
267 #| R<BLOCK DATA TO END OF LINE>
268
269 #|{ R<BLOCK DATA>
270 R<MORE BLOCK DATA>
271 }
272
a563db4 [S26] checked in Damian's latest changes
masak authored
273 #= R<BLOCK DATA TO END OF LINE>
274
275 #={ R<BLOCK DATA>
276 R<MORE BLOCK DATA>
277 }
278
279 =end code
280
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
281 except that the bracketed forms may use I<any> valid Perl 6 bracket delimiter
a563db4 [S26] checked in Damian's latest changes
masak authored
282 (including repeated opening brackets), as described in Synopsis 2.
283
284 Declarator Pod blocks must either precede or immediately follow a valid
285 Perl 6 declarator, and are then said to be "attached" to it. They are
286 primarily intended to simplify the documentation of code interfaces.
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
287
288 Declarator blocks that start with C<#|> attach to the declarator at the
289 start of the line immediately after them (separated only by whitespace).
290 Declarator blocks that start with C<#=> attach to the declarator
291 declared at the start of the line immediately before them. In all other
292 respects they act just like comments (i.e. they are themselves whitespace
293 as far as ambient source code is concerned). This means multiple declarator
294 blocks can be specified in a row and will all attach to the same declarator.
295
a563db4 [S26] checked in Damian's latest changes
masak authored
296 For example:
297
298 =begin code
299
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
300 #| Base class for comms necromancy hierarchy
a563db4 [S26] checked in Damian's latest changes
masak authored
301 class Magic::Necrotelecomnicon {
302 has $.elemental; #= Source of all power
303 has $!true_name; # Source of all self-protection (not documented)
304
305 method cast(Spell $s)
306 #= Initiate a specified spell normally
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
307 #= (do not use for class 7 spells)
a563db4 [S26] checked in Damian's latest changes
masak authored
308 {
309 do_raw_magic($s);
310 }
311
312
313 method kast( #= Initiate a specified spell abnormally
314 Spell $s #= The spell to be abnormally initiated
315 ) {
316 do_raw_magic($s, :alternative);
317 }
318
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
319 #| This subroutine does the real work
eb57188 [S26] corrected minor typos and inconsistencies
masak authored
320 sub do_raw_magic (
a563db4 [S26] checked in Damian's latest changes
masak authored
321 Spell $s, #= Which spell to invoke
322 *%options #= How to invoke it
323 ) {...}
324 }
325
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
326 sub fu (Any $bar)
327 #=[ This text stored in C<&fu.WHY>, not in C<$bar.WHY>,
328 (because C<sub fu> is the declarator
a563db4 [S26] checked in Damian's latest changes
masak authored
329 at the I<start> of the preceding line)
330 ]
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
331
332 multi sub baz(Int $count, Str $name)
333 #=[ This text stored in C<&baz:(Int,Str).WHY>
334 (i.e. the C<.WHY> of the variant, not of the entire multisub)
335 ]
a563db4 [S26] checked in Damian's latest changes
masak authored
336 =end code
337
338 A declarator can have both a leading and a trailing Pod comment, in
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
339 which case they are concatenated with an intermediate newline when
340 their object's C<.WHY> return value is stringified:
a563db4 [S26] checked in Damian's latest changes
masak authored
341
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
342 #| This is a special chainsaw
a563db4 [S26] checked in Damian's latest changes
masak authored
343 my SwissArmy $chainsaw #= (It has a rocket launcher)
344
345 say $chainsaw.WHY; # prints: This is a special chainsaw
346 # (It has a rocket launcher)
347
7d19390 @masak [S26] replaced magic by the two forms #= and #|
masak authored
348 The individual leading and trailing Pod comments can be retrieved
349 via the returned Pod object's C<.leading> and C<.trailing> methods:
350
351 say $chainsaw.WHY.leading; # prints: This is a special chainsaw
352
353 say $chainsaw.WHY.trailing; # prints: (It has a rocket launcher)
a563db4 [S26] checked in Damian's latest changes
masak authored
354
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
355 The Pod object representing each Declarator block is still appended to
3e1a9a5 @masak [S26] lower-case $=POD, =DATA and =END
masak authored
356 the current surrounding Pod object (e.g. to C<$=pod> at the top level).
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
357 Each such block representation is an object of class
358 C<Pod6::Block::Declarator>, and has a C<.WHEREFORE> method that returns
359 the code object or metaobject created by the declarator to which the
360 documentation is attached.
a563db4 [S26] checked in Damian's latest changes
masak authored
361
c86ca97 @masak [S26] supplied explanatory .WHY/.WHEREFORE diagram
masak authored
362 In other words, C<.WHY> and C<.WHEREFORE> are inverse operations:
363
364 .WHY
365 ----------------------------
366 | |
367 | v
368 ----------------- -----------------
369 | Declared code | | Documentation |
370 | object | | object |
371 ----------------- -----------------
372 ^ |
373 | |
374 ----------------------------
375 .WHEREFORE
376
377
378
a563db4 [S26] checked in Damian's latest changes
masak authored
379 When the L<default C<DOC INIT> block|#How Pod is parsed and processed>
380 renders these Pod objects, it automatically includes information about
381 the declarator as well. For instance, the earlier Necrotelecomnicon
382 example might produce something like:
383
384 =begin output
385 Name: Magic::Necrotelecomnicon:
386 Desc: Base class for comms necromancy hierarchy
387
388 Attrs:
389 .elemental : Source of all power
390
391 Methods:
392 .cast(Spell $s) : Initiate a specified spell normally
393 .kast(Spell $s) : Initiate a specified spell abnormally
394
395 Subroutines:
eb57188 [S26] corrected minor typos and inconsistencies
masak authored
396 do_raw_magic( : This subroutine does the real work
a563db4 [S26] checked in Damian's latest changes
masak authored
397 Spell $s, : Which spell to invoke
398 *%options : How to invoke it
399 )
400
401 =end output
402
403 Note, however, that the exact rendering used for declarator blocks is
404 implementation dependent, and may also be pre-empted explicitly by some
405 L<C<DOC> configuration statement|#How Pod is parsed and processed>
406 within the document, such as:
407
408 DOC use Pod6::Markovian;
409
410 or:
411
412 DOC INIT {
413 use Pod6::Eiffelish::Long;
414
3e1a9a5 @masak [S26] lower-case $=POD, =DATA and =END
masak authored
415 say eiffelish_long($=pod);
a563db4 [S26] checked in Damian's latest changes
masak authored
416
417 exit;
418 }
419
420
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
421 =head3 Block equivalence
422
a563db4 [S26] checked in Damian's latest changes
masak authored
423 The first three block specifications (delimited, paragraph, and
424 abbreviated) are treated identically by the underlying documentation
425 model, so you can use whichever form is most convenient for a particular
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
426 documentation task. In the descriptions that follow, the abbreviated
427 form will generally be used, but should be read as standing for all
428 three forms equally.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
429
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
430 For example, although L<#Headings> shows only:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
431
a563db4 [S26] checked in Damian's latest changes
masak authored
432 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
433 =head1 Top Level Heading
a563db4 [S26] checked in Damian's latest changes
masak authored
434 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
435
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
436 this automatically implies that you could also write that block as:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
437
a563db4 [S26] checked in Damian's latest changes
masak authored
438 =begin code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
439 =for head1
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
440 Top Level Heading
a563db4 [S26] checked in Damian's latest changes
masak authored
441 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
442
443 or:
444
a563db4 [S26] checked in Damian's latest changes
masak authored
445 =begin code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
446 =begin head1
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
447 Top Level Heading
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
448 =end head1
a563db4 [S26] checked in Damian's latest changes
masak authored
449 =end code
450
451 Declarator blocks are distinct from these three forms. They do not have
452 typenames of their own, but rather take their meaning and identity from
453 the declared object or type to which they are attached. In general, they
454 are used specifically to describe that declarand.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
455
456
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
457 =head3 Standard configuration options
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
458
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
459 Pod predefines a small number of standard configuration options that can be
a563db4 [S26] checked in Damian's latest changes
masak authored
460 applied uniformly to any built-in block type. These include:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
461
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
462 =begin defn
463 C<:nested>
53bce10 r5749@bytes: ingy | 2006-03-17 08:54:03 -0800
ingy authored
464
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
465 This option specifies that the block is to be nested within its current
466 context. For example, nesting might be applied to block quotes, to textual
467 examples, or to commentaries. In addition the L<C<=code>|#Code blocks>,
468 L<C<=item>|#Lists>, L<C<=input>|#I/O blocks>, and L<C<=output>|#I/O blocks>
469 blocks all have implicit nesting.
53bce10 r5749@bytes: ingy | 2006-03-17 08:54:03 -0800
ingy authored
470
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
471 Nesting of blocks is usually rendered by adding extra indentation to the
eb57188 [S26] corrected minor typos and inconsistencies
masak authored
472 block contents, but may also be indicated in other ways:
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
473 by boxing the contents, by changing the font or size of the nested text,
474 or even by folding the text (so long as a visible placeholder is provided).
53bce10 r5749@bytes: ingy | 2006-03-17 08:54:03 -0800
ingy authored
475
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
476 Occasionally it is desirable to nest content by more than one level:
53bce10 r5749@bytes: ingy | 2006-03-17 08:54:03 -0800
ingy authored
477
a563db4 [S26] checked in Damian's latest changes
masak authored
478 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
479 =begin para :nested
753e1c5 re-syncing from Perl6-Perldoc-v0.0.5
diakopter authored
480 =begin para :nested
481 =begin para :nested
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
482 "We're going deep, deep, I<deep> undercover!"
483 =end para
484 =end para
485 =end para
a563db4 [S26] checked in Damian's latest changes
masak authored
486 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
487
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
488 This can be simplified by giving the C<:nested> option a positive integer
489 value:
490
a563db4 [S26] checked in Damian's latest changes
masak authored
491 =begin code :allow<B>
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
492 =begin para B<:nested(3)>
493 "We're going deep, deep, I<deep> undercover!"
494 =end para
a563db4 [S26] checked in Damian's latest changes
masak authored
495 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
496
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
497 You can also give the option a value of zero, to defeat any implicit
498 nesting that might normally be applied to a paragraph. For example, to
499 specify a block of code that should appear I<without> its usual
500 nesting:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
501
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
502 =begin code :allow<B V>
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
503 =comment Don't nest this code block in the usual way...
504 B<=begin code :nested(0)>
505
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
506 1 2 3 4 5 6
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
507 123456789012345678901234567890123456789012345678901234567890
508 |------|-----------------------|---------------------------|
509 line instruction comments
510 number code
511
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
512 V<=end code>
a563db4 [S26] checked in Damian's latest changes
masak authored
513 =end code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
514
515 Note that C<:!nested> could also be used for this purpose:
516
a563db4 [S26] checked in Damian's latest changes
masak authored
517 =begin code
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
518 =Z<>begin code :!nested
a563db4 [S26] checked in Damian's latest changes
masak authored
519 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
520
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
521 =end defn
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
522
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
523 =begin defn
524 C<:numbered>
c9f3329 Various items for further discussion at the hackathon.
lwall authored
525
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
526 This option specifies that the block is to be numbered. The most common
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
527 use of this option is to create L<numbered headings|#Numbered headings> and
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
528 L<ordered lists|#Ordered lists>, but it can be applied to any block.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
529
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
530 The numbering conventions for headings and lists are specified in those
531 sections, but it is up to individual renderers to decide how to display
532 any numbering associated with other types of blocks.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
533
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
534 Note that numbering is never explicit; it is always implied by context.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
535
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
536 =end defn
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
537
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
538 =begin defn
539 C<:formatted>
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
540
541 This option specifies that the contents of the block should be treated as if
542 they had one or more L<formatting codes|#Formatting codes> placed around them.
543
544 For example, instead of:
545
a563db4 [S26] checked in Damian's latest changes
masak authored
546 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
547 =for comment
548 The next para is both important and fundamental,
549 so doubly emphasize it...
550
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
551 =begin para
552 B<I<
553 Warning: Do not immerse in water. Do not expose to bright light.
554 Do not feed after midnight.
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
555 >>
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
556 =end para
a563db4 [S26] checked in Damian's latest changes
masak authored
557 =end code
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
558
559 you can just write:
560
a563db4 [S26] checked in Damian's latest changes
masak authored
561 =begin code :allow<B>
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
562 =begin para B<:formatted<B I>>
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
563 Warning: Do not immerse in water. Do not expose to bright light.
564 Do not feed after midnight.
565 =end para
a563db4 [S26] checked in Damian's latest changes
masak authored
566 =end code
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
567
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
568 The internal representations of these two versions are exactly the same,
569 except that the second one retains the C<:formatted> option information
570 as part of the resulting block object.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
571
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
572 Like all formatting codes, codes applied via a C<:formatted> are
573 inherently cumulative. For example, if the block itself is already
574 inside a formatting code, that formatting code will still apply, in
575 addition to the extra "basis" and "important" formatting specified by
576 C<:formatted<B I>>.
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
577 =end defn
578
579 =begin defn
580 C<:like>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
581
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
582 This option specifies that a block or config has the same formatting
583 properties as the type named by its value. This is useful for creating
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
584 related L<configurations|#Block pre-configuration> or for making
585 user-defined synonyms for existing types. For example:
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
586
a563db4 [S26] checked in Damian's latest changes
masak authored
587 =begin code
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
588 =config head2 :like<head1> :formatted<I>
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
589
590 =config Subhead :like<head2>
a563db4 [S26] checked in Damian's latest changes
masak authored
591 =end code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
592
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
593 =end defn
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
594
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
595 =defn C<:allow>
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
596 This option expects a list of formatting codes that are to be recognized
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
597 within any C<V<>> codes that appear in (or are implicitly applied to)
598 the current block. The option is most often used on C<=code> blocks to
599 allow mark-up within those otherwise verbatim blocks, though it can be
600 used in I<any> block that contains verbatim text. See L<#Formatting
601 within code blocks>.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
602
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
603 =begin defn
604 C<:margin>
605
a563db4 [S26] checked in Damian's latest changes
masak authored
606 This option specifies a character that indicates the left margin of the
607 contents of the block. Normally this left margin is determined by the column
608 at which the C<=> of the opening block-delimiter occurs. For example:
609
610 =begin code
611 =head1 Indenting Pod blocks
612
613 =begin para
614 This text is flush with the (virtual) left margin of
615 the Pod block because that margin is implicitly specified
616 by the C<=> of the C<=begin>
617 =end para
618 =end code
619
620 However, by using the C<:margin> option it is possible to specify a
621 character that acts like an explicit margin when it occurs as the first
622 non-whitespace character on any line within the block. For example:
623
624 =begin code
625 =head1 Indenting Pod blocks
626
627 =begin para :margin<|>
628 |This text is flush with the (virtual) left margin of
629 |the Pod block because that margin is explicitly marked
630 |by the C<|>, as specified by the block's C<:margin<|>> option.
631 =end para
632 =end code
633
634 The virtual margin can even be to the left of the opening delimiter, which can
635 be convenient to guide subsequent indentations. For example:
636
637 =begin code
638 sub foo {
639
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
640 V<=begin> pod :margin<|>
a563db4 [S26] checked in Damian's latest changes
masak authored
641 |=head1 Hey Look: Indented Pod!
642 |
643 |You can indent Pod in Perl 6
644 |which makes code look cleaner
645 |when documentation is interspersed
646 |
647 | my $this is Code;
648 |
649 |=end pod
650
651 ...
652 }
653 =end code
654
655 When a C<:margin> option is used, each subsequent line (until the
656 corresponding closing delimiter is encountered) simply has any text matching
657 C</^^ \s* $margin_char/> automatically removed. This may include a line that
658 then becomes the closing delimiter, as in the above example.
659
660 Any line from which such a margin marker is removed automatically resets
661 the implicit margin for subsequent lines of the block, setting it to the
662 length of the "marginalized" indent that was just removed. This implicit
663 margin is then used until the next line with an explicit margin marker
664 is encountered, or the block terminates.
665
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
666 =end defn
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
667
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
668 =head2 Block types
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
669
a563db4 [S26] checked in Damian's latest changes
masak authored
670 Pod offers notations for specifying a wide range of standard block types...
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
671
672 =head3 Headings
673
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
674 Pod provides an unlimited number of levels of heading, specified by the
675 C<=head>R<N> block marker. For example:
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
676
a563db4 [S26] checked in Damian's latest changes
masak authored
677 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
678 =head1 A Top Level Heading
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
679
a563db4 [S26] checked in Damian's latest changes
masak authored
680 =head2 A Second Level Heading
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
681
a563db4 [S26] checked in Damian's latest changes
masak authored
682 =head3 A third level heading
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
683
a563db4 [S26] checked in Damian's latest changes
masak authored
684 =head86 A "Missed it by I<that> much!" heading
685 =end code
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
686
687 While Pod parsers are required to recognize and distinguish all levels
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
688 of heading, Pod renderers are only required to provide distinct
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
689 I<renderings> of the first four levels of heading (though they may, of
690 course, provide more than that). Headings at levels without distinct
691 renderings would typically be rendered like the lowest distinctly
692 rendered level.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
693
694
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
695 =head4 Numbered headings
c9f3329 Various items for further discussion at the hackathon.
lwall authored
696
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
697 You can specify that a heading is numbered using the C<:numbered> option. For
698 example:
c9f3329 Various items for further discussion at the hackathon.
lwall authored
699
a563db4 [S26] checked in Damian's latest changes
masak authored
700 =begin code
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
701 =for head1 :numbered
702 The Problem
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
703
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
704 =for head1 :numbered
705 The Solution
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
706
a563db4 [S26] checked in Damian's latest changes
masak authored
707 =for head2 :numbered
708 Analysis
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
709
a563db4 [S26] checked in Damian's latest changes
masak authored
710 =for head3
711 Overview
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
712
a563db4 [S26] checked in Damian's latest changes
masak authored
713 =for head3
714 Details
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
715
a563db4 [S26] checked in Damian's latest changes
masak authored
716 =for head2 :numbered
717 Design
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
718
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
719 =for head1 :numbered
720 The Implementation
a563db4 [S26] checked in Damian's latest changes
masak authored
721 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
722
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
723 which would produce:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
724
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
725 =begin nested :formatted<B>
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
726 1. The Problem
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
727
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
728 2. The Solution
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
729
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
730 =begin nested
731 2.1. Analysis
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
732
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
733 =begin nested
734 Overview
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
735
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
736 Details
737 =end nested
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
738
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
739 2.2: Design
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
740 =end nested
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
741
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
742 3. The Implementation
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
743 =end nested
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
744
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
745 It is usually better to preset a numbering scheme for each heading
746 level, in a series of L<configuration blocks|#Block pre-configuration>:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
747
a563db4 [S26] checked in Damian's latest changes
masak authored
748 =begin code :allow<B>
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
749 B<=config head1 :numbered
750 =config head2 :numbered
751 =config head3 :!numbered>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
752
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
753 =head1 The Problem
754 =head1 The Solution
755 =head2 Analysis
756 =head3 Overview
757 =head3 Details
758 =head2 Design
759 =head1 The Implementation
a563db4 [S26] checked in Damian's latest changes
masak authored
760 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
761
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
762 Alternatively, as a short-hand, if the first whitespace-delimited word
763 in a heading consists of a single literal C<#> character, the C<#> is
764 removed and the heading is treated as if it had a C<:numbered> option:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
765
a563db4 [S26] checked in Damian's latest changes
masak authored
766 =begin code
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
767 =head1 # The Problem
768 =head1 # The Solution
769 =head2 # Analysis
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
770 =head3 Overview
771 =head3 Details
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
772 =head2 # Design
773 =head1 # The Implementation
a563db4 [S26] checked in Damian's latest changes
masak authored
774 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
775
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
776 Note that, even though renderers are not required to distinctly render
777 more than the first four levels of heading, they I<are> required to
778 correctly honour arbitrarily nested numberings. That is:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
779
a563db4 [S26] checked in Damian's latest changes
masak authored
780 =begin code
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
781 =head6 # The Rescue of the Kobayashi Maru
a563db4 [S26] checked in Damian's latest changes
masak authored
782 =end code
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
783
784 should produce something like:
785
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
786 =nested
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
787 B<2.3.8.6.1.9. The Rescue of the Kobayashi Maru>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
788
789
790 =head3 Ordinary paragraph blocks
791
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
792 Ordinary paragraph blocks consist of text that is to be formatted into
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
793 a document at the current level of nesting, with whitespace
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
794 squeezed, lines filled, and any special L<inline mark-up|#Formatting codes>
795 applied.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
796
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
797 Ordinary paragraphs consist of one or more consecutive lines of text,
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
798 each of which starts with a non-whitespace character at (virtual) column
799 1. The paragraph is terminated by the first blank line or block
800 directive. For example:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
801
a563db4 [S26] checked in Damian's latest changes
masak authored
802 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
803 =head1 This is a heading block
804
805 This is an ordinary paragraph.
806 Its text will be squeezed and
807 short lines filled. It is terminated by
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
808 the first blank line.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
809
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
810 This is another ordinary paragraph.
811 Its text will also be squeezed and
812 short lines filled. It is terminated by
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
813 the trailing directive on the next line.
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
814 =head2 This is another heading block
815
816 This is yet another ordinary paragraph,
817 at the first virtual column set by the
818 previous directive
a563db4 [S26] checked in Damian's latest changes
masak authored
819 =end code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
820
3e1a9a5 @masak [S26] lower-case $=POD, =DATA and =END
masak authored
821 Within a C<=pod>, C<=item>, C<=defn>, C<=nested>, C<=finish>, or
753e1c5 re-syncing from Perl6-Perldoc-v0.0.5
diakopter authored
822 L<semantic|#Semantic blocks> block, ordinary paragraphs do not require
823 an explicit marker or delimiters, but there is also an explicit C<para>
824 marker (which may be used anywhere):
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
825
a563db4 [S26] checked in Damian's latest changes
masak authored
826 =begin code :allow<B>
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
827 B<=para>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
828 This is an ordinary paragraph.
829 Its text will be squeezed and
830 short lines filled.
a563db4 [S26] checked in Damian's latest changes
masak authored
831 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
832
833 and likewise the longer C<=for> and C<=begin>/C<=end> forms. For example:
834
753e1c5 re-syncing from Perl6-Perldoc-v0.0.5
diakopter authored
835 =begin code :allow<B>
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
836 B<=begin para>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
837 This is an ordinary paragraph.
838 Its text will be squeezed and
839 short lines filled.
753e1c5 re-syncing from Perl6-Perldoc-v0.0.5
diakopter authored
840
841 This is I<still> part of the same paragraph,
842 which continues until an...
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
843 B<=end para>
753e1c5 re-syncing from Perl6-Perldoc-v0.0.5
diakopter authored
844 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
845
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
846 As the previous example implies, when any form of explicit C<para> block
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
847 is used, any whitespace at the start of each line is removed during rendering.
a563db4 [S26] checked in Damian's latest changes
masak authored
848 In addition, within a delimited C<=begin para>/C<=end para> block, any
849 blank lines are preserved.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
850
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
851 =head3 Code blocks
c9f3329 Various items for further discussion at the hackathon.
lwall authored
852
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
853 Code blocks are used to specify pre-formatted text (typically source
854 code), which should be rendered without rejustification, without
855 whitespace-squeezing, and without recognizing any inline formatting
856 codes. Code blocks also have an implicit L<nesting|#Nesting blocks>
857 associated with them. Typically these blocks are used to show examples
858 of code, mark-up, or other textual specifications, and are rendered
859 using a fixed-width font.
c9f3329 Various items for further discussion at the hackathon.
lwall authored
860
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
861 A code block may be implicitly specified as one or more lines of text,
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
862 each of which starts with a whitespace character at the block's virtual
a563db4 [S26] checked in Damian's latest changes
masak authored
863 left margin. The implicit code block is then terminated by a blank line.
864 For example:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
865
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
866 =begin code
867 This ordinary paragraph introduces a code block:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
868
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
869 $this = 1 * code('block');
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
870 $which.is_specified(:by<indenting>);
871 =end code
872
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
873 Implicit code blocks may only be used within C<=pod>, C<=item>, C<=defn>,
3e1a9a5 @masak [S26] lower-case $=POD, =DATA and =END
masak authored
874 C<=nested>, C<=finish>, or L<semantic|#Semantic blocks> blocks.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
875
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
876 There is also an explicit C<=code> block (which can be specified within
877 I<any> other block type, not just C<=pod>, C<=item>, etc.):
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
878
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
879 =begin code :allow<B>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
880 The C<loud_update()> subroutine adds feedback:
881
a563db4 [S26] checked in Damian's latest changes
masak authored
882 B<=begin code>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
883
a563db4 [S26] checked in Damian's latest changes
masak authored
884 sub loud_update ($who, $status) {
885 say "$who -> $status";
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
886
a563db4 [S26] checked in Damian's latest changes
masak authored
887 silent_update($who, $status);
888 }
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
889
a563db4 [S26] checked in Damian's latest changes
masak authored
890 B<=end code>
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
891 =end code
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
892
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
893 As the previous example demonstrates, within an explicit C<=code> block
a563db4 [S26] checked in Damian's latest changes
masak authored
894 the code can start at the (virtual) left margin. Furthermore, lines that
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
895 start with whitespace characters after that margin have subsequent
a563db4 [S26] checked in Damian's latest changes
masak authored
896 whitespace preserved exactly (in addition to the implicit nesting of the
897 code). Explicit C<=code> blocks may also contain empty lines.
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
898
899
900 =head4 Formatting within code blocks
901
902 Although C<=code> blocks automatically disregard all L<formatting
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
903 codes|#Formatting codes>, occasionally you may still need to specify
904 some formatting within a code block. For example, you may wish
905 to emphasize a particular keyword in an example (using a C<B<>> code). Or
906 you may want to indicate that part of the example is metasyntactic
907 (using the C<R<>> code). Or you might need to insert a non-ASCII
908 character (using the C<E<>> code).
909
910 You can specify a list of formatting codes that should still be
911 recognized within a code block using the C<:allow> option. The value of
912 the C<:allow> option must be a list of the (single-letter) names of one
913 or more formatting codes. Those codes will then remain active inside the
914 code block. For example:
915
a563db4 [S26] checked in Damian's latest changes
masak authored
916 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
917 =begin code :allow< B R >
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
918 sub demo {
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
919 B<say> 'Hello R<name>';
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
920 }
921 =end code
a563db4 [S26] checked in Damian's latest changes
masak authored
922 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
923
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
924 would be rendered:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
925
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
926 =begin code :allow< B R >
927 sub demo {
928 B<say> 'Hello R<name>';
929 }
930 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
931
a563db4 [S26] checked in Damian's latest changes
masak authored
932 Note that the use of the C<:allow> option also makes it possible
933 for verbatim L<formatting codes|#Formatting codes> (such as C<C<>>
934 and C<V<>>) to L<contain other codes as well|#Pre-configuring formatting codes>.
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
935
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
936
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
937 =head3 I/O blocks
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
938
a563db4 [S26] checked in Damian's latest changes
masak authored
939 Pod also provides blocks for specifying the input and output of programs.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
940
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
941 The C<=input> block is used to specify pre-formatted keyboard input,
942 which should be rendered without rejustification or squeezing of whitespace.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
943
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
944 The C<=output> block is used to specify pre-formatted terminal or file
945 output which should also be rendered without rejustification or
946 whitespace-squeezing.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
947
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
948 Note that, like C<=code> blocks, both C<=input> and C<=output> blocks have an
949 implicit level of nesting. They are also like C<=code> blocks in that they
950 are typically rendered in a fixed-width font, though ideally all three blocks
951 would be rendered in distinct font/weight combinations (for example: regular
952 serifed for code, bold sans-serif for input, and regular sans-serif for
953 output).
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
954
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
955 Unlike C<=code> blocks, both C<=input> and C<=output> blocks honour any
753e1c5 re-syncing from Perl6-Perldoc-v0.0.5
diakopter authored
956 nested formatting codes. This is particularly useful since a sample of
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
957 input will often include prompts (which are, of course, output).
958 Likewise a sample of output may contain the occasional interactive
959 component. Pod provides L<special formatting codes|#Example specifiers>
960 (C<K<>> and C<T<>>) to indicate embedded input or output, so you can use
961 the block type that indicates the overall purpose of the sample (i.e. is
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
962 it demonstrating an input operation or an output sequence?) and then use
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
963 the "contrasting" formatting code within the block.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
964
a563db4 [S26] checked in Damian's latest changes
masak authored
965 For example, to include a small amount of input in a sample of output
966 you could use the C<K<>> formatting code:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
967
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
968 =begin code :allow<B>
969 =begin output
970 Name: Baracus, B.A.
971 Rank: Sgt
972 Serial: 1PTDF007
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
973
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
974 Do you want additional personnel details? B<K<y>>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
975
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
976 Height: 180cm/5'11"
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
977 Weight: 104kg/230lb
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
978 Age: 49
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
979
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
980 Print? B<K<n>>
981 =end output
982 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
983
984
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
985 =head3 Lists
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
986
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
987 Lists in Pod are specified as a series of contiguous C<=item> blocks. No
988 special "container" directives or other delimiters are required to
989 enclose the entire list. For example:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
990
a563db4 [S26] checked in Damian's latest changes
masak authored
991 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
992 The seven suspects are:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
993
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
994 =item Happy
995 =item Dopey
996 =item Sleepy
997 =item Bashful
998 =item Sneezy
999 =item Grumpy
1000 =item Keyser Soze
a563db4 [S26] checked in Damian's latest changes
masak authored
1001 =end code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1002
1003 List items have one implicit level of nesting:
1004
1005 =begin nested
1006 The seven suspects are:
1007
1008 =item Happy
1009 =item Dopey
1010 =item Sleepy
1011 =item Bashful
1012 =item Sneezy
1013 =item Grumpy
1014 =item Keyser Soze
1015 =end nested
1016
1017 Lists may be multi-level, with items at each level specified using the
1018 C<=item1>, C<=item2>, C<=item3>, etc. blocks. Note that C<=item> is just
1019 an abbreviation for C<=item1>. For example:
1020
a563db4 [S26] checked in Damian's latest changes
masak authored
1021 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1022 =item1 Animal
1023 =item2 Vertebrate
1024 =item2 Invertebrate
1025
1026 =item1 Phase
1027 =item2 Solid
1028 =item2 Liquid
1029 =item2 Gas
1030 =item2 Chocolate
a563db4 [S26] checked in Damian's latest changes
masak authored
1031 =end code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1032
1033 which would be rendered something like:
1034
1035 =for para :nested
1036 E<bull> Animal
1037 =for para :nested(2)
1038 E<ndash> Vertebrate
1039 =for para :nested(2)
1040 E<ndash> Invertebrate
1041
1042 =for para :nested
1043 E<bull> Phase
1044 =for para :nested(2)
1045 E<ndash> Solid
1046 =for para :nested(2)
1047 E<ndash> Liquid
1048 =for para :nested(2)
1049 E<ndash> Gas
1050 =for para :nested(2)
1051 E<ndash> Chocolate
1052
a563db4 [S26] checked in Damian's latest changes
masak authored
1053 Pod parsers must issue a warning if a "level-R<N+1>" C<=item> block
3f1828f committing Documentation.pod (S26) changes from upstream::Damian.
diakopter authored
1054 (e.g. an C<=item2>, C<=item3>, etc.) appears anywhere except where there
1055 is a preceding "level-R<N>" C<=item> in the same surrounding block. That
1056 is, an C<=item3> should only be specified if an C<=item2> appears
1057 somewhere before it, and that C<=item2> should itself only appear if
1058 there is a preceding C<=item1>.
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1059
1060 Note that item blocks within the same list are not physically nested.
1061 That is, lower-level items should I<not> be specified inside
1062 higher-level items:
1063
a563db4 [S26] checked in Damian's latest changes
masak authored
1064 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1065 =comment WRONG...
1066 =begin item1 --------------
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
1067 The choices are: |
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1068 =item2 Liberty ==< Level 2 |==< Level 1
1069 =item2 Death ==< Level 2 |
1070 =item2 Beer ==< Level 2 |
1071 =end item1 --------------
a563db4 [S26] checked in Damian's latest changes
masak authored
1072 =end code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1073
a563db4 [S26] checked in Damian's latest changes
masak authored
1074 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1075 =comment CORRECT...
1076 =begin item1 ---------------
1077 The choices are: |==< Level 1
1078 =end item1 ---------------
1079 =item2 Liberty ==================< Level 2
1080 =item2 Death ==================< Level 2
1081 =item2 Beer ==================< Level 2
a563db4 [S26] checked in Damian's latest changes
masak authored
1082 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1083
1084
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1085 =head4 Ordered lists
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1086
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1087 An item is part of an ordered list if the item has a C<:numbered>
1088 configuration option:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1089
a563db4 [S26] checked in Damian's latest changes
masak authored
1090 =begin code
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1091 =for item1 :numbered
1092 Visito
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1093
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1094 =for item2 :numbered
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1095 Veni
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1096
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1097 =for item2 :numbered
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1098 Vidi
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1099
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1100 =for item2 :numbered
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1101 Vici
a563db4 [S26] checked in Damian's latest changes
masak authored
1102 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1103
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1104 This would produce something like:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1105
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1106 =begin nested
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1107 1. Visito
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1108
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1109 =begin nested
1110 1.1. Veni
1111
1112 1.2. Vidi
1113
1114 1.3. Vici
1115 =end nested
1116 =end nested
1117
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
1118 although the numbering scheme is entirely at the discretion of the
1119 renderer, so it might equally well be rendered:
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1120
1121 =begin nested
1122 1. Visito
1123
1124 =begin nested
1125 1a. Veni
1126
1127 1b. Vidi
1128
1129 1c. Vici
1130 =end nested
1131 =end nested
1132
1133 or even:
1134
1135 =begin nested
1136 A: Visito
1137
1138 =begin nested
1139 E<nbsp;nbsp>(i) Veni
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1140
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1141 E<nbsp>(ii) Vidi
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1142
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1143 (iii) Vici
1144 =end nested
1145 =end nested
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1146
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1147 Alternatively, if the first word of the item consists of a single C<#>
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1148 character, the item is treated as having a C<:numbered> option:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1149
a563db4 [S26] checked in Damian's latest changes
masak authored
1150 =begin code
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1151 =item1 # Visito
1152 =item2 # Veni
1153 =item2 # Vidi
1154 =item2 # Vici
a563db4 [S26] checked in Damian's latest changes
masak authored
1155 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1156
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1157 To specify an I<unnumbered> list item that starts with a literal C<#>, either
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
1158 make the octothorpe verbatim:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1159
a563db4 [S26] checked in Damian's latest changes
masak authored
1160 =begin code :allow<B>
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1161 =item B<V<#>> introduces a comment
a563db4 [S26] checked in Damian's latest changes
masak authored
1162 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1163
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1164 or explicitly mark the item itself as being unnumbered:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1165
a563db4 [S26] checked in Damian's latest changes
masak authored
1166 =begin code :allow<B>
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1167 =for item B<:!numbered>
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1168 # introduces a comment
a563db4 [S26] checked in Damian's latest changes
masak authored
1169 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1170
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1171 The numbering of successive C<=item1> list items increments
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1172 automatically, but is reset to 1 whenever any other kind of non-ambient
a563db4 [S26] checked in Damian's latest changes
masak authored
1173 Pod block appears between two C<=item1> blocks. For example:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1174
19a64f5 @tadzik [S26] Fix an example in List section
tadzik authored
1175 =begin code
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1176 The options are:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1177
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1178 =item1 # Liberty
1179 =item1 # Death
1180 =item1 # Beer
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1181
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1182 The tools are:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1183
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1184 =item1 # Revolution
1185 =item1 # Deep-fried peanut butter sandwich
1186 =item1 # Keg
a563db4 [S26] checked in Damian's latest changes
masak authored
1187 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1188
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1189 would produce:
c9f3329 Various items for further discussion at the hackathon.
lwall authored
1190
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1191 =begin nested
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1192 The options are:
19a64f5 @tadzik [S26] Fix an example in List section
tadzik authored
1193
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1194 =begin nested
1195 =para 1. Liberty
1196 =para 2. Death
1197 =para 3. Beer
1198 =end nested
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1199
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1200 The tools are:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1201
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1202 =begin nested
1203 =para 1. Revolution
1204 =para 2. Deep-fried peanut butter sandwich
1205 =para 3. Keg
1206 =end nested
1207 =end nested
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1208
9999072 * docs/: Perl6::Spec::Documentation, alpha draft, from TheDamian.
audreyt authored
1209 The numbering of nested items (C<=item2>, C<=item3>, etc.) only resets
1210 (to 1) when the higher-level item's numbering either resets or increments.
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1211
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1212 To prevent a numbered C<=item1> from resetting after a non-item block,
1213 you can specify the C<:continued> option:
1214
1215 =begin code :allow<B>
1216 =for item1
1217 # Retreat to remote Himalayan monastery
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1218
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1219 =for item1
1220 # Learn the hidden mysteries of space and time
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1221
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1222 I<????>
1223
1224 =for item1 B<:continued>
1225 # Prophet!
1226 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1227
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1228 which produces:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1229
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1230 =begin nested
1231 =para 1. Retreat to remote Himalayan monastery
1232 =para 2. Learn the hidden mysteries of space and time
1233 =para I<????>
1234 =para 3. Prophet!
1235 =end nested
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1236
1237
1238 =head4 Unordered lists
1239
2c7a3ac [S26] Added Damian's even more latest changes
masak authored
1240 List items that are not C<:numbered> are treated as defining unordered
1241 lists. Typically, such lists are rendered with bullets. For example:
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1242
a563db4 [S26] checked in Damian's latest changes
masak authored
1243 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1244 =item1 Reading
1245 =item2 Writing
1246 =item3 'Rithmetic
a563db4 [S26] checked in Damian's latest changes
masak authored
1247 =end code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1248
1249 might be rendered:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1250
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1251 =for para :nested(1)
1252 E<bull;nbsp;nbsp>Reading
1253 =for para :nested(2)
1254 E<mdash;nbsp;nbsp>Writing
1255 =for para :nested(3)
1256 E<curren;nbsp;nbsp>'Rithmetic
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1257
45ca8c8 @patch fix typos
patch authored
1258 As with numbering styles, the bulletting strategy used for different levels
391cb36 updated S26 to Damian's Perl6-Perldoc-v0.0.2 edition
diakopter authored
1259 within a nested list is entirely up to the renderer.
1260
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1261
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1262 =head4 Multi-paragraph list items
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1263
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1264 Use the delimited form of the C<=item> block to specify items that
1265 contain multiple paragraphs. For example:
c9f3329 Various items for further discussion at the hackathon.
lwall authored
1266
a563db4 [S26] checked in Damian's latest changes
masak authored
1267 =begin code
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1268 Let's consider two common proverbs:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1269
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1270 =begin item :numbered
1271 I<The rain in Spain falls mainly on the plain.>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1272
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1273 This is a common myth and an unconscionable slur on the Spanish
1274 people, the majority of whom are extremely attractive.
1275 =end item
c88d29b r6@Gort: damian | 2006-03-16 10:31:40 +1100
damian authored
1276
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1277 =begin item :numbered
1278 I<The early bird gets the worm.>
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1279
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1280 In deciding whether to become an early riser, it is worth
1281 considering whether you would actually enjoy annelids
1282 for breakfast.
1283 =end item
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1284
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1285 As you can see, folk wisdom is often of dubious value.
a563db4 [S26] checked in Damian's latest changes
masak authored
1286 =end code
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1287
68d8802 * S26: Documentation spec, 2006-11-22 edition, from Damian.
audreyt authored
1288 which produces:
a630d8c * repo-copy S26.pod and S29.pod into docs/Perl6/Spec/.
audreyt authored
1289