------
 Doxia Macros Guide
 ------
 Vincent Siveton
 ------
 2009-03-02
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Doxia Macros Guide

 The Doxia <Core> includes macro mechanisms to facilitate the documentation writing.

 Macros are currently only supported for APT, Xdoc and FML formats. Starting with Doxia 1.7 (maven-site-plugin 3.5),
 macros are also supported for XHTML and Markdown.
 Macros are not (and probably will never be) supported by Confluence, Docbook 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 or FML macro has the following syntax:

+----
<macro name="macro_name">
  <param name="param1" value="value1"/>
  <param name="param2" value="value2"/>
  ...
</macro>
+----

 Since Doxia 1.7, an XHTML or Markdown macro has the following syntax:

+----
<!-- MACRO{macro_name|param1=value1|param2=value2|...} -->
+----

 As of Doxia 1.7, the following macros are available:

%{toc|section=1|fromDepth=2|toDepth=2}

* {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:

+----
%{echo|param1=value1|param2=value2}
+----

 Similarly, it will be for xdoc file:

+----
<macro name="echo">
  <param name="param1" value="value1"/>
  <param name="param2" value="value2"/>
</macro>
+----

  and it will output

+----
  param1 ---> value1
  param2 ---> value2
+----

* {Snippet Macro}

 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}
+----

 In a xdoc file, it will be:

+----
<macro name="snippet">
  <param name="id" value="myid"/>
  <param name="url" value="http://myserver/path/to/file.txt"/>
</macro>
+----

 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: myid
    public static void main( String[] args ) throws Exception
    {
        ...
    }
    // END SNIPPET: myid
}
+----

  * Start and end snippets in a XML file

+----
<project>
...
  <build>
    <plugins>
<!-- START SNIPPET: myid -->
      <plugin>
        ...
      </plugin>
<!-- END SNIPPET: myid -->
    </plugins>
  </build>
</project>
+----

  []

*-----------+--------------+
|| Parameter || Description  |
*-----------+--------------+
| id        | The id of the snippet to include.
|           | If omitted the whole file/url will be included (since Doxia 1.1).
*-----------+--------------+
| url       | The path of the URL 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>>>.
*-----------+--------------+
| encoding  | The encoding of the file to read (since Doxia 1.6). If omitted the default JVM encoding will be used.
*-----------+--------------+

* {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:

+----
%{toc|section=2|fromDepth=2|toDepth=3}
+----

 This displays a TOC for the second section in the document, including all
 subsections (depth 2) and  sub-subsections (depth 3).

  <<Note>> that in Doxia, apt section titles are not implicit anchors
  (see {{{../references/doxia-apt.html}Enhancements to the APT format}}), so you need
  to insert explicit anchors for links to work!

 In a xdoc file, it will be:

+----
<macro name="toc">
  <param name="section" value="2"/>
  <param name="fromDepth" value="0"/>
  <param name="toDepth" value="4"/>
</macro>
+----

*-----------+--------------+
|| Parameter || Description  |
*-----------+--------------+
| section   | Display a TOC for the specified section only, or all sections if 0. Positive int, not mandatory, 0 by default.
*-----------+--------------+
| fromDepth | Minimum section depth to include in the TOC (sections are depth 1, sub-sections depth 2, etc.). Positive int, not mandatory, 0 by default.
*-----------+--------------+
| toDepth   | Maximum section depth to include in the TOC. Positive int, not mandatory, 5 by default.
*-----------+--------------+

 From <<Doxia 1.1.1>> on you may also specify any of the html base attributes
 (<i.e.> any of <<<id>>>, <<<class>>>, <<<style>>>, <<<lang>>>, <<<title>>>) as parameters, e.g.:

+----
%{toc|class=myTOC}
+----

 This can be used for styling the TOC via css.

* {SWF Macro}

 The <Swf> macro prints Shockwave Flash assets in the documentation. For instance, in an APT file,
 you could write:

+----
%{swf|src=swf/myfile.swf|id=MyMovie|width=600|height=200}
+----

 In a xdoc file, it will be:

+----
<macro name="swf">
  <param name="src" value="swf/myfile.swf"/>
  <param name="id" value="MyMovie"/>
  <param name="width" value="600"/>
  <param name="height" value="200"/>
</macro>
+----

*-----------+--------------+
|| Parameter || Description  |
*-----------+--------------+
| src       | Specifies the location (URL) of the movie to be loaded.
*-----------+--------------+
| id        | Identifies the Flash movie to the host environment (a web browser, for example) so that it can be referenced using a scripting language.
*-----------+--------------+
| width     | Specifies the width of the movie in either pixels or percentage of browser window.
*-----------+--------------+
| height    | Specifies the height of the movie in either pixels or percentage of browser window.
*-----------+--------------+
| quality   | Possible values: low, high, autolow, autohigh, best.
*-----------+--------------+
| menu      | True displays the full menu, allowing the user a variety of options to enhance or control playback. False displays a menu that contains only the Settings option and the About Flash option.
*-----------+--------------+
| loop      | Possible values: true, false. Specifies whether the movie repeats indefinitely or stops when it reaches the last frame. The default value is true if this attribute is omitted.
*-----------+--------------+
| play      | Possible values: true, false. Specifies whether the movie begins playing immediately on loading in the browser. The default value is true if this attribute is omitted.
*-----------+--------------+
| version   | Specifies the width of the movie in either pixels or percentage of browser window.
*-----------+--------------+
| allowScript | Specifies the width of the movie in either pixels or percentage of browser window.
*-----------+--------------+

 For more information, see the {{{./swf-macro.html}SWF Macro}} page.

* {SSI Macro}

 Since Doxia 1.7, the <SSI> macro prints a server side include. For instance, in an APT file,
 you could write:

+----
%{ssi|function=include|file=included-file.html}
+----

 In a xdoc file, it will be:

+----
<macro name="ssi">
  <param name="function" value="include"/>
  <param name="file" value="included-file.html"/>
</macro>
+----

*-----------+--------------+
|| Parameter || Description  |
*-----------+--------------+
| function  | The SSI function to insert.
*-----------+--------------+
| <any>     | Parameter that will be added to the SSI directive.
*-----------+--------------+