| The <sitemap> Tag
                          The <sitemap> tag is used to generate a content item containing a map,
                          in a tree structure, of the current site.
                          
                         
                          It does this by traversing every content item you have defined, looking for
                          one tagged with a isroot=true attribute. This will become the root of the
                          site map tree.
                          
                         
                          While traversing, it also searches for content items with a metadatum called up. This is used to tie all the content together into a
                          tree structure.
                          
                         
                          
                            Note: content items that do not have an upmetadatum are considered
                             children of the root by default. If you do not want to map a piece of
                             content, declare it with the attribute map=false.
                            
                           
                          By default, the content items are arranged by their score and title metadata
                          at each level. The sort criteria can be overridden by setting the
                          sortorder attribute.
                          
                         
                          
                            Note: if you wish to include external HTML pages into the sitemap, you
                             will need to load them as URL references using the <media> tag and use
                             the <metatable> tag to associate metadata with them.
                             t/data/sitemap_with_metatable.wmk in the WebMake test suite demonstrates
                             this. This needs more documentation (TODO).
                            
                           
                          The <sitemap> tag takes the following required attributes:
                          
                         
                          
                            name
                          
                            
                              The name of the sitemap item, used to refer to it
                               later. Sitemaps are referred to, in other content items or in out
                               files, using the normal ${foo} style of content reference.
                              
                            
                            node
                          
                            
                              The name of the template item to evaluate for each
                               node with children in the tree. See Processing, below.
                              
                            
                            leaf
                          
                            
                              The name of the template item to evaluate for each leaf
                               node, ie. a node with no children, in the tree. See Processing,
                               below.
                              
                             
                          And the following optional attributes:
                          
                         
                          
                            rootname
                          
                            
                              The root content item to start traversing at. The
                               default root is whichever content item has the isroot attribute
                               set to true.
                              
                            
                            all
                          
                            
                              Whether or not all content items should be mapped.
                               Normally dynamic content, such as metadata and perl-code-defined
                               content items, are not included. (default: false)
                              
                            
                            dynamic
                          
                            
                              The name of the template item to evaluate for
                               dynamic content items, required if the all attribute is set
                               to true.
                              
                            
                            grep
                          
                            
                              Perl code to evaluate at each step of the tree.
                               See the Grep section below.
                              
                            
                            sortorder
                          
                            
                              A sort string specifying what metadata
                               should be used to sort the items in the tree, for example "section
                               score title".
                              
                             
                          Note that the root attribute is deprecated; use rootname instead.
                          
                         
                          The sitemap can be declared either as an empty element, with /> at the
                          end, or with a pair of starting and ending tags and text between. If the
                          sitemap is declared using the latter style, any text between the tags will be
                          prepended to the generated site map. It's typically only useful if you wish
                          to set metadata on the map itself.
                          
                         Processing
                          Here's the key to sitemap generation. Once the internal tree structure of the
                          site has been determined, WebMake will run through each node from the root
                          down up to 20 levels deep, and for each node, evaluate one of the 3 content
                          items named in the <sitemap> tag's attributes:
                          
                         
                          
                            
                              node: For pages with pages beneath them;
                              
                            
                            
                              leaf: For "leaf" pages with no pages beneath them;
                              
                            
                            
                              dynamic: For dynamic content items, defined by perl code
                               or metadata.
                              
                             
                          By changing the template content items you name in the tag's attributes, you
                          have total control over the way the sitemap is rendered. For efficiency,
                          these should be declared using the <template> tag instead of the
                          <content> tag.
                          
                         
                          The following variables (ie. content items) are set for each node:
                          
                         
                          
                            name
                          
                            
                              the content name
                              
                            
                            title
                          
                            
                              the content's Titlemetadatum, if set
                              
                            
                            score
                          
                            
                              the content's Scoremetadatum, if set
                              
                            
                            list
                          
                            
                              the text for all children of this node (node
                               items only)
                              
                            
                            is_node
                          
                            
                              whether the content is a node or a leaf (1 for
                               node, 0 for leaf)
                              
                             
                          In addition, the following URL reference is set:
                          
                         
                          
                            url
                          
                            
                              the first URL listed in a WebMake <out> tag
                               to refer to the content item.
                              
                             
                          Confused? Don't worry, there's an example below.
                          
                         Grep
                          The grep attribute is used to filter which content items are included in
                          the site map.
                          
                         
                          The "grep" code is evaluated once for every node in the sitemap, and $_is the name of that node; you can then decide to display/not display it, as
                          follows. 
                          $_is set to the current content item's name. If the perl code returns 0,
                          the node is skipped; if the perl code sets the variable$PRUNEto 1, all
                          nodes at this level and below are skipped. Example
                          If you're still not sure how it works, take a look at examples/sitemap.wmk
                          in the distribution. Here's the important bits from that file.
                          
                         
                          Firstly, two content items are necessary -- a template for a sitemap node, and
                          a template for a leaf. Note the use of $(url),
                          ${title}, etc., which are filled in by the sitemap code.
                          
                         
                           
	<content name=sitemapnode map=false>
	  <li>
	    <a href=$(url)>${title}</a>: $[${name}.abstract]<br>
	    <!-- don't forget to list the sub-items -->
	    <ul> ${list} </ul>
	  </li>
	</content>
                        
                        And the template for the leaf nodes. Note that the ${list}
                        reference is not needed here.
                        
                       
                         
	<content name=sitemapleaf map=false>
	  <li>
	    <a href=$(url)>${title}</a>: $[${name}.abstract]<br>
	  </li>
	  </li>
	</content>
                      
                      Finally, the sitemap itself is declared.
                      
                     
                       
	<sitemap name=mainsitemap node=sitemapnode leaf=sitemapleaf />
                    
                    From then on, it's just a matter of including the sitemap content item in
                    an output file:
                    
                   
                     
	<out name=map file=sitemap_html/map.html>
	  ${header}${mainsitemap}${footer}
	</out>
                  
                  And that's it.
                  
                 
                  This documentation includes a sitemap, by the way. It's used to generate
                  the navigation links. Take a look here.
                  
                 
                  
                 |