Author image Zahatski Aliaksandr
and 1 contributors


Perl6::Pod::Block::item - lists


     =item  Happy
     =item  Dopey
     =item  Sleepy

     =item1  Animal
     =item2     Vertebrate
     =item2     Invertebrate


Lists in Pod are specified as a series of contiguous =item blocks. No special "container" directives or other delimiters are required to enclose the entire list. For example:

     The seven suspects are:

     =item  Happy
     =item  Dopey
     =item  Sleepy
     =item  Bashful
     =item  Sneezy
     =item  Grumpy
     =item  Keyser Soze

List items have one implicit level of nesting:

Lists may be multi-level, with items at each level specified using the =item1, =item2, =item3, etc. blocks. Note that =item is just an abbreviation for =item1. For example:

     =item1  Animal
     =item2     Vertebrate
     =item2     Invertebrate

     =item1  Phase
     =item2     Solid
     =item2     Liquid
     =item2     Gas
     =item2     Chocolate

Note that item blocks within the same list are not physically nested. That is, lower-level items should not be specified inside higher-level items:

    =comment WRONG...
    =begin item1          --------------
    The choices are:                    |
    =item2 Liberty        ==< Level 2   |==<  Level 1
    =item2 Death          ==< Level 2   |
    =item2 Beer           ==< Level 2   |
    =end item1            --------------

    =comment CORRECT...
    =begin item1          ---------------
    The choices are:                     |==< Level 1
    =end item1            ---------------
    =item2 Liberty        ==================< Level 2
    =item2 Death          ==================< Level 2
    =item2 Beer           ==================< Level 2

Ordered lists

An item is part of an ordered list if the item has a :numbered configuration option:

     =for item1 :numbered
     =for item2 :numbered
     =for item2 :numbered
     =for item2 :numbered

Alternatively, if the first word of the item consists of a single # character, the item is treated as having a :numbered option:

     =item1  # Visito
     =item2     # Veni
     =item2     # Vidi
     =item2     # Vici

To specify an unnumbered list item that starts with a literal #, either make the octothorpe verbatim:

    =item V<#> introduces a comment

or explicitly mark the item itself as being unnumbered:

    =for item :!numbered
    # introduces a comment

Unordered lists

List items that are not :numbered are treated as defining unordered lists. Typically, such lists are rendered with bullets. For example:

    =item1 Reading
    =item2 Writing
    =item3 'Rithmetic

Multi-paragraph list items

Use the delimited form of the =item block to specify items that contain multiple paragraphs. For example:

     Let's consider two common proverbs:
     =begin item :numbered
     I<The rain in Spain falls mainly on the plain.>
     This is a common myth and an unconscionable slur on the Spanish
     people, the majority of whom are extremely attractive.
     =end item
     =begin item :numbered
     I<The early bird gets the worm.>
     In deciding whether to become an early riser, it is worth
     considering whether you would actually enjoy annelids
     for breakfast.
     =end item

     As you can see, folk wisdom is often of dubious value.

Definition lists

    =defn  MAD
    Affected with a high degree of intellectual independence.

    =defn  MEEKNESS
    Uncommon patience in planning a revenge that is worth while.

    Conforming to a local and mutable standard of right.
    Having the quality of general expediency.



Unordered lists
  =item Milk
  =item Toilet Paper
  =item Cereal
  =item Bread

  # <ul> - unordered list; bullets
   <li>Toilet Paper</li>
    =for item :numbered
    Find a Job
    =item # Get Money
    =item # Move Out

  # <ol> - ordered list; numbers (<ol start="4" > for :continued)
     <li>Find a Job</li>
     <li>Get Money</li>
     <li>Move Out</li>
definition list; dictionary
     =defn Fromage
     French word for cheese.
     =defn Voiture
     French word for car.

    * <dl> - defines the start of the list
    * <dt> - definition term
    * <dd> - defining definition

     <dd>French word for cheese.</dd>
     <dd>French word for car.</dd>

SEE ALSO, Perldoc Pod to HTML converter:, Perl6::Pod::Lib


Zahatski Aliaksandr, <>


Copyright (C) 2009-2015 by Zahatski Aliaksandr

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.