[S22] Definition lists, footnotes

Footnotes are incredibly messy for codeblocks, but it looks pretty nice
when rendered in HTML :) .

S22-package-format.pod6

@@ -21,22 +21,26 @@ Synopsis 22: Package Format [DRAFT]
 I'll start by listing a few terms, and whether this document is supposed to cover them or
 not.
 
-=begin item1 
-.jib files; this is the source package format, and is specified in this document
-=end item1
-=begin item1 
-CPAN6; this is a piece of software for managing an archive network (such as CPAN).This is not specified in this document; see L<http://cpan6.org/>
-
-=end item1
-=begin item1 
-PAUSE6; this is an actual network based on the cpan6 software (see above).  It alsois not documented here.
-
-=end item1
-=begin item1 
-CPAN6.pm; this is a piece of software that starts with what it can get on PAUSE6, andattempts to give you an installed perl module (this is a replacement for
+=begin defn
+.jib files
+This is the source package format, and is specified in this document
+=end defn
+=begin defn
+CPAN6
+This is a piece of software for managing an archive network (such as CPAN). This
+is not specified in this document; see L<http://cpan6.org/>
+=end defn
+=begin defn
+PAUSE6
+This is an actual network based on the cpan6 software (see above).  It also is
+not documented here.
+=end defn
+=begin defn
+CPAN6.pm
+This is a piece of software that starts with what it can get on PAUSE6, and
+attempts to give you an installed perl module (this is a replacement for
 CPANPLUS/cpan2dist)
-
-=end item1
+=end defn
 =head2 Inspirations
 
 The following can be useful inspirations:
@@ -45,7 +49,7 @@ The following can be useful inspirations:
 Debian Policy: L<http://www.us.debian.org/doc/debian-policy>
 =end item1
 =begin item1 
-Software::Packager::Metadata:L<http://perlsoftpackmet.svn.sourceforge.net/viewvc/perlsoftpackmet/main/doc/> (click on the
+Software::Packager::Metadata: L<http://perlsoftpackmet.svn.sourceforge.net/viewvc/perlsoftpackmet/main/doc/> (click on the
 link in the Rev. column next to Overview)
 
 =end item1
@@ -126,14 +130,17 @@ This allows us to ship an extra md5sum, version, signature, anything.
 
 =head2 Supported fields
 
+=for code :allow<N>
     - Prefix        Package prefix category     (p5)
     - Name          Perl module name            (Foo-Bar)
     - Version       Perl module version         (1.2.3)
     - Authority     From S11                    (cpan+KANE)
     - Package       Full package name           (p5-Foo-Bar-1.2.3-cpan+kane)
     - Description   Description of function     (This is what it does)
     - Author        CPAN author id              (KANE)
-    - Depends       Packages it depends on[1][2](p5-Foo)
+    - Depends       Packages it depends onN«This is packages, *not* modules. If we need a module -> package
+        mapping, this needs to be done when extracting the data from the
+        compiler, and queried against the available packages cache.»N<See the section on L<Dependencies>>(p5-Foo)
     - Provides      Packages this one provides  (p5-Foo-Bar,
                                                     p5-Foo-Bar-cpan+kane)
 
@@ -146,12 +153,7 @@ C<Package> syntax.
 Again, arguably, the C<Author> and C<Authority> fields overlap, and
 C<Authority> can be made to hold both cases.
 
-    [1] This is packages, *not* modules. If we need a module -> package
-        mapping, this needs to be done when extracting the data from the
-        compiler, and queried against the available packages cache.
-    [2] See the section on L<Dependencies>
-
-=head2 Suggested fields[3]
+=head2 Suggested fieldsN<Steal more tags from debian policy>
 
     - Build-Depends Packages needed to build this package
     - Suggests      Packages suggested by this package
@@ -164,8 +166,6 @@ C<Authority> can be made to hold both cases.
     - Contains      List of modules (and scripts?) contained
                     in the package
 
-    [3] Steal more tags from debian policy
-
 =DEPENDENCIES
 =head2 Dependency Notation
 
@@ -201,17 +201,16 @@ This allows nesting of the above expressions
 
 =head3 More complex examples:
 
+=for code :allow<N>
     a, [b,c]                    # a AND (b OR c)
     { a => 1 }, { a => '< 2' }  # a greater or equal to 1 AND smaller than 2
-    [a, \[ b, c ] ]             # a OR (b AND c) [1]
-
-    [1] This is possibly not portable to other languages. Options seem
+    [a, \[ b, c ] ]             # a OR (b AND c) N«This is possibly not portable to other languages. Options seem
         thin as we don't have some /other/ grouping mechanism than [ ], { }
         and \[ ]; ( ) gets flattened and \( ) == [ ].
         We could abuse { } to create { OR => [ ] } and { AND => [ ] }
         groups, but it would not read very intuitively. It would also mean
         that the version requirements would have to be in the package naming,
-        ie. 'a > 2' rather than a => '> 2'
+        ie. 'a > 2' rather than a => '> 2'»
 
 =head3 Serialization Examples
 
@@ -236,4 +235,4 @@ This allows nesting of the above expressions
         - ...
 
 =comment vim:set expandtab sw=4:
-=end pod
+=end pod