+<div>
+ <ul>
+ <li><a href="#TWiki Meta Data"> TWiki Meta Data</a><ul>
+ <li><a href="#Overview"> Overview</a></li>
+ <li><a href="#Meta Data Syntax"> Meta Data Syntax</a></li>
+ <li><a href="#Meta Data Specifications"> Meta Data Specifications</a><ul>
+ <li><a href="#META:TOPICINFO"> META:TOPICINFO</a></li>
+ <li><a href="#META:TOPICMOVED"> META:TOPICMOVED</a></li>
+ <li><a href="#META:TOPICPARENT"> META:TOPICPARENT</a></li>
+ <li><a href="#META:FILEATTACHMENT"> META:FILEATTACHMENT</a></li>
+ <li><a href="#META:FORM"> META:FORM</a></li>
+ <li><a href="#META:FIELD"> META:FIELD</a></li>
+ <li><a href="#Recommended Sequence"> Recommended Sequence</a></li>
+ </ul>
+ </li>
+ <li><a href="#Viewing Meta Data in Page Source"> Viewing Meta Data in Page Source</a></li>
+ <li><a href="#Rendering Meta Data"> Rendering Meta Data</a></li>
+ <li><a href="#Known Issues"> Known Issues</a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+<a name="MetaDataDefinition"></a>
+
+# <a name="TWiki Meta Data"></a> TWiki Meta Data
+
+_Additional topic data, not editable from main freeform text box, stored in `META` variable name/value pairs_
+
+## <a name="Overview"></a> Overview
+
+TWikiMetaData uses `META` variables to store topic data that's separate from the main free-form content. This includes program-generated info like [[FileAttachment]] data, and user-defined [[TWikiForms]] info.
+
+## <a name="Meta Data Syntax"></a> Meta Data Syntax
+
+- Format is the same as in [[TWikiVariables]], except all fields have a key.
+ - `%META:<type>{key1="value1" key2="value2" ...}%`
+
+- Order of fields within the meta variables is not defined, except that if there is a field with key `name`, this appears first for easier searching (note the order of the variables themselves is defined).
+
+- Each meta variable is on one line.
+
+- `\n` (new line) is represented in values by `%_N_` and `"` (double-quotes) by `%_Q_%`.
+
+> **Example of Format**
+>
+> %META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
+> text of the topic
+> %META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
+> by="JohnTalintyre" date="976762680"}%
+> %META:TOPICPARENT{name="NavigationByTopicContext"}%
+> %META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
+> %META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
+> %META:FORM{name="WebFormTemplate"}%
+> %META:FIELD{name="OperatingSystem" value="OsWin"}%
+> %META:FIELD{name="TopicClassification" value="PublicFAQ"}%
+
+## <a name="Meta Data Specifications"></a> Meta Data Specifications
+
+The current version of Meta Data is 1.0, with support for the following variables.
+
+### <a name="META:TOPICINFO"></a> META:TOPICINFO
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th align="center" bgcolor="#99CCCC"><strong> Key </strong></th>
+ <th align="center" bgcolor="#99CCCC"><strong> Comment </strong></th>
+ </tr>
+ <tr>
+ <td> version </td>
+ <td> Same as RCS version </td>
+ </tr>
+ <tr>
+ <td> date </td>
+ <td> integer, unx time, seconds since start 1970 </td>
+ </tr>
+ <tr>
+ <td> author </td>
+ <td> last to change topic, is the REMOTE_USER </td>
+ </tr>
+ <tr>
+ <td> format </td>
+ <td> Format of this topic, will be used for automatic format conversion </td>
+ </tr>
+</table>
+
+### <a name="META:TOPICMOVED"></a> META:TOPICMOVED
+
+This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history.
+
+`%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%`
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th align="center" bgcolor="#99CCCC"><strong> Key </strong></th>
+ <th align="center" bgcolor="#99CCCC"><strong> Comment </strong></th>
+ </tr>
+ <tr>
+ <td> from </td>
+ <td> Full name i.e. web.topic </td>
+ </tr>
+ <tr>
+ <td> to </td>
+ <td> Full name i.e. web.topic </td>
+ </tr>
+ <tr>
+ <td> by </td>
+ <td> Who did it, is the REMOTE_USER, not WikiName </td>
+ </tr>
+ <tr>
+ <td> date </td>
+ <td> integer, unx time, seconds since start 1970 </td>
+ </tr>
+</table>
+
+Notes:
+
+- at present version number is not supported directly, it can be inferred from the RCS history.
+- there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.
+
+### <a name="META:TOPICPARENT"></a> META:TOPICPARENT
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Key </strong></th>
+ <th bgcolor="#99CCCC"><strong> Comment </strong></th>
+ </tr>
+ <tr>
+ <td> name </td>
+ <td> The topic from which this was created, [[Main/WebHome]] if done from <code>Go</code>, othewise topic where <code>?</code> or form used. Normally just topic, but is full web.topic format if parent is in a different Web. Renaming a Web will then only break a few of these references or they can be scanned and fixed. </td>
+ </tr>
+</table>
+
+### <a name="META:FILEATTACHMENT"></a> META:FILEATTACHMENT
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Key </strong></th>
+ <th bgcolor="#99CCCC"><strong> Comment </strong></th>
+ </tr>
+ <tr>
+ <td> name </td>
+ <td> Name of file, no path. Must be unique within topic </td>
+ </tr>
+ <tr>
+ <td> version </td>
+ <td> Same as RCS revision </td>
+ </tr>
+ <tr>
+ <td> path </td>
+ <td> Full path file was loaded from </td>
+ </tr>
+ <tr>
+ <td> size </td>
+ <td> In bytes </td>
+ </tr>
+ <tr>
+ <td> date </td>
+ <td> integer, unx time, seconds since start 1970 </td>
+ </tr>
+ <tr>
+ <td> user </td>
+ <td> the REMOTE_USER, not WikiName </td>
+ </tr>
+ <tr>
+ <td> comment </td>
+ <td> As supplied when file uploaded </td>
+ </tr>
+ <tr>
+ <td> attr </td>
+ <td><code>h</code> if hidden, optional </td>
+ </tr>
+</table>
+
+Extra fields that are added if an attachment is moved:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Key </strong></th>
+ <th bgcolor="#99CCCC"><strong> Comment </strong></th>
+ </tr>
+ <tr>
+ <td> movedfrom </td>
+ <td> full topic name - web.topic </td>
+ </tr>
+ <tr>
+ <td> movedby </td>
+ <td> the REMOTE_USER, not WikiName </td>
+ </tr>
+ <tr>
+ <td> movedto </td>
+ <td> full topic name - web.topic </td>
+ </tr>
+ <tr>
+ <td> moveddate </td>
+ <td> integer, unx time, seconds since start 1970 </td>
+ </tr>
+</table>
+
+### <a name="META:FORM"></a> META:FORM
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Key </strong></th>
+ <th bgcolor="#99CCCC"><strong> Comment </strong></th>
+ </tr>
+ <tr>
+ <td> name </td>
+ <td> A topic name - the topic represents one of the [[Main/TWikiForms]]. Can optionally include the web name i.e. web.topic, but doesn't normally </td>
+ </tr>
+</table>
+
+### <a name="META:FIELD"></a> META:FIELD
+
+Should only be present if there is a META:FORM entry. Note that this data is used when viewing a topic, the form template definition is not read.
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Key </strong></th>
+ <th bgcolor="#99CCCC"><strong> Name </strong></th>
+ </tr>
+ <tr>
+ <td> name </td>
+ <td> Ties to entry in [[Main/TWikiForms]] template, is title with all bar alphanumerics and . removed </td>
+ </tr>
+ <tr>
+ <td> title </td>
+ <td> Full text from [[Main/TWikiForms]] template </td>
+ </tr>
+ <tr>
+ <td> value </td>
+ <td> Value user has supplied via form </td>
+ </tr>
+</table>
+
+### <a name="Recommended Sequence"></a> Recommended Sequence
+
+There is no absolute need for Meta Data variables to be listed in a specific order within a topic, but it makes sense to do so a couple of good reasons:
+
+- form fields remain in the order they are defined
+- the `diff` function output appears in a logical order
+
+The recommended sequence is:
+
+- META:TOPICINFO
+- `text of topic`
+- META:TOPICMOVED (optional)
+- META:TOPICPARENT (optional)
+- META:FILEATTACHMENT (0 or more entries)
+- META:FORM (optional)
+- META:FIELD (0 or more entries; FORM required)
+
+## <a name="Viewing Meta Data in Page Source"></a> Viewing Meta Data in Page Source
+
+When viewing a topic the <code>**Raw Text**</code> link can be clicked to show the text of a topic (ie: as seen when editing). This is done by adding `raw=on` to URL. `raw=debug` shows the meta data as well as the topic data, ex: [debug view for this topic](http://www.dementia.org/twiki//view/%WEB%/%TOPIC%?raw=debug)
+
+<a name="MetaDataRendering"></a>
+
+## <a name="Rendering Meta Data"></a> Rendering Meta Data
+
+Meta Data is rendered with the %META% variable. This is mostly used in the `view`, `preview` and `edit` scripts.
+
+Current support covers:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Variable usage: </strong></th>
+ <th bgcolor="#99CCCC"><strong> Comment: </strong></th>
+ </tr>
+ <tr>
+ <td> %META{"form"}% </td>
+ <td> Show form data, see [[Main/TWikiForms]]</td>
+ </tr>
+ <tr>
+ <td> %META{"attachments"}% </td>
+ <td> Show attachments, exclude hidden </td>
+ </tr>
+ <tr>
+ <td> Options for [[Main/FileAttachments]]: </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> all="on" </td>
+ <td> Show ALL attachments (including hidden) </td>
+ </tr>
+ <tr>
+ <td> %META{"moved"}% </td>
+ <td> Details of any topic moves </td>
+ </tr>
+ <tr>
+ <td> %META{"parent [options]"}% </td>
+ <td> Show topic parent </td>
+ </tr>
+ <tr>
+ <td> Options for parent: </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> dontrecurse="on" </td>
+ <td> By default recurses up tree, at some cost </td>
+ </tr>
+ <tr>
+ <td> prefix="..." </td>
+ <td> Prefix for parents, only if there are parents; default "" </td>
+ </tr>
+ <tr>
+ <td> suffix="..." </td>
+ <td> Suffix, only appears if there are parents; default "" </td>
+ </tr>
+ <tr>
+ <td> separator="..." </td>
+ <td> Separator between parents, default is " > " </td>
+ </tr>
+</table>
+
+## <a name="Known Issues"></a> Known Issues
+
+At present, there is no Meta Data support for Plugins. However, the format is readily extendable and the `Meta.pm` code that supports the format needs only minor alteration.
+
+-- [[JohnTalintyre]] - 29 Aug 2001 <br />