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>

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

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>

For more information, see the 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>