svn commit: r619393 - /maven/doxia/site/src/site/apt/macros/index.apt

[lt...@apache.org]

Author: ltheussl
Date: Thu Feb  7 05:03:24 2008
New Revision: 619393

URL: http://svn.apache.org/viewvc?rev=619393&view=rev
Log:
Update and clarify macro docs, in particular snippet macro after DOXIA-210

Modified:
    maven/doxia/site/src/site/apt/macros/index.apt

Modified: maven/doxia/site/src/site/apt/macros/index.apt
URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/macros/index.apt?rev=619393&r1=619392&r2=619393&view=diff
==============================================================================
--- maven/doxia/site/src/site/apt/macros/index.apt (original)
+++ maven/doxia/site/src/site/apt/macros/index.apt Thu Feb  7 05:03:24 2008
@@ -30,7 +30,40 @@
 
  The Doxia <Core> includes macro mechanisms to facilitate the documentation writing.
 
-*Echo Macro
+ Macros are best tested and supported for the standard Maven input formats APT and Xdoc,
+ they are also supported by Docbook, FML and XHTML input formats.
+ Macros are not currently supported by Confluence and Twiki modules.
+
+ A macro in an APT source file is a <<non-indented>> line that looks like this:
+
+-----
+%{macro_name|param1=value1|param2=value2|...}
+-----
+
+ An Xdoc macro has the following syntax:
+
+-----
+<macro name="macro_name">
+  <param name="param1" value="value1"/>
+  <param name="param2" value="value2"/>
+  ...
+</macro>
+-----
+
+ As of Doxia-1.0-beta-1, the following macros are available:
+
+ * {{{Echo_Macro} Echo Macro}}: print out parameters
+
+ * {{{Snippet_Macro} Snippet Macro}}: include (parts of) external files
+
+ * {{{TOC_Macro} TOC Macro}}: print a Table of Contents
+
+ * {{{SWF_Macro} SWF Macro}}: print Shockwave Flash assets
+
+ []
+
+
+*{Echo Macro}
 
  The <Echo> macro is a very simple macro: it prints out the key and value of any supplied parameters.
  For instance, in an APT file, you could write:
@@ -55,10 +88,10 @@
   param2 ---> value2
 -----
 
-*Snippet Macro
+*{Snippet Macro}
 
- The <Snippet> macro is a very useful macro: it prints out the content of a file or an URL. For instance,
- in an APT file, you could write:
+ The <Snippet> macro is a very useful macro: it prints out the content of a file or a URL.
+ For instance, in an APT file, you could write:
 
 -----
 %{snippet|id=myid|url=http://myserver/path/to/file.txt}
@@ -73,19 +106,23 @@
 </macro>
 -----
 
- If you need to include only a part of a file, you could add start and end snippets.
+ The <<<id>>> parameter is not required if you want to include the entire file.
+ If you want to include only a part of a file, you should add start and end demarcators:
+ any line (typically a comment) that contains the strings "<<<START>>>", "<<<SNIPPET>>>"
+ and "<<<myid>>>" (where <<<myid>>> is the <<<id>>> of the snippet) is a start demarcator,
+ and similarly "<<<END SNIPPET myid>>>" denotes the end of the snippet to include. For example:
 
   * Start and end snippets in a Java file
 
 -----
 public class MyClass
 {
-    // START SNIPPET: foo
+    // START SNIPPET: myid
     public static void main( String[] args ) throws Exception
     {
         ...
     }
-    // END SNIPPET: foo
+    // END SNIPPET: myid
 }
 -----
 
@@ -96,11 +133,11 @@
 ...
   <build>
     <plugins>
-<!-- START SNIPPET: foo -->
+<!-- START SNIPPET: myid -->
       <plugin>
         ...
       </plugin>
-<!-- END SNIPPET: foo -->
+<!-- END SNIPPET: myid -->
     </plugins>
   </build>
 </project>
@@ -111,18 +148,19 @@
 *-----------+--------------+
 || Parameter || Description  |
 *-----------+--------------+
-| id        | The id of the snippet (required).
+| id        | The id of the snippet to include.
+|           | If omitted the whole file/url will be included (since doxia-1.0-beta-1).
 *-----------+--------------+
 | url       | The path of the URL to include.
 *-----------+--------------+
-| file      | The path of the file to include.
+| file      | The path of the file to include (since doxia-1.0-alpha-9).
 *-----------+--------------+
 | verbatim  | If the content should be output as verbatim escaped text. If this is set to <<<false>>> then the content
 |           | of the snippet will not be escaped. This means that you can use it like Server-Side Includes on a
 |           | webserver. Default value is <<<true>>>.
 *-----------+--------------+
 
-*TOC Macro
+*{TOC Macro}
 
  The <TOC> macro prints a Table Of Content of a document. It is useful if you have several sections and
  subsections in your document. For instance, in an APT file, you could write:
@@ -151,7 +189,7 @@
 | toDepth   | Display the depth ending for the given section number. Positive int, not mandatory, 5 by default.
 *-----------+--------------+
 
-*SWF Macro
+*{SWF Macro}
 
  The <Swf> macro prints Shockwave Flash assets in the documentation. For instance, in an APT file,
  you could write: