Search
| How I think Perl POD Translators Should Deal with =over/=item/=back | ||
Quote of the Day
How should a translator deal with =over/=item/=back? Here are some examples and what I think should happen.
Note that in all cases the right margin is not specified. It would be up to the translator program to decide if it should remain the same or if it too should be indented.
The =over/=back sequence should be use in the same manner for everything inside it. To change the type of its use, start another sequence.
The =over/=back sequence can be used to indent full paragraphs of the normal and verbatim type. It is done simply by enclosing the paragraphs in a =over/=back pair.
=over This paragraph is to be indent to signify its difference from other paragraphs. Multiple paragraphs can be included. =back
<blockquote>...</blockquote>
Bulleted lists are created by having an =item for every bulleted item. The =item is immediately followed with an asterisk.
=over =item * This paragraph has a bullet and is empathized in some manner, such as bold. This paragraph is indented as the above but does not have a bullet. =item * This paragraph has a bullet and is not empathized. =back
<ul>...</ul>
Numbered lists are created by having an =item for each item. The =item has a number immediately following it. An optional decimal point may be added.
The number does not matter; the translator will replace it with the correct number in the sequence. However, the translator can issue a warning if it encounters number out of order. This warning has the option of being turned off (or on, if the default is off).
=over =item 1. This paragraph is numbered and is empathized in some manner, such as bold. The use of the decimal point is optional. This paragraph is indented as the above but is not numbered. =item 1 This paragraph is numbered and is not empathized. =back
<ol>...</ol>
Dictionary lists, sometimes called Glossary lists, are created by having an =item without an asterisk or number immediately following it. These have the most complex behaviour of all the lists.
=over =item This paragraph is empathized in some manner, such as bold. This paragraph is indented as the above but not highlighted. =item Z<>* This paragraph is highlighted but starts with an asterisk. The C<<< Z<> >>> formatting code is used to prevent the translator in thinking this is a bulleted item. =item Z<>2011-04-20: This paragraph is highlighted but starts with a number. The C<<< Z<> >>> formatting code is used to prevent the translator in thinking this is a numbered item. =item This paragraph is indented and is not empathized. =back
=over =item First =item Second =item Third The above three items are grouped together and associated with this paragraph. =item Fourth Z<> =item Fifth Z<> =item Sixth The above three items are not grouped together. Each is separate from the other. Only the last one is associated with this paragraph. The C<<< Z<> >>> formatting code is used to create empty paragraphs. =back
<dl>
<dt>...</dt>
<dd>...</dd>
...
</dl> 
Send me a comment.
Note: not all comments will be posted.
Copyright 2011 by Shawn H Corey. Some rights reserved.
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
DISCLAIMER:
The information presented here is for entertainment purposes only. The author(s), web host(s), ISP(s), or anyone involved in the creation or distribution of this information is NOT RESPONSIBLE for ANY LOSS, DAMAGE, INJURY or DEATH that may result from the use of this information.