Changeset 2742

Timestamp:

07/09/08 20:16:36 (16 months ago)

Author:

bchoate

Message:

Updated POD for template tags; added test for template tag doc coverage.

Location:

branches/release-41

Files:

• lib/MT/Template/Context/Search.pm (modified) (6 diffs)
• lib/MT/Template/ContextHandlers.pm (modified) (343 diffs)
• t/91-tagcoverage.t (added)

branches/release-41/lib/MT/Template/Context/Search.pm

@@ -39 +39 @@
 ###########################################################################
 
+=head2 IfStraightSearch
+
+A conditional block which outputs its contents if the search in progress
+is a regular (or "straight") search.
+
+=for tags search
+
+=cut
+
+###########################################################################
+
+=head2 IfTagSearch
+
+A conditional block which outputs its contents if the search in progress
+is a search of entries by tag.
+
+=for tags search
+
+=cut
+
+###########################################################################
+
+=head2 NoSearch
+
+A container tag whose contents are displayed only if there is no search
+performed.
+
+This tag is only recognized in search templates.
+
+=for tags search
+
+=cut
+
+###########################################################################
+
+=head2 NoSearchResults
+
+A container tag whose contents are displayed if a search is performed
+but no results are found.
+
+This tag is only recognized in search templates.
+
+=for tags search
+
+=cut
+
+###########################################################################
+
 =head2 SearchResultsHeader
 
@@ -48 +96 @@
 This tag is only recognized in SearchResults block.
 
+B<Example:>
+
+    <mt:SearchResultsHeader>
+    <h3>Look what we found!</h3>
+    </mt:SearchResultsHeader>
+
 =for tags search
 
@@ -61 +115 @@
 
 This tag is only recognized in SearchResults block.
+
+B<Example:>
+
+    <mt:SearchResultsFooter>
+    <p>If you didn't find what you were looking for, you can also peruse
+    the <a href="<mt:Link identifier="archive_index">">site archives</a>.</p>
+    </mt:SearchResultsFooter>
 
 =for tags search
@@ -110 +171 @@
 This tag is only recognized in search templates.
 
+=for tags search
+
 =cut
 
@@ -124 +187 @@
 =cut
 
+###########################################################################
+
+=head2 SearchIncludeBlogs
+
+Used in the search result template to pass the IncludeBlogs parameters
+through from the search form keeping the context of any followup search
+the same as the initial search.
+
+B<Example:>
+
+    <input type="hidden" name="IncludeBlogs" value="<$mt:SearchIncludeBlogs$>" />
+
+=cut
+
 sub _hdlr_include_blogs { $_[0]->stash('include_blogs') || '' }
+
+###########################################################################
+
+=head2 SearchString
+
+An HTML-encoded search query. This tag is only recognized in search templates.
+
+B<Example:>
+
+    <$mt:SearchString$>
+
+=for tags search
+
+=cut
+
 sub _hdlr_search_string { $_[0]->stash('search_string') || '' }
+
+###########################################################################
+
+=head2 SearchTemplateID
+
+Returns the identifier of the search template (ie, "feed" or
+"nomorepizzaplease").
+
+B<Example:>
+
+    <$mt:SearchTemplateID$>
+
+=for tags search
+
+=cut
+
 sub _hdlr_template_id { $_[0]->stash('template_id') || '' }
 sub _hdlr_max_results { $_[0]->stash('maxresults') || '' }
+
+###########################################################################
+
+=head2 SearchResultCount
+
+The number of results found across all of the blogs searched. This tag
+is only recognized in search templates.
+
+B<Example:>
+
+    <$mt:SearchResultCount$>
+
+=for tags search, count
+
+=cut
 
 sub _hdlr_result_count {
@@ -133 +256 @@
     $results ? $results : 0;
 }
+
+###########################################################################
+
+=head2 SearchResults
+
+A container tag that creates a list of search results. This tag
+creates an entry and blog context that all Entry* and Blog* tags
+can be used.
+
+This tag is only recognized in search templates.
+
+=for tags search
+
+=cut
 
 sub _hdlr_results {

branches/release-41/lib/MT/Template/ContextHandlers.pm

@@ -1075 +1075 @@
 ###########################################################################
 
+=head2 string_format
+
+An alias for the 'sprintf' modifier.
+
+=cut
+
+###########################################################################
+
 =head2 sprintf
 
@@ -1228 +1236 @@
 =over 4
 
-=item html
+=item * html
 
 Similar to the 'encode_html' modifier. Escapes special characters as
 HTML entities.
 
-=item url
+=item * url
 
 Similar to the 'encode_url' modifier. Escapes special characters using
 a URL-encoded format (ie, " " becomes "%20").
 
-=item javascript or js
+=item * javascript or js
 
 Similar to the 'encode_js' modifier. Escapes special characters such
@@ -1244 +1252 @@
 in a JavaScript string.
 
-=item mail
+=item * mail
 
 A very simple email obfuscation technique.
@@ -1455 +1463 @@
 ###########################################################################
 
+=head2 TemplateNote
+
+A function tag that always returns an empty string. This tag is useful
+for placing simple notes in your templates, since it produces nothing.
+
+B<Example:>
+
+    <$mt:TemplateNote note="Hi, mom!"$>
+
+=for tags templating
+
+=cut
+
+###########################################################################
+
+=head2 Ignore
+
+A block tag that always produces an empty string. This tag is useful
+for wrapping template code you wish to disable, or perhaps annotating
+sections of your template.
+
+B<Example:>
+
+    <mt:Ignore>
+        The API key for the following tag is D3ADB33F.
+    </mt:Ignore>
+
+=for tags templating
+
+=cut
+
+###########################################################################
+
+=head2 IfStatic
+
+Returns true if the current publishing context is static publishing,
+and false otherwise.
+
+=for tags templating, utility
+
+=cut
+
+###########################################################################
+
+=head2 IfDynamic
+
+Returns true if the current publishing context is dynamic publishing,
+and false otherwise.
+
+=for tags templating, utility
+
+=cut
+
+###########################################################################
+
 =head2 App:Listing
 
@@ -1526 +1589 @@
 =over 4
 
-=item type (optional)
+=item * type (optional)
 
 The C<MT::Object> object type the listing is processing. If unset,
 will use the contents of the C<object_type> variable.
 
-=item loop (optional)
+=item * loop (optional)
 
 The source of data to process. This is an array of hashes, similar
@@ -1537 +1600 @@
 variable is used instead.
 
-=item empty_message (optional)
+=item * empty_message (optional)
 
 Used when there are no rows to output for the listing. If not set,
@@ -1544 +1607 @@
 found.
 
-=item id (optional)
+=item * id (optional)
 
 Used to construct the DOM id for the listing. The outer C<div> tag
@@ -1551 +1614 @@
 attribute).
 
-=item listing_class (optional)
+=item * listing_class (optional)
 
 Provides a custom class name that can be applied to the main
@@ -1557 +1620 @@
 that is always applied).
 
-=item action (optional; default 'script_url' variable)
+=item * action (optional; default 'script_url' variable)
 
 Supplies the 'action' attribute of the C<form> tag produced.
 
-=item hide_pager (optional; default '0')
+=item * hide_pager (optional; default '0')
 
 Controls whether the pagination controls are shown or not.
 If unspecified, pagination is shown.
 
-=item show_actions (optional; default '1')
+=item * show_actions (optional; default '1')
 
 Controls whether the actions associated with the object type
@@ -1677 +1740 @@
 =over 4
 
-=item mode
+=item * mode
 
 Maps to a '__mode' argument.
 
-=item type
+=item * type
 
 Maps to a '_type' argument.
@@ -1741 +1804 @@
 =over 4
 
-=item bar_position (optional; default "top")
+=item * bar_position (optional; default "top")
 
 Assigns a CSS class name indicating whether the control is above or
 below the listing or edit form it is associated with.
 
-=item hide_pager
+=item * hide_pager
 
 Assign either 1 or 0 to control whether the pagination controls are
 displayed or not.
 
-=item form_id
+=item * form_id
 
 Associates the pagition controls and item action widget with the
@@ -1793 +1856 @@
 =over 4
 
-=item id (optional)
+=item * id (optional)
 
 If specified, will be used as the 'id' attribute for the outermost C<div>
@@ -1799 +1862 @@
 variable instead.
 
-=item label (required)
+=item * label (required)
 
 The label to display above the widget.
 
-=item label_link (optional)
+=item * label_link (optional)
 
 If specified, this link will wrap the label for the widget.
 
-=item label_onclick
+=item * label_onclick
 
 If specified, this JavaScript code will be assigned to the 'onclick'
 attribute of a link tag wrapping the widget label.
 
-=item class (optional)
+=item * class (optional)
 
 If unspecified, will use the id of the widget. This class is included in the
 'class' attribute of the outermost C<div> tag for the widget.
 
-=item header_action
-
-=item can_close (optional; default "0")
+=item * header_action
+
+=item * can_close (optional; default "0")
 
 Identifies whether widget may be closed or not.
 
-=item tabbed (optional; default "0")
+=item * tabbed (optional; default "0")
 
 If specified, the widget will be assigned an attribute that gives it
@@ -1932 +1995 @@
 =over 4
 
-=item id (optional)
-
-=item class (optional; default "info")
-
-=item rebuild (optional)
+=item * id (optional)
+
+=item * class (optional; default "info")
+
+=item * rebuild (optional)
 
 Accepted values: "all", "index".
 
-=item can_close (optional; default "1")
+=item * can_close (optional; default "1")
 
 =back
@@ -2063 +2126 @@
 =over 4
 
-=item action (optional)
+=item * action (optional)
 
 Identifies the URL to submit the form to. If not given, will use
 the current application URI.
 
-=item method (optional; default "POST")
+=item * method (optional; default "POST")
 
 Supplies the C<form> method. "GET" or "POST" are the typical values
 for this, but will accept any HTTP-compatible method (ie: "PUT", "DELETE").
 
-=item object_id (optional)
+=item * object_id (optional)
 
 Populates a hidden 'id' field in the form. If not given, will also use any
 'id' template variable defined.
 
-=item blog_id (optional)
+=item * blog_id (optional)
 
 Populates a hidden 'blog_id' field in the form. If not given, will also use
 any 'blog_id' template variable defined.
 
-=item object_type (optional)
+=item * object_type (optional)
 
 Populates a hidden '_type' field in the form. If not given, will also use
 any 'type' template variable defined.
 
-=item id (optional)
+=item * id (optional)
 
 Used to form the 'id' element of the HTML C<form> tag. If not specified,
@@ -2094 +2157 @@
 determined object_type.
 
-=item name (optional)
+=item * name (optional)
 
 Supplies the C<form> name attribute. If unspecified, will use the C<id>
 attribute, if available.
 
-=item enctype (optional)
+=item * enctype (optional)
 
 If assigned, sets an 'enctype' attribute on the C<form> tag using the value
@@ -2175 +2238 @@
 =over 4
 
-=item id (required)
+=item * id (required)
 
 A unique identifier for this group of settings.
 
-=item class (optional)
+=item * class (optional)
 
 If specified, applies this CSS class to the C<fieldset> tag produced.
 
-=item shown (optional; default "1")
+=item * shown (optional; default "1")
 
 Controls whether the C<fieldset> is initially shown or not. If hidden,
@@ -2230 +2293 @@
 =over 4
 
-=item id (required)
+=item * id (required)
 
 Each application setting tag requires a unique 'id' attribute. This id
 should not be re-used within the template.
 
-=item required (optional; default "0")
+=item * required (optional; default "0")
 
 Controls whether the field is displayed with visual cues that the
 field is a required field or not.
 
-=item label
+=item * label
 
 Supplies the label phrase for the setting.
 
-=item show_label (optional; default "1")
+=item * show_label (optional; default "1")
 
 Controls whether the label portion of the setting is shown or not.
 
-=item shown (optional; default "1")
+=item * shown (optional; default "1")
 
 Controls whether the setting is visible or not. If specified, adds
@@ -2254 +2317 @@
 setting.
 
-=item label_class (optional)
+=item * label_class (optional)
 
 Allows an additional CSS class to be applied to the label of the
 setting.
 
-=item content_class (optional)
+=item * content_class (optional)
 
 Allows an addtional CSS class to be applied to the contents of the
 setting.
 
-=item hint (optional)
+=item * hint (optional)
 
 Supplies a "hint" phrase that provides inline instruction to the user.
@@ -2270 +2333 @@
 forces it to display.
 
-=item show_hint (optional; default "0")
+=item * show_hint (optional; default "0")
 
 Controls whether the inline help 'hint' label is shown or not.
 
-=item warning
+=item * warning
 
 Supplies a warning message to the user regarding the use of this setting.
 
-=item show_warning
+=item * show_warning
 
 Controls whether the warning message is shown or not.
 
-=item help_page
+=item * help_page
 
 Identifies a specific page of the MT help documentation for this setting.
 
-=item help_section
+=item * help_section
 
 Identifies a section name of the MT help documentation for this setting.
@@ -2408 +2471 @@
 =over 4
 
-=item var (optional)
+=item * var (optional)
 
 If assigned, the current 'index' of the loop is assigned to this template
 variable.
 
-=item from (optional; default "0")
-
-=item start
+=item * from (optional; default "0")
+
+=item * start
 
 Identifies the starting number for the loop.
 
-=item to
-
-=item end
+=item * to
+
+=item * end
 
 Identifies the ending number for the loop. Either 'to' or 'end' must
 be specified.
 
-=item step (optional; default "1")
-
-=item increment
+=item * step (optional; default "1")
+
+=item * increment
 
 Provides the amount to increment the loop counter.
 
-=item glue (optional)
+=item * glue (optional)
 
 If specified, this string is added inbetween each block of the loop.
@@ -2442 +2505 @@
 =over 4
 
-=item __first__
+=item * __first__
 
 Assigned 1 when the loop is in the first iteration.
 
-=item __last__
+=item * __last__
 
 Assigned 1 when the loop is in the last iteration.
 
-=item __odd__
+=item * __odd__
 
 Assigned 1 when the loop index is odd, 0 when it is even.
 
-=item __even__
+=item * __even__
 
 Assigned 1 when the loop index is even, 0 when it is odd.
 
-=item __index__
+=item * __index__
 
 Holds the current loop index value, even if the 'var' attribute has
 been given.
 
-=item __counter__
+=item * __counter__
 
 Tracks the number of times the loop has run (starts at 1).
@@ -2597 +2660 @@
 =over 4
 
-=item name
-
-=item var
+=item * name
+
+=item * var
 
 Declares a variable to test. When none of the comparison attributes are
@@ -2605 +2668 @@
 a "true" value, meaning if it is assigned a non-empty, non-zero value.
 
-=item tag
+=item * tag
 
 Declares a MT tag to execute; the value of which is used for testing.
@@ -2613 +2676 @@
 If tag passes through the logical result of that conditional tag.
 
-=item op
+=item * op
 
 If specified, applies the specified mathematical operator to the value
@@ -2621 +2684 @@
 =over 4
 
-=item + or add
+=item * + or add
 
 Addition.
 
-=item - or sub
+=item * - or sub
 
 Subtraction.
 
-=item ++ or inc
+=item * ++ or inc
 
 Adds 1 to the given value.
 
-=item -- or dec
+=item * -- or dec
 
 Subtracts 1 from the given value.
 
-=item * or mul
+=item * * or mul
 
 Multiplication.
 
-=item / or div
+=item * / or div
 
 Division.
 
-=item % or mod
+=item * % or mod
 
 Issues a modulus operator.
@@ -2651 +2714 @@
 =back
 
-=item value
+=item * value
 
 Used in conjunction with the 'op' attribute.
 
-=item eq
+=item * eq
 
 Tests whether the given value is equal to the value of the 'eq' attribute.
 
-=item ne
+=item * ne
 
 Tests whether the given value is not equal to the value of the 'ne' attribute.
 
-=item gt
+=item * gt
 
 Tests whether the given value is greater than the value of the 'gt' attribute.
 
-=item lt
+=item * lt
 
 Tests whether the given value is less than the value of the 'lt' attribute.
 
-=item ge
+=item * ge
 
 Tests whether the given value is greater than or equal to the value of the
 'ge' attribute.
 
-=item le
+=item * le
 
 Tests whether the given value is less than or equal to the value of the
 'le' attribute.
 
-=item like
+=item * like
 
 Tests whether the given value matches the regex pattern in the 'like'
 attribute.
 
-=item test
+=item * test
 
 Uses a Perl (or PHP under Dynamic Publishing) expression. For Perl, this
@@ -2969 +3032 @@
 ###########################################################################
 
+=head2 Unless
+
+A conditional tag that is the logical opposite of the L<If> tag. All
+attributes supported by the L<If> tag are also supported for this tag.
+
+=for tags templating
+
+=cut
+
+###########################################################################
+
 =head2 Loop
 
@@ -2981 +3055 @@
 =over 4
 
-=item name
-
-=item var
+=item * name
+
+=item * var
 
 The template variable that contains the array of hashref data to
 process.
 
-=item sort_by (optional)
+=item * sort_by (optional)
 
 Causes the data in the given array to be resorted in the manner
@@ -3000 +3074 @@
     sort_by="key reverse"; sort_by="value numeric"
 
-=item glue (optional)
+=item * glue (optional)
 
 If specified, this string will be placed inbetween each "row"
@@ -3012 +3086 @@
 =over 4
 
-=item __first__
+=item * __first__
 
 Assigned when the loop is in the first iteration.
 
-=item __last__
+=item * __last__
 
 Assigned when the loop is in the last iteration.
 
-=item __odd__
+=item * __odd__
 
 Assigned 1 when the loop is on odd numbered rows, 0 when even.
 
-=item __even__
+=item * __even__
 
 Assigned 1 when the loop is on even numbered rows, 0 when odd.
 
-=item __key__
+=item * __key__
 
 When looping over a hashref template variable, this variable is
 assigned the key currently in context.
 
-=item __value__
+=item * __value__
 
 This variable holds the value of the array or hashref element
@@ -3138 +3212 @@
 An alias for the 'Var' tag, and considered deprecated in favor of 'Var'.
 
+=for tags deprecated
+
 =cut
 
@@ -3150 +3226 @@
 =over 4
 
-=item name (or var)
+=item * name (or var)
 
 Identifies the template variable. The 'name' attribute supports a variety
@@ -3175 +3251 @@
     <mt:Var name="count(foo)">
 
-=item op
+=item * op
 
 Along with the 'value' attribute, this allows the application of
@@ -3181 +3257 @@
 are supported).
 
-=item value
+=item * value
 
 If provided with the 'op' attribute, provides the operand for the
@@ -3190 +3266 @@
 is useful for setting variables as well.
 
-=item function
+=item * function
 
 For array template variables, this attribute supports:
@@ -3196 +3272 @@
 =over 4
 
-=item pop
+=item * pop
 
 Takes an element from the end of the array (last element).
 
-=item shift
+=item * shift
 
 Takes an element from the front of the array (index 0).
 
-=item count
+=item * count
 
 Returns the number of elements in the array template variable.
@@ -3214 +3290 @@
 =over 4
 
-=item delete
+=item * delete
 
 Only valid when used with the 'key' attribute, or if a key is present
 in the variable name.
 
-=item count
+=item * count
 
 Returns the number of keys present in the hash template variable.
@@ -3225 +3301 @@
 =back
 
-=item index
+=item * index
 
 Identifies an element of an array template variable.
 
-=item key
+=item * key
 
 Identifies a key of a hash template variable.
 
-=item default
+=item * default
 
 If the variable is undefined or empty, this value will be output instead.
 
-=item to_json
+=item * to_json
 
 Formats the variable in JSON notation.
 
-=item glue
+=item * glue
 
 For array template variables, this attribute is used in joining the
@@ -3437 +3513 @@
 =over 4
 
-=item tag or name
+=item * tag or name
 
 If either 'name' or 'tag' are specified, tests the entry in context
@@ -3553 +3629 @@
 =over 4
 
-=item glue
+=item * glue
 
 A text string that is used to join each of the items together. For example
@@ -3561 +3637 @@
 would print out each tag name separated by a comma and a space.
 
-=item type
+=item * type
 
 The kind of object for which to show tags. By default the entry tags are shown.
 
-=item sort_by
+=item * sort_by
 
 The tag object column on which to order the tags. Common values are name and
 rank. By default tags are sorted by name.
 
-=item sort_order
+=item * sort_order
 
 The direction in which to sort tags by the sort_by field. Possible values
@@ -3576 +3652 @@
 when sorted by name and descending order when sorted by other columns.
 
-=item limit
+=item * limit
 
 A number of tags to show. If given, only the first tags as ordered by
 sort_by and sort_order are shown.
 
-=item top
+=item * top
 
 A number of tags to show. If given, only the given number of tags with
@@ -3817 +3893 @@
 =over 4
 
-=item max (optional; default "6")
+=item * max (optional; default "6")
 
 Allows a user to specify the upper bound of the scale.
@@ -3931 +4007 @@
 
 To avoid printing out the leading text when no entry tags are assigned you
-can use the EntryIfTagged conditional block to first test for entry tags
-on the entry. You can also use the EntryIfTagged conditional block with
+can use the L<EntryIfTagged> conditional block to first test for entry tags
+on the entry. You can also use the L<EntryIfTagged> conditional block with
 the tag attribute to test for the assignment of a particular entry tag.
 
@@ -3939 +4015 @@
 =over 4
 
-=item glue
+=item * glue
 
 A text string that is used to join each of the items together. For example:
 
-    <mt:EntryTags glue=", "><$MTTagName$></mt:EntryTags>
+    <mt:EntryTags glue=", "><$mt:TagName$></mt:EntryTags>
 
 would print out each tag name separated by a comma and a space.
@@ -3951 +4027 @@
 B<Example:>
 
-The following code can be used anywhere MTEntries can be used. It prints
+The following code can be used anywhere L<Entries> can be used. It prints
 a list of all of the tags assigned to each entry returned by L<Entries>
 glued together by a comma and a space.
@@ -3995 +4071 @@
 ###########################################################################
 
+=head2 TagLabel
+
+An alias for the 'TagName' tag.
+
+=cut
+
+###########################################################################
+
 =head2 TagName
 
@@ -4003 +4087 @@
 =over 4
 
-=item normalize (optional; default "0")
+=item * normalize (optional; default "0")
 
 If specified, outputs the "normalized" form of the tag. A normalized
@@ -4011 +4095 @@
 =over 4
 
-=item quote (optional; default "0")
+=item * quote (optional; default "0")
 
 If specified, causes any tag with spaces in it to be wrapped in quote
@@ -4229 +4313 @@
 =over 4
 
-=item type
-
-=item archive_type
+=item * type
+
+=item * archive_type
 
 The archive type to test for, case-insensitively. See L<ArchiveType> for
@@ -4276 +4360 @@
 =over 4
 
-=item type or archive_type
+=item * type or archive_type
 
 Specifies the name of the archive type you wish to check to see if it is enabled.
@@ -4354 +4438 @@
 =over 4
 
-=item var (optional)
+=item * var (optional)
 
 Supplies a variable name to use for assigning the contents of the
@@ -4387 +4471 @@
 =over 4
 
-=item module
+=item * module
 
 The name of a template module in the current blog.
 
-=item widget
+=item * widget
 
 The name of the widget in the current blog to include.
 
-=item file
+=item * file
 
 The path to an external file on the system. The path can be absolute or
@@ -4402 +4486 @@
 includes like that found in PHP.
 
-=item identifier
+=item * identifier
 
 For selecting Index templates by their unique identifier.
@@ -4411 +4495 @@
 filename to load.
 
-=item blog_id (optional)
+=item * blog_id (optional)
 
 Used to include a template from another blog in the system. Use in
 conjunction with the module, widget or identifier attributes.
 
-=item global (optional; default "0")
+=item * global (optional; default "0")
 
 Forces an Include of a globally defined template even if the
@@ -4422 +4506 @@
 (For module, widget and identifier includes.)
 
-=item ssi (optional; default "0")
+=item * ssi (optional; default "0")
 
 If specified, causes the include to be handled as a server-side
@@ -4443 +4527 @@
 Suitable for module, widget or identifier includes.
 
-=item cache (optional; default "0")
+=item * cache (optional; default "0")
 
 Enables caching of the contents of the include. Suitable for module,
 widget or identifier includes.
 
-=item key or cache_key (optional)
+=item * key or cache_key (optional)
 
 Used to cache the template module. Used in conjunction with the 'cache'
 attribute. Suitable for module, widget or identifier includes.
 
-=item ttl (optional)
+=item * ttl (optional)
 
 Specifies the lifetime in seconds of a cached template module. Suitable
@@ -4791 +4875 @@
 =over 4
 
-=item format
+=item * format
 
 A required attribute that defines the template with a string of specifiers.
@@ -4801 +4885 @@
 =over 4
 
-=item %a
+=item * %a
 
 The entry's author's display name passed through the dirify global filter. Example: melody_nelson
 
-=item %-a
+=item * %-a
 
 The same as above except using dashes. Example: melody-nelson
 
-=item %b
+=item * %b
 
 For individual archive mappings, this returns the basename of the entry. By
@@ -4816 +4900 @@
 entry screen. Example: my_summer_vacation
 
-=item %-b
+=item * %-b
 
 Same as above but using dashes. Example: my-summer-vacation
 
-=item %c
+=item * %c
 
 The entry's primary category/subcategory path, built using the category
 basename field. Example: arts_and_entertainment/tv_and_movies
 
-=item %-c
+=item * %-c
 
 Same as above but using dashes. Example: arts-and-entertainment/tv-and-movies
 
-=item %C
+=item * %C
 
 The entry's primary category label passed through the dirify global filter. Example: arts_and_entertainment
 
-=item %-C
+=item * %-C
 
 Same as above but using dashes. Example: arts-and-entertainment
 
-=item %d
+=item * %d
 
 2-digit day of the month. Example: 09
 
-=item %D
+=item * %D
 
 3-letter language-dependent abbreviation of the week day. Example: Tue
 
-=item %e
+=item * %e
 
 A numeric entry ID padded with leading zeroes to six digits. Example: 000040
 
-=item %E
+=item * %E
 
 The entry's numeric ID. Example: 40
 
-=item %f
+=item * %f
 
 Archive filename with the specified extension. This can be used instead of
@@ -4859 +4943 @@
 Example: entry_basename.html or index.html
 
-=item %F
+=item * %F
 
 Same as above but without the file extension. Example: filename
 
-=item %h
+=item * %h
 
 2-digit hour on a 24-hour clock with a leading zero if applicable.
 Example: 09 for 9am, 16 for 4pm
 
-=item %H
+=item * %H
 
 2-digit hour on a 24-hour clock without a leading zero if applicable.
 Example: 9 for 9am, 16 for 4pm
 
-=item %i
+=item * %i
 
 The setting of the IndexBasename configuration directive with the default
 file extension appended. Example: index.html
 
-=item %I
+=item * %I
 
 Same as above but without the file extension. Example: index
 
-=item %j
+=item * %j
 
 3-digit day of year, zero-padded. Example: 040
 
-=item %m
+=item * %m
 
 2-digit month, zero-padded. Example: 07
 
-=item %M
+=item * %M
 
 3-letter language-dependent abbreviation of the month. Example: Sep
 
-=item %n
+=item * %n
 
 2-digit minute, zero-padded. Example: 04
 
-=item %s
+=item * %s
 
 2-digit second, zero-padded. Example: 01
 
-=item %x
+=item * %x
 
 File extension with a leading dot (.). If a file extension has not
 been specified a blank string is returned. Example: .html
 
-=item %y
+=item * %y
 
 4-digit year. Example: 2005
 
-=item %Y
+=item * %Y
 
 2-digit year with zero-padding. Example: 05
@@ -5028 +5112 @@
 B<Attributes:>
 
-=item template
+=item * template
 
 The name of the index template.
 
-=item identifier
+=item * identifier
 
 A template identifier.
 
-=item entry_id
+=item * entry_id
 
 The numeric system ID of the entry.
 
-=item with_index (optional; default "0")
+=item * with_index (optional; default "0")
 
 If not set to 1, remove index filenames (by default, index.html)
@@ -5118 +5202 @@
 =over 4
 
-=item version (optional; default "0")
+=item * version (optional; default "0")
 
 If specified, also outputs the version (same as L<Version>).
@@ -5214 +5298 @@
 =over 4
 
-=item tag
+=item * tag
 
 A tag which is evaluated and tested for non-emptiness.
 
-=item name or var
+=item * name or var
 
 A variable whose contents are tested for non-emptiness.
@@ -5264 +5348 @@
 =over 4
 
-=item tag
+=item * tag
 
 A tag which is evaluated and tested for non-zeroness.
 
-=item name or var
+=item * name or var
 
 A variable whose contents are tested for non-zeroness.
@@ -5425 +5509 @@
 =over 4
 
-=item var or name
+=item * var or name
 
 Identifies the name of the template variable. See L<Var> for more
 information on the format of this attribute.
 
-=item value
+=item * value
 
 The value to assign to the variable.
 
-=item op (optional)
+=item * op (optional)
 
 See the L<Var> tag for more information about this attribute.
 
-=item prepend (optional)
+=item * prepend (optional)
 
 If specified, places the contents at the front of any existing value
 for the template variable.
 
-=item append (optional)
+=item * append (optional)
 
 If specified, places the contents at the end of any existing value
@@ -5450 +5534 @@
 =back
 
-=for tags templating
+=for tags deprecated
 
 =cut
@@ -5466 +5550 @@
 =over 4
 
-=item var or name (required)
+=item * var or name (required)
 
 Identifies the name of the template variable. See L<Var> for more
 information on the format of this attribute.
 
-=item op (optional)
+=item * op (optional)
 
 See the L<Var> tag for more information about this attribute.
 
-=item prepend (optional)
+=item * prepend (optional)
 
 If specified, places the contents at the front of any existing value
 for the template variable.
 
-=item append (optional)
+=item * append (optional)
 
 If specified, places the contents at the end of any existing value
@@ -5504 +5588 @@
 =over 4
 
-=item var or name (required)
+=item * var or name (required)
 
 Identifies the name of the template variable. See L<Var> for more
@@ -5896 +5980 @@
 }
 
-=for tags search
+###########################################################################
+
+=head2 MaxResults
+
+Deprecated in favor of L<SearchMaxResults>.
+
+=for tags deprecated
+
+=cut
 
 ###########################################################################
@@ -5903 +5995 @@
 
 Returns the value of the C<SearchMaxResults> or C<MaxResults> configuration
-setting.  Use C<SearchMaxResults> because MaxResults is considered deprecated.
+setting. Use C<SearchMaxResults> because MaxResults is considered deprecated.
 
 =for tags search, configuration
@@ -6048 +6140 @@
 =over 4
 
-=item display_name
+=item * display_name
 
 Specifies a particular author to select.
 
-=item lastn
+=item * lastn
 
 Limits the selection of authors to the specified number.
 
-=item sort_by (optional)
+=item * sort_by (optional)
 
 Supported values: display_name, name, created_on.
 
-=item sort_order (optional; default "ascend")
+=item * sort_order (optional; default "ascend")
 
 Supported values: ascend, descend.
 
-=item roles
+=item * roles
 
 A comma separated list of roles used to select users by.
 eg: "Author, Commenter".
 
-=item need_entry (optional; default "1")
+=item * need_entry (optional; default "1")
 
 Identifies whether the author(s) must have published an entry
 to be included or not.
 
-=item status (optional; default "enabled")
+=item * status (optional; default "enabled")
 
 Supported values: enabled, disabled.
 
-=item namespace
+=item * namespace
 
 Used in conjunction with the "min*", "max*" attributes to
 select authors based on a particular scoring mechanism.
 
-=item min_score
+=item * min_score
 
 If 'namespace' is also specified, filters the authors based on
@@ -6089 +6181 @@
 to consider the author for inclusion.
 
-=item max_score
+=item * max_score
 
 If 'namespace' is also specified, filters the authors based on
@@ -6095 +6187 @@
 to consider the author for inclusion.
 
-=item min_rank
+=item * min_rank
 
 If 'namespace' is also specified, filters the authors based on
@@ -6101 +6193 @@
 to consider the author for inclusion.
 
-=item max_rate
+=item * max_rate
 
 If 'namespace' is also specified, filters the authors based on
@@ -6107 +6199 @@
 to consider the author for inclusion.
 
-=item min_count
+=item * min_count
 
 If 'namespace' is also specified, filters the authors based on
@@ -6113 +6205 @@
 to consider the author for inclusion.
 
-=item max_count
+=item * max_count
 
 If 'namespace' is also specified, filters the authors based on
@@ -6504 +6596 @@
 ###########################################################################
 
-=head2 AuthorIconURL
+=head2 AuthorAuthIconURL
 
 Returns URL to a small (16x16) image represents in what authentication
@@ -6516 +6608 @@
 =over 4
 
-=item size (optional; default "logo_small")
+=item * size (optional; default "logo_small")
 
 Identifies the requested size of the logo. This is an identifier,
@@ -6676 +6768 @@
 =over 4
 
-=item blog_ids
+=item * blog_ids
 
 This attribute allows you to limit the set of blogs iterated over by
@@ -6741 +6833 @@
 ###########################################################################
 
+=head2 IfBlog
+
+A conditional tag that produces its contents when there is a blog in
+context. This tag is useful for situations where a blog may or may not
+be in context, such as the search template, when a search is conducted
+across all blogs.
+
+B<Example:>
+
+    <mt:IfBlog>
+        <h1>Search results for <$mt:BlogName$>:</h1>
+    <mt:Else>
+        <h1>Search results from all blogs:</h1>
+    </mt:IfBlog>
+
+=for tags blogs
+
+=cut
+
+###########################################################################
+
 =head2 BlogID
 
@@ -6889 +7002 @@
 =over 4
 
-=item no_colon (optional; default "0")
+=item * no_colon (optional; default "0")
 
 If specified, will produce the timezone without the ":" character
@@ -6925 +7038 @@
 =over 4
 
-=item locale (optional; default "0")
+=item * locale (optional; default "0")
 
 If assigned, will format the language in the style "language_LOCALE" (ie: "en_US", "de_DE", etc).
 
-=item ietf (optional; default "0")
+=item * ietf (optional; default "0")
 
 If assigned, will change any '_' in the language code to a '-', conforming
@@ -6965 +7078 @@
 =over 4
 
-=item exclude_port (optional; default "0")
+=item * exclude_port (optional; default "0")
 
 Removes any specified port number if this attribute is set to true (1),
@@ -6971 +7084 @@
 www.somedomain.com:8080).
 
-=item signature (optional; default "0")
+=item * signature (optional; default "0")
 
 If set to 1, then this template tag will instead return a unique signature
@@ -7014 +7127 @@
 =over 4
 
-=item exclude_port (optional; default "0")
+=item * exclude_port (optional; default "0")
 
 If set, exclude the port number from the CGIHost.
@@ -7038 +7151 @@
 =head2 BlogCategoryCount
 
-=for tags multiblog, count, blogs
+Returns the number of categories associated with a blog. This
+template tag supports the multiblog template tags.
+
+This template tag also supports all of the same filtering mechanisms
+defined by the mt:Categories tag allowing users to retrieve a count
+of the number of comments on a blog that meet a certain criteria.
+
+B<Example:>
+
+    <$mt:BlogCategoryCount$>
+
+=for tags multiblog, count, blogs, categories
 
 =cut
@@ -7179 +7303 @@
 =over 4
 
-=item with_index (optional; default "0")
+=item * with_index (optional; default "0")
 
 If specified, forces the trailing "index" filename to be left on any
@@ -7309 +7433 @@
 =over 4
 
-=item lastn (optional)
+=item * lastn (optional)
 
 Allows you to limit the number of entries output. This attribute
@@ -7319 +7443 @@
 This would publish the 5 most recent entries, ordered by their titles.
 
-=item limit (optional)
+=item * limit (optional)
 
 Similar to the C<lastn> attribute, but limits output based on whichever
 sort order is in use.
 
-=item sort_by (optional; default "authored_on")
+=item * sort_by (optional; default "authored_on")
 
 Accepted values are: C<authored_on>, C<title>, C<ping_count>,
@@ -7335 +7459 @@
 field basename you wish to sort on).
 
-=item sort_order (optional)
+=item * sort_order (optional)
 
 Accepted values are 'ascend' and 'descend'. The default is the order
@@ -7341 +7465 @@
 screen.
 
-=item field:I<basename>
+=item * field:I<basename>
 
 Permits filtering entries based on a custom field defined (available
@@ -7354 +7478 @@
 (checkbox field) checked.
 
-=item namespace (optional)
+=item * namespace (optional)
 
 The namespace attribute is used to specify which scoring namespace
@@ -7364 +7488 @@
 of recommend/favorite votes that have been made.
 
-=item class_type (optional; default 'entry')
+=item * class_type (optional; default 'entry')
 
 Accepted values are 'entry' and 'page'.
 
-=item offset (optional)
+=item * offset (optional)
 
 Accepted values are any non-zero positive integers, or the keyword
@@ -7375 +7499 @@
 the request.
 
-=item category or categories (optional)
+=item * category or categories (optional)
 
 This attribute allows you to filter the entries based on category
@@ -7401 +7525 @@
     <mt:Entries categories="NOT Family">
 
-=item include_subcategories (optional)
+=item * include_subcategories (optional)
 
 If this attribute is specified in conjunction with the category (or
@@ -7407 +7531 @@
 of the identified category/categories to be included as well.
 
-=item tag or tags (optional)
+=item * tag or tags (optional)
 
 This attribute functions similarly to the C<category> attribute, but
@@ -7413 +7537 @@
 described for category selection.
 
-=item author (optional)
+=item * author (optional)
 
 Accepts an author's username to filter entry selection.
@@ -7421 +7545 @@
     <mt:Entries author="Melody">
 
-=item id (optional)
+=item * id (optional)
 
 If specified, selects a single entry matching the given entry ID.
@@ -7427 +7551 @@
     <mt:Entries id="10">
 
-=item min_score (optional)
-
-=item max_score (optional)
-
-=item min_rate (optional)
-
-=item max_rate (optional)
-
-=item min_count (optional)
-
-=item max_count (optional)
+=item * min_score (optional)
+
+=item * max_score (optional)
+
+=item * min_rate (optional)
+
+=item * max_rate (optional)
+
+=item * min_count (optional)
+
+=item * max_count (optional)
 
 Allows filtering of entries based on score, rating or count. Each of
 the attributes require the C<namespace> attribute.
 
-=item scored_by (optional)
+=item * scored_by (optional)
 
 Allows filtering of entries that were scored by a particular user,
 specified by username. Requires the C<namespace> attribute.
 
-=item days (optional)
+=item * days (optional)
 
 Limits the selection of entries to a specified number of days,
@@ -7457 +7581 @@
 published.
 
-=item recently_commented_on (optional)
+=item * recently_commented_on (optional)
 
 Selects the list of entries that have received published comments
@@ -7469 +7593 @@
 received comment.
 
-=item unique
+=item * unique
 
 If specified, this flag will cause MT to keep track of which entries
@@ -7491 +7615 @@
 from the first Entries tag.
 
-=item glue (optional)
+=item * glue (optional)
 
 Specifies a string that is output inbetween published entries.
@@ -7652 +7776 @@
                 } else {
                     my @cats = cat_path_to_category($category_arg, [ \%blog_terms, \%blog_args ], $class_type);
+use Data::Dumper; die Dumper({ terms => \%blog_terms, args => \%blog_args, cats => \@cats, arg => $category_arg });
                     if (@cats) {
                         $cats = \@cats;
@@ -8201 +8326 @@
 }
 
+###########################################################################
+
+=head2 DateHeader
+
+A container tag whose contents will be displayed if the entry in context
+was posted on a new day in the list.
+
+B<Example:>
+
+    <mt:Entries>
+        <mt:DateHeader>
+            <h2><$mt:EntryDate format="%A, %B %e, %Y"$></h2>
+        </mt:DateHeader>
+        <!-- display entry here -->
+    </mt:Entries>
+
+=for tags entries
+
+=cut
+
+###########################################################################
+
+=head2 DateFooter
+
+A container tag whose contents will be displayed if the entry in context
+is the last entry in the group of entries for a given day.
+
+B<Example:>
+
+    <mt:Entries>
+        <!-- display entry here -->
+        <mt:DateFooter>
+            <hr />
+        </mt:DateFooter>
+    </mt:Entries>
+
+=for tags entries
+
+=cut
+
+###########################################################################
+
+=head2 EntriesHeader
+
+The contents of this container tag will be displayed when the first
+entry listed by a L<Entries> tag is reached.
+
+=for tags entries
+
+=cut
+
+###########################################################################
+
+=head2 EntriesFooter
+
+The contents of this container tag will be displayed when the last
+entry listed by a L<Entries> tag is reached.
+
+=for tags entries
+
+=cut
+
+###########################################################################
+
+=head2 PagesHeader
+
+The contents of this container tag will be displayed when the first page
+listed by a L<Pages> tag is reached.
+
+B<Example:>
+
+    <mt:Pages glue=", ">
+        <mt:PagesHeader>
+            The following pages are available:
+        </mt:PagesHeader>
+        <a href="<$mt:PagePermalink$>"><$mt:PageTitle$></a>
+    </mt:Pages>
+
+=for tags pages
+
+=cut
+
+###########################################################################
+
+=head2 PagesFooter
+
+The contents of this container tag will be displayed when the last page
+listed by a L<Pages> tag is reached.
+
+=for tags pages
+
+=cut
+
 # returns an iterator that supplies entries, in the order of last comment
 # date (descending)
@@ -8326 +8544 @@
 =over 4
 
-=item convert_breaks (optional; default "1")
+=item * convert_breaks (optional; default "1")
 
 Accepted values are '0' and '1'. Typically, this attribute is
@@ -8332 +8550 @@
 text based on the text formatting option for the entry.
 
-=item words (optional)
+=item * words (optional)
 
 Accepts any positive integer to limit the number of words
@@ -8414 +8632 @@
 =over 4
 
-=item generate (optional)
+=item * generate (optional)
 
 If specified, will draw content from the "main" text field of
@@ -8518 +8736 @@
 =over 4
 
-=item flag (required)
+=item * flag (required)
 
 Accepts one of: 'allow_pings', 'allow_comments'.
@@ -8560 +8778 @@
 =over 4
 
-=item no_generate (optional)
+=item * no_generate (optional)
 
 If the excerpt field is empty, this flag will prevent the generation
 of an excerpt using the main text of the entry.
 
-=item words (optional; default "40")
+=item * words (optional; default "40")
 
 Controls the length of the auto-generated entry excerpt. Does B<not>
 limit the content when the excerpt field contains content.
 
-=item convert_breaks (optional; default "0")
+=item * convert_breaks (optional; default "0")
 
 When set to '1', applies the text formatting filters on the excerpt
@@ -8622 +8840 @@
 usernames.>
 
+=for tags deprecated
+
 =cut
 
@@ -8659 +8879 @@
 favor of L<EntryAuthorDisplayName>.>
 
+=for tags deprecated
+
 =cut
 
@@ -8697 +8919 @@
 =over 4
 
-=item spam_protect (optional; default "0")
+=item * spam_protect (optional; default "0")
 
 If specified, this will apply a light obfuscation of the email address,
@@ -8744 +8966 @@
 =over 4
 
-=item new_window
+=item * new_window
 
 If specified, the published link is given a C<target> attribute of '_blank'.
 
-=item show_email (optional; default "0")
+=item * show_email (optional; default "0")
 
 If set, will allow publishing of an email address if the URL field
 for the author is empty.
 
-=item spam_protect (optional)
+=item * spam_protect (optional)
 
 If specified, this will apply a light obfuscation of any email address
@@ -8759 +8981 @@
 address (C<:>, C<@>, and C<.>) into HTML entities.
 
-=item type (optional)
+=item * type (optional)
 
 Accepted values: C<url>, C<email>, C<archive>. Note: an 'archive' type
 requires publishing of "Author" archives.
 
-=item show_hcard (optional; default "0")
+=item * show_hcard (optional; default "0")
 
 If present, adds additional CSS class names to the link tag published,
@@ -8935 +9157 @@
 ###########################################################################
 
-=head2 EntryTrackbackLink
+=head2 EntryTrackbackData
 
 Outputs the TrackBack RDF block that allows for TrackBack
@@ -8945 +9167 @@
 =over 4
 
-=item comment_wrap (optional; default "1")
+=item * comment_wrap (optional; default "1")
 
 If enabled, will enclose the RDF markup inside an HTML
 comment tag.
 
-=item with_index (optional; default "0")
+=item * with_index (optional; default "0")
 
 If specified, will leave any "index.html" (or appropriate index
@@ -9041 +9263 @@
 =over 4
 
-=item type (optional)
-
-=item archive_type (optional)
+=item * type (optional)
+
+=item * archive_type (optional)
 
 Identifies the archive type to use when creating the link. For instance,
@@ -9094 +9316 @@
 =over 4
 
-=item separator (optional)
+=item * separator (optional)
 
 Accepts either "-" or "_". If unspecified, the raw basename value is
@@ -9150 +9372 @@
 =over 4
 
-=item type or archive_type (optional)
+=item * type or archive_type (optional)
 
 Specifies an alternative archive type to use instead of the individual
 archive.
 
-=item valid_html (optional; default "0")
+=item * valid_html (optional; default "0")
 
 When publishing entry permalinks for non-individual archive templates, an
@@ -9164 +9386 @@
 valid HTML.
 
-=item with_index (optional; default "0")
+=item * with_index (optional; default "0")
 
 If assigned, will retain any index filename at the end of the permalink.
@@ -9270 +9492 @@
 =over 4
 
-=item glue (optional)
+=item * glue (optional)
 
 If specified, this string is placed in between each result from the loop.
@@ -9381 +9603 @@
 Outputs a link to the MT Comment script to allow signing in to a TypeKey
 configured blog. B<NOTE: This is deprecated in favor of L<SignInLink>.>
+
+=for tags deprecated
 
 =cut
@@ -9417 +9641 @@
 a blog. B<NOTE: This tag is deprecated in favor of L<SignOutLink>.>
 
+=for tags deprecated
+
 =cut
 
@@ -9442 +9668 @@
 }
 
+###########################################################################
+
+=head2 CommentFields
+
+A deprecated tag that formerly published an entry comment form.
+
+=for tags deprecated
+
+=cut
+
 sub _hdlr_comment_fields {
     my ($ctx, $args, $cond) = @_;
@@ -9565 +9801 @@
 =over 4
 
-=item ts (optional)
+=item * ts (optional)
 
 If specified, will use the given date as the date to publish. Must be
 in the format of "YYYYMMDDhhmmss".
 
-=item relative (optional)
+=item * relative (optional)
 
 If specified, will publish the date using a phrase, if the date is
@@ -9578 +9814 @@
 =over 4
 
-=item relative="1"
+=item * relative="1"
 
 Supports display of one duration: moments ago; N minutes ago; N hours ago; N days ago. For older dates in the same year, the date is shown as the abbreviated month and day of the month ("Jan 3"). For older dates, the year is added to that ("Jan 3 2005").
 
-=item relative="2"
+=item * relative="2"
 
 Supports display of two durations: less than 1 minute ago; N seconds, N minutes ago; N minutes ago; N hours, N minutes ago; N hours ago; N days, N hours ago; N days ago.
 
-=item relative="3"
+=item * relative="3"
 
 Supports display of two durations: N seconds ago; N seconds, N minutes ago;
 N minutes ago; N hours, N minutes ago; N hours ago; N days, N hours ago; N days ago.
 
-=item relative="js"
+=item * relative="js"
 
 When specified, publishes the date using JavaScript, which relies on a
@@ -9598 +9834 @@
 =back
 
-=item format (optional)
+=item * format (optional)
 
 A string that provides the format in which to publish the date. If
@@ -9607 +9843 @@
 =over 4
 
-=item %Y
+=item * %Y
 
 The 4-digit year. Example: "1999".
 
-=item %m
+=item * %m
 
 The 2-digit month (zero-padded). Example: for a date in September, this would output "09".
 
-=item %d
+=item * %d
 
 The 2-digit day of the month (zero-padded). Example: "05".
 
-=item %H
+=item * %H
 
 The 2-digit hour of the day (24-hour clock, zero-padded). Example: "18".
 
-=item %M
+=item * %M
 
 The 2-digit minute of the hour (zero-padded). Example: "09".
 
-=item %S
+=item * %S
 
 The 2-digit second of the minute (zero-padded). Example: "04".
 
-=item %w
+=item * %w
 
 The numeric day of the week, in the range C<0>-C<6>, where C<0> is
 C<Sunday>. Example: "3".
 
-=item %j
+=item * %j
 
 The numeric day of the year, in the range C<0>-C<365>. Zero-padded to
 three digits. Example: "040".
 
-=item %y
+=item * %y
 
 The two-digit year, zero-padded. Example: %y for a date in 2008 would
 output "08".
 
-=item %b
+=item * %b
 
 The abbreviated month name. Example: %b for a date in January would
 output "Jan".
 
-=item %B
+=item * %B
 
 The full month name. Example: "January".
 
-=item %a
+=item * %a
 
 The abbreviated day of the week. Example: %a for a date on a Monday would
 output "Mon".
 
-=item %A
+=item * %A
 
 The full day of the week. Example: "Friday".
 
-=item %e
-
-The numeric day of the month (space-padded). Example: "08".
-
-=item %I
+=item * %e
+
+The numeric day of the month (space-padded). Example: " 8".
+
+=item * %I
 
 The two-digit hour on a 12-hour clock padded with a zero if applicable.
 Example: "04".
 
-=item %k
+=item * %k
 
 The two-digit military time hour padded with a space if applicable.
 Example: " 9".
 
-=item %l
+=item * %l
 
 The hour on a 12-hour clock padded with a space if applicable.
@@ -9685 +9921 @@
 =back
 
-=item format_name (optional)
+=item * format_name (optional)
 
 Supports date formatting for particular standards.
@@ -9691 +9927 @@
 =over 4
 
-=item rfc822
+=item * rfc822
 
 Outputs the date in the format: "%a, %d %b %Y %H:%M:%S Z".
 
-=item iso8601
+=item * iso8601
 
 Outputs the date in the format: "%Y-%m-%dT%H:%M:%SZ".
@@ -9701 +9937 @@
 =back
 
-=item utc (optional)
+=item * utc (optional)
 
 Converts the date into UTC time.
 
-=item offset_blog_id (optional)
+=item * offset_blog_id (optional)
 
 Identifies the ID of the blog to use for adjusting the time to
 blog time. Will default to the current blog in context if unset.
 
-=item language (optional)
+=item * language (optional)
 
 Used to force localization of the date to a specific language.
@@ -9851 +10087 @@
 ###########################################################################
 
-=head2 Comments TBD
+=head2 Comments
 
 A container tag which iterates over a list of comments on an entry or for a
-blog. By default, all comments in context (e.g on an entry or in a blog) are
+blog. By default, all comments in context (e.g. on an entry or in a blog) are
 returned. When used in a blog context, only comments on published entries are
 returned.
@@ -9862 +10098 @@
 =over 4
 
-=item lastn
+=item * lastn
 
 Display the last N comments in context where N is a positive integer.
 B<NOTE: lastn required in a blog context.>
 
-=item offset
-
-=item sort_by
-
-=item sort_order
+=item * offset (optional; default "0")
+
+Specifies a number of comments to skip.
+
+=item * sort_by (optional)
+
+Specifies a sort column.
+
+=item * sort_order (optional)
 
 Specifies the sort order and overrides the General Settings. Recognized
 values are "ascend" and "descend."
 
-=item namespace
-
-=item min_score
-
-=item max_score
-
-=item min_rate
-
-=item max_rate
-
-=item min_count
-
-=item max_count
-
-=item scored_by
+=item * namespace
+
+Used in conjunction with the "min*", "max*" attributes to
+select comments based on a particular scoring mechanism.
+
+=item * min_score
+
+If 'namespace' is also specified, filters the comments based on
+the score within that namespace. This specifies the minimum score
+to consider the comment for inclusion.
+
+=item * max_score
+
+If 'namespace' is also specified, filters the comments based on
+the score within that namespace. This specifies the maximum score
+to consider the comment for inclusion.
+
+=item * min_rank
+
+If 'namespace' is also specified, filters the comments based on
+the rank within that namespace. This specifies the minimum rank
+to consider the comment for inclusion.
+
+=item * max_rate
+
+If 'namespace' is also specified, filters the comments based on
+the rank within that namespace. This specifies the maximum rank
+to consider the comment for inclusion.
+
+=item * min_count
+
+If 'namespace' is also specified, filters the comments based on
+the count within that namespace. This specifies the minimum count
+to consider the comment for inclusion.
+
+=item * max_count
+
+If 'namespace' is also specified, filters the comments based on
+the count within that namespace. This specifies the maximum count
+to consider the comment for inclusion.
 
 =back
@@ -10269 +10534 @@
 ###########################################################################
 
+=head2 CommentName
+
+Deprecated in favor of the L<CommentAuthor> tag.
+
+=for tags deprecated
+
+=cut
+
+###########################################################################
+
 =head2 CommentAuthor
 
@@ -10321 +10596 @@
 =over 4
 
-=item show_email (optional; default "0")
+=item * show_email (optional; default "0")
 
 Specifies if the comment author's email can be displayed.
 
-=item show_url (optional; default "1")
+=item * show_url (optional; default "1")
 
 Specifies if the comment author's URL can be displayed.
 
-=item new_window (optional; default "0")
+=item * new_window (optional; default "0")
 
 Specifies to open the link in a new window by adding C<target="_blank">
 to the anchor tag. See example below.
 
-=item default_name (optional; default "Anonymous")
+=item * default_name (optional; default "Anonymous")
 
 Used in the event that the commenter did not provide a value for their
 name.
 
-=item no_redirect (optional; default "0")
+=item * no_redirect (optional; default "0")
 
 Prevents use of the mt-comments.cgi script to handle the comment author
 link.
 
-=item nofollowfy (optional)
+=item * nofollowfy (optional)
 
 If assigned, applies a C<rel="nofollow"> link relation to the link.
@@ -10416 +10691 @@
 =over 4
 
-=item spam_protect (optional; default "0")
+=item * spam_protect (optional; default "0")
 
 =back
@@ -10528 +10803 @@
 ###########################################################################
 
+=head2 CommentPreviewEmail
+
+A deprecated tag, replaced with L<CommentEmail>.
+
+=for tags deprecated
+
+=cut
+
+###########################################################################
+
+=head2 CommentPreviewBody
+
+A deprecated tag, replaced with L<CommentBody>.
+
+=for tags deprecated
+
+=cut
+
+###########################################################################
+
+=head2 CommentPreviewAuthorLink
+
+A deprecated tag, replaced with L<CommentAuthorLink>.
+
+=for tags deprecated
+
+=cut
+
+###########################################################################
+
+=head2 CommentPreviewURL
+
+A deprecated tag, replaced with L<CommentURL>.
+
+=for tags deprecated
+
+=cut
+
+###########################################################################
+
+=head2 CommentPreviewDate
+
+A deprecated tag, replaced with L<CommentDate>.
+
+=for tags deprecated
+
+=cut
+
+###########################################################################
+
+=head2 CommentPreviewAuthor
+
+A deprecated tag, replaced with L<CommentAuthor>.
+
+=for tags deprecated
+
+=cut
+
+###########################################################################
+
+=head2 CommentPreviewIP
+
+A deprecated tag, replaced with L<CommentIP>.
+
+=for tags deprecated
+
+=cut
+
+###########################################################################
+
 =head2 CommentBody
 
@@ -10534 +10879 @@
 =over 4
 
-=item autolink (optional)
+=item * autolink (optional)
 
 If unspecified, any plaintext links in the comment body will be
@@ -10541 +10886 @@
 override the blog preference.
 
-=item convert_breaks (optional)
+=item * convert_breaks (optional)
 
 By default, the comment text is formatted according to the comment text
@@ -10548 +10893 @@
 applied.
 
-=item words (optional)
+=item * words (optional)
 
 Limits the length of the comment body to the specified number of words.
@@ -10704 +11049 @@
 =over 4
 
-=item label or text (optional)
+=item * label or text (optional)
 
 A custom phrase for the link (default is "Reply").
 
-=item onclick (optional)
+=item * onclick (optional)
 
 Custom JavaScript code for the onclick attribute. By default, this
@@ -10744 +11089 @@
 =over 4
 
-=item pad
+=item * pad
 
 If specified, zero-pads the ID to 6 digits. Example: 001234.
@@ -10764 +11109 @@
 
 =head2 CommentReplies
+
+A block tag which iterates over a list of reply comments to the 
+in context.
+
+B<Example:>
+
+    <mt:Comment>
+      <mt:CommentReplies>
+        <mt:CommentsHeader>Replies to the comment:</mt:CommentsHeader>
+        <$mt:CommentBody$>
+      </mt:CommentReplies>
+    </mt:Comment>
 
 =for tags comments, loop
@@ -10842 +11199 @@
 =head2 CommentRepliesRecurse
 
+Recursively call the block with the replies to the comment in context. This
+tag, when placed at the end of loop controlled by MTCommentReplies tag will
+cause them to recursively descend into any replies to comments that exist
+during the loop.
+
+B<Example:>
+
+    <mt:Comments>
+      <$mt:CommentBody$>
+      <mt:CommentReplies>
+        <mt:CommentsHeader><ul></MTCommentsHeader>
+        <li><$mt:CommentID$>
+        <$mt:CommentRepliesRecurse$>
+        </li>
+        <mt:CommentsFooter></ul></mt:CommentsFooter>
+      </mt:CommentReplies>
+    </mt:Comments>
+
 =for tags comments
 
@@ -10915 +11290 @@
 ###########################################################################
 
+=head2 CommentsHeader
+
+The contents of this container tag will be displayed when the first
+comment listed by a L<Comments> or L<CommentReplies> tag is reached.
+
+=for tags comments
+
+=cut
+
+###########################################################################
+
+=head2 CommentsFooter
+
+The contents of this container tag will be displayed when the last
+comment listed by a L<Comments> or L<CommentReplies> tag is reached.
+
+=for tags comments
+
+=cut
+
+###########################################################################
+
 =head2 IfCommentParent
 
@@ -10967 +11364 @@
 =head2 CommenterNameThunk
 
-=for tags comments
+Used to populate the commenter_name Javascript variable. Deprecated in
+favor of the L<UserSessionState> tag.
+
+=for tags deprecated
 
 =cut
@@ -10992 +11392 @@
 =head2 CommenterUsername
 
+This template tag returns the username of the current commenter in context.
+If no name exists, then it returns an empty string.
+
+B<Example:>
+
+    <mt:Entries>
+        <h1><$mt:EntryTitle$></h1>
+        <mt:Comments>
+            <a name="comment-<$mt:CommentID$>"></a>
+            <p><$mt:CommentBody$></p>
+            <cite><a href="/profiles/<$mt:CommenterID$>"><$mt:CommenterUsername$></a></cite>
+        </mt:Comments>
+    </mt:Entries>
+
 =for tags comments
 
@@ -11004 +11418 @@
 ###########################################################################
 
-=head2 UserSessionCookieTimeout
+=head2 UserSessionState
 
 Returns a JSON-formatted data structure that represents the user that is
 currently logged in.
 
-=for tags comments
+=for tags comments, authentication
 
 =cut
@@ -11028 +11442 @@
 =head2 UserSessionCookieTimeout
 
-=for tags comments
+Returns the value of the C<UserSessionCookieTimeout> configuration setting.
+
+=for tags comments, configuration, authentication
 
 =cut
@@ -11041 +11457 @@
 =head2 UserSessionCookiePath
 
-=for tags comments
+Returns the value of the C<UserSessionCookiePath> configuration setting.
+
+The C<UserSessionCookiePath> may also use MT tags. If it does, they will
+be evaluated for the blog in context.
+
+=for tags comments, configuration, authentication
 
 =cut
@@ -11068 +11489 @@
 =head2 UserSessionCookieDomain
 
-=for tags comments
+Returns the value of the C<UserSessionCookieDomain> configuration setting,
+or the domain name of the blog currently in context. Any "www" subdomain
+will be ignored (ie, "www.sixapart.com" becomes ".sixapart.com").
+
+The C<UserSessionCookieDomain> may also use MT tags. If it does, they will
+be evaluated for the blog in context.
+
+=for tags comments, configuration, authentication
 
 =cut
@@ -11096 +11524 @@
 ###########################################################################
 
-=head2 UserSessionCookie
-
-=for tags comments
+=head2 UserSessionCookieName
+
+Returns the value of the C<UserSessionCookieName> configuration setting.
+If the setting contains the C<%b> string, it will replaced with the blog ID
+of the blog currently in context.
+
+B<Example:>
+
+    <$mt:UserSessionCookieName$>
+
+=for tags comments, configuration
 
 =cut
@@ -11119 +11555 @@
 =head2 CommenterName
 
+The name of the commenter for the comment currently in context.
+
+B<Example:>
+
+    <$mt:CommenterName$>
+
 =for tags comments
 
@@ -11135 +11577 @@
 =head2 CommenterEmail
 
+The email address of the commenter. The spam_protect global filter may
+be used.
+
+B<Example:>
+
+    <$mt:CommenterEmail$>
+
 =for tags comments
 
@@ -11150 +11599 @@
 =head2 CommenterAuthType
 
-=for tags comments
+Returns a string which identifies what authentication provider the commenter
+in context used to authenticate him/herself. Commenter context is created by
+either MTComments or MTCommentReplies template tag. For example, 'MT' will be
+returned when the commenter in context is authenticated by Movable Type. When
+the commenter in context is authenticated by Vox, 'Vox' will be returned.
+
+B<Example:>
+
+    <mt:Comments>
+      <$mt:CommenterName$> (<$mt:CommenterAuthType$>) said:
+      <$mt:CommentBody$>
+    </mt:Comments>
+
+=for tags comments, authentication
 
 =cut
@@ -11164 +11626 @@
 =head2 CommenterAuthIconURL
 
-=for tags comments
+Returns URL to a small (16x16) image represents in what authentication
+provider the commenter in context is authenticated. Commenter context
+is created by either a L<Comments> or L<CommentReplies> block tag. For
+commenters authenticated by Movable Type, it will be a small spanner
+logo of Movable Type. Otherwise, icon image is provided by each of
+authentication provider. Movable Type provides images for Vox,
+LiveJournal and OpenID out of the box.
+
+B<Example:>
+
+    <mt:Comments>
+        <$mt:CommenterName$><$mt:CommenterAuthIconURL$>:
+        <$mt:CommentBody$>
+    </mt:Comments>
+
+=for tags comments, authentication
 
 =cut
@@ -11187 +11664 @@
 ###########################################################################
 
+=head2 CommenterIfTrusted
+
+Deprecated in favor of the L<IfCommenterTrusted> tag.
+
+=for tags deprecated
+
+=cut
+
+###########################################################################
+
 =head2 IfCommenterTrusted
 
-=for tags comments
+A conditional tag that displays its contents if the commenter in context
+has been marked as trusted.
+
+=for tags comments, authentication
 
 =cut
@@ -11285 +11775 @@
 =head2 CommenterUserpic
 
+This template tag returns a complete HTML C<img> tag for the current
+commenter's userpic. For example:
+
+    <img src="http://yourblog.com/userpics/1.jpg" width="100" height="100" />
+
+B<Example:>
+
+    <h2>Recent Commenters</h2>
+    <mt:Entries recently_commented_on="10">
+        <div class="userpic" style="float: left; padding: 5px;"><$mt:CommenterUserpic$></div>
+    </mt:Entries>
+
 =for tags comments
 
@@ -11301 +11803 @@
 =head2 CommenterUserpicURL
 
+This template tag returns the URL to the image of the current
+commenter's userpic.
+
+B<Example:>
+
+    <img src="<$mt:CommenterUserpicURL$>" />
+
 =for tags comments
 
@@ -11315 +11824 @@
 =head2 CommenterUserpicAsset
 
-=for tags comments
+This template tag is a container tag that puts the current commenter's
+userpic asset in context. Because userpics are stored as assets within
+Movable Type, this allows you to utilize all of the asset-related
+template tags when displaying a user's userpic.
+
+B<Example:>
+
+     <mt:CommenterUserpicAsset>
+        <img src="<$mt:AssetThumbnailURL width="20" height="20"$>"
+            width="20" height="20"  />
+     </mt:CommenterUserpicAsset>
+
+=for tags comments, assets
 
 =cut
@@ -11357 +11878 @@
 =head2 ArchivePrevious
 
-
-=cut
+A container tag that creates a context to the "previous" archive
+relative to the current archive context.
+
+This tag also works with the else tag to produce content if there is no
+"previous" archive.
+
+B<Attributes:>
+
+=over 4
+
+=item * type or archive_type (optional)
+
+Specifies the "previous" archive type the context is for. See
+the L<ArchiveList> tag for supported values for this attribute.
+
+=back
+
+B<Example:>
+
+    <mt:ArchivePrevious>
+      <a href="<$mt:ArchiveLink$>"
+        title="<$mt:ArchiveTitle escape="html"$>">Next</a>
+    <mt:Else>
+       <!-- output when no previous archive is available -->
+    </mt:ArchivePrevious>
+
+=for tags archiving
+
+=cut
+
+###########################################################################
 
 =head2 ArchiveNext
@@ -11366 +11916 @@
 
 This tag also works with the else tag to produce content if there is no
-"previous" archive.
+"next" archive.
 
 B<Attributes:>
@@ -11372 +11922 @@
 =over 4
 
-=item type or archive_type (optional)
+=item * type or archive_type (optional)
 
 Specifies the "next" archive type the context is for. See the L<ArchiveList>
@@ -11384 +11934 @@
       <a href="<$mt:ArchiveLink$>"
         title="<$mt:ArchiveTitle escape="html"$>">Next</a>
-    <mt:else>
-       <!-- output when no previous archive is available -->
+