<wmmeta name="Title" value="The &lt;out&gt; Tag" />
<wmmeta name="Section" value="02-tags_attrs" />
<wmmeta name="Score" value="80" />
<wmmeta name="Abstract">
an output file and URL
</wmmeta>

The &lt;out&gt; tag is used to generate output. Surprise!

It has one required attribute -- __file__, which defines the output file
generated by this section.  In addition it has some optional attributes, as
follows:

  __name__:	which is used to substitute in that section's URL address, by
  inserting it in other sections or out tags in a "URL reference" [ref], like
  so: &wmdollar;(out_foo) .

	[ref]: $(url_refs)

More optional attributes are as follows.  These ones also pick up defaults
from the "&lt;attrdefault&gt;" [attrdefault] tag.

  __format__:	which defines the format the output is expected in
  (MIME-style).  The default is **text/html**.

  __clean__:	specifies which features of the "HTML cleaner"
  to use.  The "HTML cleaner" is a powerful filter which can polish grotty,
  messy HTML into fully-standards-compliant glory.  The default value
  is **all**.

  __ismainurl__:	Whether this output file should be used as a ''main
  URL'' for any content items used within it, to support "the __url__ magic
  metadatum" [wmmeta].  If you plan to have multiple output styles for
  your content, be sure to set ''ismainurl=false'' on the pages which use
  ''alternative'' styles.  The default value is **true**.

  	[HTML cleaner]: $(cleaner)
	[wmmeta]: $(wmmeta)
	[attrdefault]: $(attrdefault)

Perl code can also access out URLs using the <a
href=$(PerlCodeLibrary.pm.html)>##get_url()##</a> function.

The production of multiple out files that are more-or-less identical can be
automated using the <a href=$(for)>&lt;for&gt;</a> tag.

Output and Dependencies
~~~~~~~~~~~~~~~~~~~~~~~

Out files will not be generated if the resulting text has not changed from the
previous run, or if the content sections it depends on have not changed.

The latter functionality is accomplished by caching the modification dates of
each file from which content was read to generate the output file.  If:

	1. the output file exists,

	2. none of the files are newer than they were last time the output
	file was written,

	3. none of them are newer than the output file itself, and

	4. none of the content items contain dynamic content, such as Perl
	code or sitemaps, 

then it does not need to be rebuilt.

	__Note:__ the ##-r## switch to webmake, or the ##risky_fast_rebuild##
	option to the ##HTML::WebMake::Main## constructor, indicates that
	WebMake can take some risks when rebuilding.  If this is on, then
	step 4. from the list above is ignored.

Example
=======

<safe>
  <out name="index" file="index.html">
    ${header}
    ${index_text}
    ${footer}
  </out>
</safe>