first cut at METAL reference

lib/python/Products/PageTemplates/help/metal-define-macro.stx

+define-macro - Define a macro
+
+  Syntax
+
+    'metal:define-macro' syntax::
+
+      argument ::= Name
+
+  Description
+
+    The 'metal:define-macro' statement defines a macro. The macro is
+    named by the statement expression, and is defined as the element
+    and its sub-tree.
+
+    In Zope, a macro definition is available as a sub-object of a
+    template's 'macros' object. For example, to access a macro named
+    'header' in a template named 'master.html', you could use the path
+    expression 'master.html/macros/header'.
+
+  Examples
+
+    Simple macro definition::
+
+      <p metal:define-macro="copyright">
+        Copyright 2001, <em>Foobar</em> Inc.
+      </p>
+
+  See Also
+
+    "metal:use-macro":metal-use-macro.stx"
+
+    "metal:define-slot":metal-define-slot.stx
+    

lib/python/Products/PageTemplates/help/metal-define-slot.stx

+define-slot - Define a macro customization point
+
+  Syntax
+
+    'metal:define-slot' syntax::
+   
+      argument ::= Name
+
+  Description
+
+    The 'metal:define-slot' statement defines a macro customization
+    point or *slot*. When a macro is used, its slots can be replaced,
+    in order to customize the macro. Slot definitions provide default
+    content for the slot. You will get the default slot contents if
+    you decides not to customize the macro when using it.
+
+    The 'metal:define-slot' statement must be used inside a
+    'metal:define-macro' statement.
+
+    Slot names must be unique within a macro.
+
+  Examples
+
+    Simple macro with slot::
+
+      <p metal:define-macro="hello">
+        Hello <b metal:define-slot="name">World</b>
+      </p>
+ 
+    This example defines a macro with one slot named 'name'. When you
+    use this macro you can customize the 'b' element by filling the
+    'name' slot.
+
+  See Also
+
+    "metal:fill-slot":metal-fill-slot.stx
+
+
+

lib/python/Products/PageTemplates/help/metal-fill-slot.stx

+fill-slot - Customize a macro
+
+  Syntax
+
+    'metal:fill-slot' syntax::
+   
+      argument ::= Name
+
+  Description
+
+    The 'metal:fill-slot' statement customizes a macro by replacing a
+    *slot* in the macro with the statement element (and its content).
+
+    The 'metal:fill-slot' statement must be used inside a
+    'metal:use-macro' statement.
+
+    Slot names must be unique within a macro.
+
+    If the named slot does not exist within the macro, Zope will raise
+    an error.
+
+  Examples
+
+   Given this macro::
+
+      <p metal:define-macro="hello">
+        Hello <b metal:define-slot="name">World</b>
+      </p>
+ 
+    You can fill the 'name' slot like so::
+
+      <p metal:use-macro="container/master.html/macros/hello">
+        Hello <b metal:fill-slot="name">Kevin Bacon</b>
+      </p>
+ 
+  See Also
+    
+    "metal:define-slot":metal-define-slot.stx
\ No newline at end of file

lib/python/Products/PageTemplates/help/metal-use-macro.stx

+use-macro - Use a macro
+
+  Syntax
+
+    'metal:use-macro' syntax::
+   
+      argument ::= expression
+
+  Description
+
+    The 'metal:use-macro' statement replaces the statement element
+    with a macro. The statement expression describes a macro
+    definition. 
+
+    In Zope the expression will generally be a path expression
+    referring to a macro defined in another template. See
+    "metal:define-macro" for more information.
+
+    The effect of expanding a macro is to graft a subtree from another
+    document (or from elsewhere in the current document) in place of
+    the statement element, replacing the existing sub-tree.  Parts of
+    the original subtree may remain, grafted onto the new subtree, if
+    the macro has *slots*. See
+    "metal:define-slot":metal-define-slot.stx for more information. If
+    the macro body uses any macros, they are expanded first.
+
+    When a macro is expanded, its 'metal:define-macro' attribute is
+    replaced with the 'metal:use-macro' attribute from the statement
+    element.  This makes the root of the expanded macro a valid
+    'use-macro' statement element.
+
+  Examples
+
+    Basic macro usage::
+
+      <p metal:use-macro="container/other.html/macros/header">
+        header macro from defined in other.html template
+      </p>
+
+    This example refers to the 'header' macro defined in the
+    'other.html' template which is in the same folder as the current
+    template. When the macro is expanded, the 'p' element and its
+    contents will be replaced by the macro. Note: there will still be
+    a 'metal:use-macro' attribute on the replacement element.
+
+  See Also
+
+    "metal:define-macro":metal-define-macro.stx
+
+    "metal:use-slot":metal-use-slot.stx
+

lib/python/Products/PageTemplates/help/metal.stx

+METAL Overview
+
+  The *Macro Expansion Template Attribute Language* (METAL) standard
+  is a facility for HTML/XML macro preprocessing. It can be used in
+  conjunction with or independently of "TAL":tal.stx and
+  "TALES":tales.stx.
+
+  Macros provide a way to define a chunk of presentation in one
+  template, and share it in others, so that changes to the macro are
+  immediately reflected in all of the places that share it.
+  Additionally, macros are always fully expanded, even in a template's
+  source text, so that the template appears very similar to its final
+  rendering.
+
+  METAL Namespace
+
+    The METAL namespace URI and recommended alias are currently
+    defined as::
+
+      xmlns:metal="http://xml.zope.org/namespaces/metal"
+
+    Just like the TAL namespace URI, this URI is not attached to a web
+    page; it's just a unique identifier.
+
+  METAL Statements 
+
+    METAL defines a number of statements:
+
+    * "metal:define-macro":metal-define-macro.stx - Define a macro.
+
+    * "metal:use-macro":metal-use-macro.stx" - Use a macro.
+
+    * "metal:define-slot":metal-define-slot.stx - Define a macro
+    * customization point.
+
+    * "metal:use-slot":metal-use-slot.stx - Customize a macro.
+
+    Although METAL does not define the syntax of expression
+    non-terminals, leaving that up to the implementation, a canonical
+    expression syntax for use in METAL arguments is described in
+    "TALES Specification":tales.stx.
+
+  See Also
+
+    "TAL Overview":tal.stx
+
+    "TALES Overview":tales.stx
+
+    "metal:define-macro":metal-define-macro.stx
+
+    "metal:use-macro":metal-use-macro.stx"
+
+    "metal:define-slot":metal-define-slot.stx
+
+    "metal:use-slot":metal-use-slot.stx
+
+
+  
\ No newline at end of file