This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch feature/convert-to-md
in repository https://gitbox.apache.org/repos/asf/maven-doxia-site.git
commit ac566012c7698dfa94cf429709d18186a1e8953c
Author: Konrad Windszus <konrad.winds...@netcentric.biz>
AuthorDate: Thu Dec 12 18:54:13 2024 +0100
Convert from APT to MD with doxia-converter 1.4-SNAPSHOT
---
content/markdown/book/index.md | 85 ++---
content/markdown/developers/index.md | 73 ++--
content/markdown/developers/macros.md | 114 +++---
content/markdown/developers/modules.md.vm | 250 ++++++-------
content/markdown/developers/sink.md | 168 ++++-----
content/markdown/downloads.md | 60 ++--
content/markdown/doxia-tools/index.md | 70 ++--
content/markdown/index.md.vm | 108 +++---
content/markdown/issues/index.md | 128 +++----
content/markdown/macros/index.md | 360 ++++++++-----------
content/markdown/macros/swf-macro.md | 121 +++----
content/markdown/modules/index.md | 222 +++++-------
content/markdown/references/apt-format.md | 564 +++++++++++++-----------------
content/markdown/references/doxia-apt.md | 263 ++++++--------
content/markdown/resources.md | 97 +++--
content/site.xml | 3 +-
16 files changed, 1139 insertions(+), 1547 deletions(-)
diff --git a/content/markdown/book/index.md b/content/markdown/book/index.md
index 0fe35ae..f47e0b4 100644
--- a/content/markdown/book/index.md
+++ b/content/markdown/book/index.md
@@ -1,62 +1,53 @@
- -----
- Writing Books in Doxia
- -----
- Trygve Laugstol
- Vincent Siveton
- ------
- 2012-04-13
- ------
+---
+title: Writing Books in Doxia
+author:
+ - Trygve Laugstol
+ - Vincent Siveton
+date: 2012-04-13
+---
-~~ 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.
+<!-- 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
+# Introduction
-Introduction
+Doxia allows you to write books like user manuals and guides in any format
supported by Doxia\. You can include the manuals directly in your generated
site with links to the off\-line friendly formats like XDoc, PDF, RTF and
LaTeX\.
- Doxia allows you to write books like user manuals and guides in any format
supported by Doxia. You can include the manuals directly in your generated site
with links to the off-line
- friendly formats like XDoc, PDF, RTF and LaTeX.
+The Xdoc output which has been rendered into this site can be viewed
[here](../doxia-example-book/index.html)\.
- The Xdoc output which has been rendered into this site can be viewed
{{{../doxia-example-book/index.html}here}}.
+The generated PDF is [here](../doxia-example-book/doxia-example-book.pdf) and
the generated RTF [here](../doxia-example-book/doxia-example-book.rtf)\.
- The generated PDF is {{{../doxia-example-book/doxia-example-book.pdf}here}}
and the generated RTF
- {{{../doxia-example-book/doxia-example-book.rtf}here}}.
+## How It Works
-* How It Works
+The only thing you need in addition to the content files is a simple book
descriptor which specifies the ordering of the sections and the names for the
chapters\.
- The only thing you need in addition to the content files is a simple book
descriptor which specifies
- the ordering of the sections and the names for the chapters.
+## Creating a Book Descriptor
-* Creating a Book Descriptor
+An XML file describes the layout of the book\.
- An XML file describes the layout of the book.
+A sample is given below:
- A sample is given below:
+<!-- MACRO{snippet|id=example|file=content/books/example-book.xml} -->
+## Configuring Doxia Book Maven Plugin
-%{snippet|id=example|file=content/books/example-book.xml}
+This example illustrates how to configure the Doxia Book Maven Plugin\. It
will render the book in three different formats\. By default the output will be
under `target/generated-site/<format>/<book id> `\.
-* Configuring Doxia Book Maven Plugin
+The currently supported format ids are: `xdoc`, `pdf`, `latex`, `rtf`,
`xhtml`, `doc-book`
- This example illustrates how to configure the Doxia Book Maven Plugin. It
will render the book in three different formats.
- By default the output will be under <<<target/generated-site/<format>/<book
id> >>>.
+A sample `pom.xml` is given below:
- The currently supported format ids are: <<<xdoc>>>, <<<pdf>>>, <<<latex>>>,
<<<rtf>>>, <<<xhtml>>>, <<<doc-book>>>
-
- A sample <<<pom.xml>>> is given below:
-
-%{snippet|id=configuration|file=pom.xml}
+<!-- MACRO{snippet|id=configuration|file=pom.xml} -->
\ No newline at end of file
diff --git a/content/markdown/developers/index.md
b/content/markdown/developers/index.md
index d86f32b..d73cf87 100644
--- a/content/markdown/developers/index.md
+++ b/content/markdown/developers/index.md
@@ -1,40 +1,33 @@
- -----
- Doxia Developers Centre
- -----
- Vincent Siveton
- ------
- 2008-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 Developers Centre
-
- This documentation centre is for those that are developing Doxia modules or
macro.
-
- Currently you can find information on the following topics:
-
- * {{{./modules.html}Creating Doxia Modules}}
-
- * {{{./macros.html}Creating Doxia Macros}}
-
- * {{{./sink.html}Using the Doxia Sink API}}
-
+---
+title: Doxia Developers Centre
+author:
+ - Vincent Siveton
+date: 2008-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.-->
+
+# Doxia Developers Centre
+
+This documentation centre is for those that are developing Doxia modules or
macro\.
+
+Currently you can find information on the following topics:
+
+- [Creating Doxia Modules](./modules.html)
+- [Creating Doxia Macros](./macros.html)
+- [Using the Doxia Sink API](./sink.html)
diff --git a/content/markdown/developers/macros.md
b/content/markdown/developers/macros.md
index 4e46023..5def14c 100644
--- a/content/markdown/developers/macros.md
+++ b/content/markdown/developers/macros.md
@@ -1,38 +1,32 @@
- -----
- Doxia Developers Centre
- -----
- Vincent Siveton
- ------
- 2008-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
-
-Create a New Doxia Macro
-
- You need to add the following
{{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/}plexus-component-metadata
plugin}}
- configuration to generate the correct Plexus <component.xml> file from
annotations
- for the project containing your macro:
-
-+----
+---
+title: Doxia Developers Centre
+author:
+ - Vincent Siveton
+date: 2008-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.-->
+
+# Create a New Doxia Macro
+
+You need to add the following [plexus\-component\-metadata
plugin](https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/)
configuration to generate the correct Plexus _component\.xml_ file from
annotations for the project containing your macro:
+
+```unknown
<project>
...
<build>
@@ -55,11 +49,11 @@ Create a New Doxia Macro
</build>
...
</project>
-+----
+```
- You should implement the <AbstractMacro> class:
+You should implement the _AbstractMacro_ class:
-+----
+```unknown
import org.apache.maven.doxia.macro.AbstractMacro;
/**
@@ -77,36 +71,28 @@ public class MyMacro
}
...
}
-+----
-
- To use it, you need to write the following markups:
-
- * APT
-
-+----
-%{my|myParam=myValue} <!-- my is the macro name defined by role-hint -->
-+----
-
- * XDoc
-
-+----
-<macro name="my"> <!-- my is the required macro name defined by role-hint -->
- <param name="myParam" value="myValue"/>
-</macro>
-+----
-
- []
+```
-* {References}
+To use it, you need to write the following markups:
- * {{{../modules/index.html}Doxia Modules Guide}}
+- APT
- * {{{../macros/index.html}Doxia Macros Guide}}
+ ```unknown
+ %{my|myParam=myValue} <!-- my is the macro name defined by role-hint -->
+ ```
- * {{{../doxia/apidocs/index.html}Doxia API Reference}}
+- XDoc
- * {{{../doxia-sitetools/apidocs/index.html}Doxia Sitetools API Reference}}
+ ```unknown
+ <macro name="my"> <!-- my is the required macro name defined by role-hint
-->
+ <param name="myParam" value="myValue"/>
+ </macro>
+ ```
- * {{{/plugin-developers/cookbook/plexus-plugin-upgrade.html}Upgrading from
Plexus Javadoc Tags to Plexus Java Annotations}}
+## <a id="References"></a>References
- []
+- [Doxia Modules Guide](../modules/index.html)
+- [Doxia Macros Guide](../macros/index.html)
+- [Doxia API Reference](../doxia/apidocs/index.html)
+- [Doxia Sitetools API Reference](../doxia-sitetools/apidocs/index.html)
+- [Upgrading from Plexus Javadoc Tags to Plexus Java
Annotations](/plugin-developers/cookbook/plexus-plugin-upgrade.html)
diff --git a/content/markdown/developers/modules.md.vm
b/content/markdown/developers/modules.md.vm
index 89f5a0a..48fc1d0 100644
--- a/content/markdown/developers/modules.md.vm
+++ b/content/markdown/developers/modules.md.vm
@@ -1,36 +1,32 @@
- -----
- Doxia Developers Centre
- -----
- Vincent Siveton
- ------
- 2008-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
-
-Create a New Doxia Module
-
- First, the easiest way is to create a POM with <doxia-modules> as parent:
-
-+----
+---
+title: Doxia Developers Centre
+author:
+ - Vincent Siveton
+date: 2008-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.-->
+
+# Create a New Doxia Module
+
+First, the easiest way is to create a POM with _doxia\-modules_ as parent:
+
+```unknown
<project>
<parent>
<groupId>org.apache.maven.doxia</groupId>
@@ -43,104 +39,90 @@ Create a New Doxia Module
...
</project>
-+----
-
- Secondly, you should implement some Doxia classes, depending on what features
you want: parsing
- or generating markup.
-
-
-* Parsing
-
- * <MyParser> class
-
-+----
-import org.apache.maven.doxia.parser.AbstractParser;
-import org.apache.maven.doxia.parser.Parser;
-import org.codehaus.plexus.component.annotations.Component;
-
-@Component( role = Parser.class, hint = "my" )
-public class MyParser
- extends AbstractParser
-{
-...
-}
-+----
-
- Depending on the type markup, extending <<<AbstractTextParser>>>,
<<<AbstractXmlParser>>>
- or <<<XhtmlBaseParser>>> may give you more features.
-
- * <MyParseException> class (optional)
-
-+----
-import org.apache.maven.doxia.parser.ParseException;
-
-public class MyParseException
- extends ParseException
-{
-...
-}
-+----
-
- * <MyParserModule> class
-
-+----
-import org.apache.maven.doxia.parser.module.AbstractParserModule;
-import org.codehaus.plexus.component.annotations.Component;
-
-@Component( role = ParserModule.class, hint = "my" )
-public class MyParserModule
- extends AbstractParserModule
-{
-...
-}
-+----
-
-
-* Generating
-
- * <MySink> class
-
-+----
-import org.apache.maven.doxia.sink.SinkAdapter;
-
-public class MySink
- extends SinkAdapter
-{
-...
-}
-+----
-
- Depending on the type markup, extending <<<AbstractTextSink>>>,
<<<AbstractXmlSink>>>
- or <<<XhtmlBaseSink>>> may give you more features.
-
- * <MySinkFactory> class
-
-+----
-import org.apache.maven.doxia.sink.SinkFactory;
-import org.codehaus.plexus.component.annotations.Component;
-
-@Component( role = SinkFactory.class, hint = "my" )
-public class MySinkFactory
- extends SinkFactory
-{
-...
-}
-+----
-
- Depending on the type markup, extending <<<AbstractTextSinkFactory>>>,
<<<AbstractXmlSinkFactory>>>
- or <<<AbstractBinarySinkFactory>>> may give you more features.
-
- []
-
-
-* {References}
-
- * {{{../modules/index.html}Doxia Modules Guide}}
-
- * {{{../macros/index.html}Doxia Macros Guide}}
-
- * {{{../doxia/apidocs/index.html}Doxia API Reference}}
-
- * {{{../doxia-sitetools/apidocs/index.html}Doxia Sitetools API Reference}}
-
- []
+```
+
+Secondly, you should implement some Doxia classes, depending on what features
you want: parsing or generating markup\.
+
+${esc.h}${esc.h} Parsing
+
+- _MyParser_ class
+
+ ```unknown
+ import org.apache.maven.doxia.parser.AbstractParser;
+ import org.apache.maven.doxia.parser.Parser;
+ import org.codehaus.plexus.component.annotations.Component;
+
+ @Component( role = Parser.class, hint = "my" )
+ public class MyParser
+ extends AbstractParser
+ {
+ ...
+ }
+ ```
+
+ Depending on the type markup, extending `AbstractTextParser`,
`AbstractXmlParser` or `XhtmlBaseParser` may give you more features\.
+
+- _MyParseException_ class \(optional\)
+
+ ```unknown
+ import org.apache.maven.doxia.parser.ParseException;
+
+ public class MyParseException
+ extends ParseException
+ {
+ ...
+ }
+ ```
+
+- _MyParserModule_ class
+
+ ```unknown
+ import org.apache.maven.doxia.parser.module.AbstractParserModule;
+ import org.codehaus.plexus.component.annotations.Component;
+
+ @Component( role = ParserModule.class, hint = "my" )
+ public class MyParserModule
+ extends AbstractParserModule
+ {
+ ...
+ }
+ ```
+
+${esc.h}${esc.h} Generating
+
+- _MySink_ class
+
+ ```unknown
+ import org.apache.maven.doxia.sink.SinkAdapter;
+
+ public class MySink
+ extends SinkAdapter
+ {
+ ...
+ }
+ ```
+
+ Depending on the type markup, extending `AbstractTextSink`,
`AbstractXmlSink` or `XhtmlBaseSink` may give you more features\.
+
+- _MySinkFactory_ class
+
+ ```unknown
+ import org.apache.maven.doxia.sink.SinkFactory;
+ import org.codehaus.plexus.component.annotations.Component;
+
+ @Component( role = SinkFactory.class, hint = "my" )
+ public class MySinkFactory
+ extends SinkFactory
+ {
+ ...
+ }
+ ```
+
+ Depending on the type markup, extending `AbstractTextSinkFactory`,
`AbstractXmlSinkFactory` or `AbstractBinarySinkFactory` may give you more
features\.
+
+${esc.h}${esc.h} <a id="References"></a>References
+
+- [Doxia Modules Guide](../modules/index.html)
+- [Doxia Macros Guide](../macros/index.html)
+- [Doxia API Reference](../doxia/apidocs/index.html)
+- [Doxia Sitetools API Reference](../doxia-sitetools/apidocs/index.html)
diff --git a/content/markdown/developers/sink.md
b/content/markdown/developers/sink.md
index 479f4a8..ab6a272 100644
--- a/content/markdown/developers/sink.md
+++ b/content/markdown/developers/sink.md
@@ -1,41 +1,35 @@
- -----
- Doxia Developers Centre
- -----
- Vincent Siveton
- ------
- 2008-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
-
-Using the Doxia Sink API
-
-%{toc|section=1|fromDepth=2|toDepth=2}
-
-* {Transforming documents}
-
- Doxia can be used to transform an arbitrary input document to any supported
output format.
- The following snippet shows how to use a Doxia <Parser> to transform an apt
file to html:
-
-+----
+---
+title: Doxia Developers Centre
+author:
+ - Vincent Siveton
+date: 2008-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.-->
+
+# Using the Doxia Sink API
+
+<!-- MACRO{toc|section=1|fromDepth=2|toDepth=2} -->
+## <a id="Transforming_documents"></a>Transforming documents
+
+Doxia can be used to transform an arbitrary input document to any supported
output format\. The following snippet shows how to use a Doxia _Parser_ to
transform an apt file to html:
+
+```unknown
File userDir = new File( System.getProperty ( "user.dir" ) );
File inputFile = new File( userDir, "test.apt" );
File outputFile = new File( userDir, "test.html" );
@@ -49,22 +43,17 @@ Using the Doxia Sink API
Reader reader = ReaderFactory.newReader( inputFile, "UTF-8" );
parser.parse( reader, sink );
-+----
+```
- It is recommended that you use {{{http://plexus.codehaus.org/}Plexus}} to
look up the parser. In principle
- you could instantiate the parser directly ( <<<Parser parser = new
AptParser();>>> )
- but then some special features like macros will not be available.
+It is recommended that you use [Plexus](http://plexus.codehaus.org/) to look
up the parser\. In principle you could instantiate the parser directly \(
`Parser parser = new AptParser();` \) but then some special features like
macros will not be available\.
- You could also use the
{{{http://maven.apache.org/doxia/doxia-tools/doxia-converter/index.html}Doxia
Converter Tool}}
- to parse a given file/dir to another file/dir.
+You could also use the [Doxia Converter
Tool](http://maven.apache.org/doxia/doxia-tools/doxia-converter/index.html) to
parse a given file/dir to another file/dir\.
+## <a id="Generating_documents"></a>Generating documents
-* {Generating documents}
+The snippet below gives a simple example of how to generate a document using
the Doxia Sink API\.
- The snippet below gives a simple example of how
- to generate a document using the Doxia Sink API.
-
-+----
+```unknown
/**
* Generate a simple document and emit it
* into the specified sink. The sink is flushed but not closed.
@@ -111,78 +100,57 @@ Using the Doxia Sink API
sink.flush();
}
-+----
-
- A more complete example that also shows the 'canonical' order of events to
use when generating
- a document, can be found in the Doxia
-
{{{./doxia/doxia-core/xref-test/org/apache/maven/doxia/sink/SinkTestDocument.html}SinkTestDocument}}
- class.
+```
+A more complete example that also shows the 'canonical' order of
events to use when generating a document, can be found in the Doxia
[SinkTestDocument](./doxia/doxia-core/xref-test/org/apache/maven/doxia/sink/SinkTestDocument.html)
class\.
-* {Passing attributes to Sink events}
+## <a id="Passing_attributes_to_Sink_events"></a>Passing attributes to Sink
events
- A number of methods in the Sink API enable passing
- a set of attributes to many sink events. A typical use case is:
+A number of methods in the Sink API enable passing a set of attributes to many
sink events\. A typical use case is:
-+----
+```unknown
SinkEventAttributeSet atts = new SinkEventAttributeSet();
atts.addAttribute( SinkEventAttributes.ALIGN, "center" );
sink.paragraph( atts );
-+----
-
- The kind of attributes supported depends on the event and the sink
- implementation. The sink API specifies a list of suggested attribute
- names that sinks are expected to recognize and parsers are expected to use
- when emitting events.
+```
+The kind of attributes supported depends on the event and the sink
implementation\. The sink API specifies a list of suggested attribute names
that sinks are expected to recognize and parsers are expected to use when
emitting events\.
-* {Avoid sink.rawText!}
+## <a id="Avoid_sink.rawText.21"></a>Avoid sink\.rawText\!
- In <<Doxia 1.0>> it was a common practice to use sink.rawText() to generate
elements that
- were not supported by the Sink API. For example, the following snippet could
be used
- to generate a styled HTML \<div\> block:
+In **Doxia 1\.0** it was a common practice to use sink\.rawText\(\) to
generate elements that were not supported by the Sink API\. For example, the
following snippet could be used to generate a styled HTML <div> block:
-+----
+```unknown
sink.RawText( "<div style=\"cool\">" );
sink.text( "A text with a cool style." );
sink.rawText( "</div>" );
-+----
+```
- This has a major drawback however: it only works if the receiving Sink is a
HTML Sink.
- In other words, the above method will not work for target documents in any
other format than HTML
- (think of the FO Sink to generate a pdf, or a LaTeX sink,...).
+This has a major drawback however: it only works if the receiving Sink is a
HTML Sink\. In other words, the above method will not work for target documents
in any other format than HTML \(think of the FO Sink to generate a pdf, or a
LaTeX sink,\.\.\.\)\.
- In <<Doxia 1.1>> a new method unknown() was added to the Sink API that can
be used to emit
- an arbitrary event without making special assumptions about the receiving
Sink.
- Depending on the parameters, a Sink may decide whether or not to process the
event,
- emit it as raw text, as a comment, log it, etc.
+In **Doxia 1\.1** a new method unknown\(\) was added to the Sink API that can
be used to emit an arbitrary event without making special assumptions about the
receiving Sink\. Depending on the parameters, a Sink may decide whether or not
to process the event, emit it as raw text, as a comment, log it, etc\.
- The correct way to generate the above \<div\> block is now:
+The correct way to generate the above <div> block is now:
-+----
+```unknown
SinkEventAttributeSet atts = new SinkEventAttributeSet();
atts.addAttribute( SinkEventAttributes.STYLE, "cool" );
sink.unknown( "div", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_START )},
atts );
sink.text( "A text with a cool style." );
sink.unknown( "div", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_END )},
null );
-+----
+```
- Read the javadocs of the unknown() method in the
-
{{{./doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html}Sink}}
interface and the
-
{{{./doxia/doxia-core/apidocs/org/apache/maven/doxia/sink/XhtmlBaseSink.html}XhtmlbaseSink}}
- for information on the method parameters.
- Note that an arbitrary sink may be expected to ignore the unknown event
completely!
+Read the javadocs of the unknown\(\) method in the
[Sink](./doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html)
interface and the
[XhtmlbaseSink](./doxia/doxia-core/apidocs/org/apache/maven/doxia/sink/XhtmlBaseSink.html)
for information on the method parameters\. Note that an arbitrary sink may be
expected to ignore the unknown event completely\!
- <<In general, the rawText method should be avoided alltogether when emitting
events into an arbitrary Sink.>>
+**In general, the rawText method should be avoided alltogether when emitting
events into an arbitrary Sink\.**
+## <a id="How_to_inject_javascript_code_into_HTML"></a>How to inject
javascript code into HTML
-* {How to inject javascript code into HTML}
+Related to the above, here is the correct way of injecting a javascript
snippet into a Sink:
- Related to the above, here is the correct way of injecting a javascript
snippet into a Sink:
-
-+----
+```unknown
// the javascript code is emitted within a commented CDATA section
// so we have to start with a newline and comment the CDATA closing in the end
// note that the sink will replace the newline by the system EOL
@@ -194,17 +162,11 @@ atts.addAttribute( SinkEventAttributes.TYPE,
"text/javascript" );
sink.unknown( "script", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_START
)}, atts );
sink.unknown( "cdata", new Object[]{new Integer( HtmlMarkup.CDATA_TYPE ),
javascriptCode }, null );
sink.unknown( "script", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_END )},
null );
-+----
-
-
-* {References}
-
- * {{{../modules/index.html}Doxia Modules Guide}}
-
- * {{{../macros/index.html}Doxia Macros Guide}}
-
- * {{{../doxia/apidocs/index.html}Doxia API Reference}}
+```
- * {{{../doxia-sitetools/apidocs/index.html}Doxia Sitetools API Reference}}
+## <a id="References"></a>References
- []
+- [Doxia Modules Guide](../modules/index.html)
+- [Doxia Macros Guide](../macros/index.html)
+- [Doxia API Reference](../doxia/apidocs/index.html)
+- [Doxia Sitetools API Reference](../doxia-sitetools/apidocs/index.html)
diff --git a/content/markdown/downloads.md b/content/markdown/downloads.md
index beef55a..1791a63 100644
--- a/content/markdown/downloads.md
+++ b/content/markdown/downloads.md
@@ -1,39 +1,31 @@
- -----
- Download
- -----
- Vincent Siveton
- ------
- 2009-03-02
- ------
+---
+title: Download
+author:
+ - Vincent Siveton
+date: 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.
+<!-- 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
+# Maven Doxia Releases
-Maven Doxia Releases
+Releases of Maven Doxia are made available in both binary and source
distributions\. Individual JARs are also made available through Apache Maven
repositories\.
- Releases of Maven Doxia are made available in both binary and source
distributions.
- Individual JARs are also made available through Apache Maven repositories.
+Releases of all Doxia sub\-project components \(currently Doxia, Doxia
Sitetools and Doxia Tools\) may be downloaded from Maven's central
repository:
- Releases of all Doxia sub-project components (currently Doxia, Doxia
Sitetools and Doxia Tools)
- may be downloaded from Maven's central repository:
-
- * {{https://repo.maven.apache.org/maven2/org/apache/maven/doxia/}}
-
- []
+-
[https://repo\.maven\.apache\.org/maven2/org/apache/maven/doxia/](https://repo.maven.apache.org/maven2/org/apache/maven/doxia/)
diff --git a/content/markdown/doxia-tools/index.md
b/content/markdown/doxia-tools/index.md
index e07a513..2fcbfa3 100644
--- a/content/markdown/doxia-tools/index.md
+++ b/content/markdown/doxia-tools/index.md
@@ -1,41 +1,33 @@
- -----
- Available Doxia Tools
- -----
- Hervé Boutemy
- -----
- 2023-01-08
- -----
+---
+title: Available Doxia Tools
+author:
+ - Hervé Boutemy
+date: 2023-01-08
+---
-~~ 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.
+<!-- 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:-->
+<!-- https://maven.apache.org/doxia/references/apt-format.html-->
+# Available Doxia Tools
-~~ NOTE: For help with the syntax of this file, see:
-~~ https://maven.apache.org/doxia/references/apt-format.html
-
-Available Doxia Tools
-
-*--------------------------------------------------------------+--------------+------------+------------------+------------------------+--------------------+
-|| <<Doxia Tool>> || <<Version>>
|| <<Release Date>> || <<Description>> || <<Source Repository>> || <<Issue
Tracking>>
-*--------------------------------------------------------------+--------------+------------+------------------+------------------------+--------------------+
-| {{{./doxia-converter/} Doxia Converter}} | 1.3
| 2023-01-14 | Convert a source document from one supported Doxia format to
other supported Doxia format.. |
{{{https://gitbox.apache.org/repos/asf/maven-doxia-converter.git}Git}} /
{{{https://github.com/apache/maven-doxia-converter/}GitHub}} |
{{{https://issues.apache.org/jira/browse/DOXIATOOLS}Jira DOXIATOOLS}}
-*--------------------------------------------------------------+--------------+------------+------------------+------------------------+--------------------+
-| {{{./doxia-linkcheck/} Doxia LinkCheck}} | 1.2
| 2010-11-09 | Validate the links in a set of HTML documents. |
{{{https://gitbox.apache.org/repos/asf/maven-doxia-linkcheck.git}Git}} /
{{{https://github.com/apache/maven-doxia-linkcheck/}GitHub}} |
{{{https://issues.apache.org/jira/browse/DOXIATOOLS}Jira DOXIATOOLS}}
-*--------------------------------------------------------------+--------------+------------+------------------+------------------------+--------------------+
-| <<Book-oriented Tools>> |
| | | |
-*--------------------------------------------------------------+--------------+------------+------------------+------------------------+--------------------+
-| {{{./doxia-book-maven-plugin/} Doxia Book Maven Plugin}} | 1.2
| 2010-11-09 | Create books in different output formats. |
{{{https://gitbox.apache.org/repos/asf/maven-doxia-book-maven-plugin.git}Git}}
/ {{{https://github.com/apache/maven-doxia-book-maven-plugin/}GitHub}} |
{{{https://issues.apache.org/jira/browse/DOXIATOOLS}Jira DOXIATOOLS}}
-*--------------------------------------------------------------+--------------+------------+------------------+------------------------+--------------------+
+|**Doxia Tool**|**Version**|**Release Date**|**Description**|**Source
Repository**|**Issue Tracking**|
+|:---|:---|:---|:---|:---|:---|
+|[ Doxia Converter](./doxia-converter/)|1\.3|2023\-01\-14|Convert a source
document from one supported Doxia format to other supported Doxia
format\.\.|[Git](https://gitbox.apache.org/repos/asf/maven-doxia-converter.git)
/ [GitHub](https://github.com/apache/maven-doxia-converter/)|[Jira
DOXIATOOLS](https://issues.apache.org/jira/browse/DOXIATOOLS)|
+|[ Doxia LinkCheck](./doxia-linkcheck/)|1\.2|2010\-11\-09|Validate the links
in a set of HTML
documents\.|[Git](https://gitbox.apache.org/repos/asf/maven-doxia-linkcheck.git)
/ [GitHub](https://github.com/apache/maven-doxia-linkcheck/)|[Jira
DOXIATOOLS](https://issues.apache.org/jira/browse/DOXIATOOLS)|
+|**Book\-oriented Tools**||||||
+|[ Doxia Book Maven
Plugin](./doxia-book-maven-plugin/)|1\.2|2010\-11\-09|Create books in different
output
formats\.|[Git](https://gitbox.apache.org/repos/asf/maven-doxia-book-maven-plugin.git)
/ [GitHub](https://github.com/apache/maven-doxia-book-maven-plugin/)|[Jira
DOXIATOOLS](https://issues.apache.org/jira/browse/DOXIATOOLS)|
diff --git a/content/markdown/index.md.vm b/content/markdown/index.md.vm
index 7cbd054..f1e35ac 100644
--- a/content/markdown/index.md.vm
+++ b/content/markdown/index.md.vm
@@ -1,80 +1,56 @@
- -----
- Introduction
- -----
- Jason van Zyl
- Vincent Siveton
- ------
- 2010-05-28
- ------
+---
+title: Introduction
+author:
+ - Jason van Zyl
+ - Vincent Siveton
+date: 2010-05-28
+---
-~~ 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.
+<!-- 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
+# Maven Doxia
-Maven Doxia
+Doxia is a content generation framework which aims to provide its users with
powerful techniques for generating static and dynamic content: Doxia can be
used in web\-based publishing context to generate static sites, in addition to
being incorporated into dynamic content generation systems like blogs, wikis
and content management systems\.
- Doxia is a content generation framework which aims to provide its users with
powerful
- techniques for generating static and dynamic content: Doxia can be used in
web-based
- publishing context to generate static sites, in addition to being
incorporated into
- dynamic content generation systems like blogs, wikis and content management
systems.
+Doxia supports [markup languages with simple
syntaxes](./references/index.html)\. Lightweight markup languages are used by
people who might be expected to read the document source as well as the
rendered output\.
- Doxia supports {{{./references/index.html}markup languages with simple
syntaxes}}. Lightweight markup languages
- are used by people who might be expected to read the document source as well
as the rendered
- output.
+Doxia is used extensively by [Maven](http://maven.apache.org) and it powers
the entire documentation system of Maven\. It gives Maven the ability to take
any document that Doxia supports and output it any format\.
- Doxia is used extensively by {{{http://maven.apache.org}Maven}} and it powers
the entire
- documentation system of Maven.
- It gives Maven the ability to take any document that Doxia supports and
output it any format.
+The current version of [Doxia base framework](./doxia/) is ${doxiaVersion}.
- The current version of {{{./doxia/}Doxia base framework}} is ${doxiaVersion}.
+${esc.h}${esc.h} Brief History
-* Brief History
+<!-- {{{http://www.xmlmind.com/aptconvert.html}Aptconvert}}-->
-~~ {{{http://www.xmlmind.com/aptconvert.html}Aptconvert}}
+Based on the \(now defunct\) Aptconvert project developed by
[Xmlmind](http://www.xmlmind.com/), Doxia was initially hosted by
[Codehaus](http://codehaus.org/), to become a sub\-project of Maven early in
2006\.
- Based on the (now defunct) Aptconvert project developed by
- {{{http://www.xmlmind.com/}Xmlmind}}, Doxia was initially hosted by
- {{{http://codehaus.org/}Codehaus}}, to become a sub-project of Maven early in
2006.
+${esc.h}${esc.h} Main Features
-* Main Features
+- Developed in Java
+- [Support of several markup formats](./references/index.html): APT \(Almost
Plain Text\), Confluence, Simplified DocBook, Markdown, FML \(FAQ Markup
Language\), FO, iText, LaTeX, RTF, TWiki, XDoc \(popular in Apache land\), XHTML
+- Easy to [learn the syntax of the supported markup
formats](./modules/index.html)
+- Macro support
+- No need to have a corporate infrastructure \(like wiki\) to host your
documentation
+- Extensible framework
+- [Site Tools extension](./doxia-sitetools/) for site or document rendering
+- [Additional Tools](./doxia-tools/) like [Doxia
Converter](./doxia-tools/doxia-converter/index.html)
- * Developed in Java
+${esc.h}${esc.h} Doxia Reference Pages
- * {{{./references/index.html}Support of several markup formats}}: APT
(Almost Plain Text), Confluence,
- Simplified DocBook, Markdown, FML (FAQ Markup Language), FO, iText, LaTeX,
RTF, TWiki,
- XDoc (popular in Apache land), XHTML
+See [Doxia Markup Languages References](./references/index.html) page for a
listing of all supported markups for each format\.
- * Easy to {{{./modules/index.html}learn the syntax of the supported markup
formats}}
-
- * Macro support
-
- * No need to have a corporate infrastructure (like wiki) to host your
documentation
-
- * Extensible framework
-
- * {{{./doxia-sitetools/}Site Tools extension}} for site or document rendering
-
- * {{{./doxia-tools/}Additional Tools}} like
{{{./doxia-tools/doxia-converter/index.html}Doxia Converter}}
-
- []
-
-* Doxia Reference Pages
-
- See {{{./references/index.html}Doxia Markup Languages References}} page for
a listing of all supported markups
- for each format.
diff --git a/content/markdown/issues/index.md b/content/markdown/issues/index.md
index 1aa4ee0..f464bfb 100644
--- a/content/markdown/issues/index.md
+++ b/content/markdown/issues/index.md
@@ -1,71 +1,55 @@
- -----
- Doxia Issues
- -----
- Lukas Theussl
- ------
- 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 Issues & Gotchas
-
- This document collects some infos about specific issues and 'gotchas' when
working with Doxia.
- Please check also the {{{../faq.html}Frequently Asked Questions}}.
-
-%{toc|section=1|fromDepth=2|toDepth=2}
-
-* {Apt anchors and links}
-
- Using <<Doxia 1.1>> you may see a lot of warnings when processing old Apt
source files:
-
-+----
+---
+title: Doxia Issues
+author:
+ - Lukas Theussl
+date: 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.-->
+
+# Doxia Issues & Gotchas
+
+This document collects some infos about specific issues and
'gotchas' when working with Doxia\. Please check also the [Frequently
Asked Questions](../faq.html)\.
+
+<!-- MACRO{toc|section=1|fromDepth=2|toDepth=2} -->
+## <a id="Apt_anchors_and_links"></a>Apt anchors and links
+
+Using **Doxia 1\.1** you may see a lot of warnings when processing old Apt
source files:
+
+```unknown
[WARNING] [Apt Parser] Ambiguous link: 'doxia-apt.html'. If this is a local
link, prepend "./"!
-+----
+```
- and
+and
-+----
+```unknown
[WARNING] [Apt Parser] Modified invalid link: references/doxia-apt.html
-+----
+```
- The reason is that in Apt, links to other source documents have to start with
- either <<<./>>> or <<<../>>> to distinguish them from internal links.
- Please read the sections on {{{../references/doxia-apt.html#Anchors}anchors}}
- and {{{../references/doxia-apt.html#Links}links}} in our Apt guide.
- Note in particular that internal links in Apt do <<not>> start with '#'.
+The reason is that in Apt, links to other source documents have to start with
either `./` or `../` to distinguish them from internal links\. Please read the
sections on [anchors](../references/doxia-apt.html#Anchors) and
[links](../references/doxia-apt.html#Links) in our Apt guide\. Note in
particular that internal links in Apt do **not** start with '\#'\.
- <<You should pay attention to these warnings since your links will
- most likely be broken.>> Unfortunately, the warning message cannot
- indicate the source file with the broken link
- (see eg {{{https://issues.apache.org/jira/browse/MPDF-11}MPDF-11}}),
however, if you run
- in <<<DEBUG>>> mode, eg invoke maven with the <<<-X>>> switch,
- you can see which source document is being parsed when the warning is
emitted.
+**You should pay attention to these warnings since your links will most likely
be broken\.** Unfortunately, the warning message cannot indicate the source
file with the broken link \(see eg
[MPDF\-11](https://issues.apache.org/jira/browse/MPDF-11)\), however, if you
run in `DEBUG` mode, eg invoke maven with the `-X` switch, you can see which
source document is being parsed when the warning is emitted\.
-* {Figure sink events}
+## <a id="Figure_sink_events"></a>Figure sink events
- Doxia distinguishes between figures, which are block-level elements, and
images (or icons),
- which are in-line elements. For instance, the following sequence of sink
events
+Doxia distinguishes between figures, which are block\-level elements, and
images \(or icons\), which are in\-line elements\. For instance, the following
sequence of sink events
-+----
+```unknown
sink.figure( null );
sink.figureGraphics( "figure.png", null );
@@ -75,30 +59,26 @@ sink.text( "Figure caption", null );
sink.figureCaption_();
sink.figure_();
-+----
+```
- should output the equivalent of this html snippet:
+should output the equivalent of this html snippet:
-+----
+```unknown
<div class="figure">
<p><img src="figure.png"/></p>
<p>Figure caption</p>
</div>
-+----
+```
- while the <<<figureGraphics( ... );>>> event alone can be used to generate
an in-line image,
- i.e. just the <<<\<img\>>>> tag in case of html.
+while the `figureGraphics( ... );` event alone can be used to generate an
in\-line image, i\.e\. just the `<img>` tag in case of html\.
- <<Note>> that we are using the forms that take a <<<SinkEventAttributeSet>>>
above, even though we
- are just passing in null values. The reason is that the alternative forms
(without <<<SinkEventAttributeSet>>>)
- have a different behavior, which is kept for backward compatibility (but the
methods have been deprecated).
- Using the same sequence of sink events as above, but omitting the <<<null>>>
method parameters, will generate
+**Note** that we are using the forms that take a `SinkEventAttributeSet`
above, even though we are just passing in null values\. The reason is that the
alternative forms \(without `SinkEventAttributeSet`\) have a different
behavior, which is kept for backward compatibility \(but the methods have been
deprecated\)\. Using the same sequence of sink events as above, but omitting
the `null` method parameters, will generate
-+----
+```unknown
<img src="figure.png" alt="Figure caption"/>
-+----
+```
-* {Empty Generated Page}
+## <a id="Empty_Generated_Page"></a>Empty Generated Page
+
+After running `mvn site` using your Maven reporting plugin, you see that the
generated page is empty\. Be sure that the the code calls `sink.close()`\.
- After running <<<mvn site>>> using your Maven reporting plugin, you see that
the generated page is empty.
- Be sure that the the code calls <<<sink.close()>>>.
diff --git a/content/markdown/macros/index.md b/content/markdown/macros/index.md
index 60f0bb2..d1b1773 100644
--- a/content/markdown/macros/index.md
+++ b/content/markdown/macros/index.md
@@ -1,277 +1,227 @@
- ------
- 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:
-
-+----
+---
+title: Doxia Macros Guide
+author:
+ - Vincent Siveton
+date: 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.-->
+
+# 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:
+
+```unknown
%{macro_name|param1=value1|param2=value2|...}
-+----
+```
- An Xdoc or FML macro has the following syntax:
+An Xdoc or FML macro has the following syntax:
-+----
+```unknown
<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:
+Since Doxia 1\.7, an XHTML or Markdown macro has the following syntax:
-+----
+```unknown
<!-- MACRO{macro_name|param1=value1|param2=value2|...} -->
-+----
+```
- As of Doxia 1.7, the following macros are available:
+As of Doxia 1\.7, the following macros are available:
-%{toc|section=1|fromDepth=2|toDepth=2}
+<!-- MACRO{toc|section=1|fromDepth=2|toDepth=2} -->
+## <a id="Echo_Macro"></a>Echo Macro
-* {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:
- 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:
-
-+----
+```unknown
%{echo|param1=value1|param2=value2}
-+----
+```
- Similarly, it will be for xdoc file:
+Similarly, it will be for xdoc file:
-+----
+```unknown
<macro name="echo">
<param name="param1" value="value1"/>
<param name="param2" value="value2"/>
</macro>
-+----
+```
- and it will output
+and it will output
-+----
+```unknown
param1 ---> value1
param2 ---> value2
-+----
+```
-* {Snippet Macro}
+## <a id="Snippet_Macro"></a>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:
+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:
-+----
+```unknown
%{snippet|id=myid|url=http://myserver/path/to/file.txt}
-+----
+```
- In a xdoc file, it will be:
+In a xdoc file, it will be:
-+----
+```unknown
<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:
+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
+- Start and end snippets in a Java file
-+----
-public class MyClass
-{
- // START SNIPPET: myid
- public static void main( String[] args ) throws Exception
+ ```unknown
+ public class MyClass
{
- ...
+ // START SNIPPET: myid
+ public static void main( String[] args ) throws Exception
+ {
+ ...
+ }
+ // END SNIPPET: myid
}
- // 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:
-
-+----
+ ```
+
+- Start and end snippets in a XML file
+
+ ```unknown
+ <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\.|
+## <a id="TOC_Macro"></a>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:
+
+```unknown
%{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).
+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!
+**Note** that in Doxia, apt section titles are not implicit anchors \(see
[Enhancements to the APT format](../references/doxia-apt.html)\), so you need
to insert explicit anchors for links to work\!
- In a xdoc file, it will be:
+In a xdoc file, it will be:
-+----
+```unknown
<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.:
-
-+----
+```
+
+|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\.:
+
+```unknown
%{toc|class=myTOC}
-+----
+```
- This can be used for styling the TOC via css.
+This can be used for styling the TOC via css\.
-* {SWF Macro}
+## <a id="SWF_Macro"></a>SWF Macro
- The <Swf> macro prints Shockwave Flash assets in the documentation. For
instance, in an APT file,
- you could write:
+The _Swf_ macro prints Shockwave Flash assets in the documentation\. For
instance, in an APT file, you could write:
-+----
+```unknown
%{swf|src=swf/myfile.swf|id=MyMovie|width=600|height=200}
-+----
+```
- In a xdoc file, it will be:
+In a xdoc file, it will be:
-+----
+```unknown
<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:
-
-+----
+```
+
+|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](./swf-macro.html) page\.
+
+## <a id="SSI_Macro"></a>SSI Macro
+
+Since Doxia 1\.7, the _SSI_ macro prints a server side include\. For instance,
in an APT file, you could write:
+
+```unknown
%{ssi|function=include|file=included-file.html}
-+----
+```
- In a xdoc file, it will be:
+In a xdoc file, it will be:
-+----
+```unknown
<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.
-*-----------+--------------+
+```
+
+|Parameter|Description|
+|:---|:---|
+|function|The SSI function to insert\.|
+|_any_|Parameter that will be added to the SSI directive\.|
diff --git a/content/markdown/macros/swf-macro.md
b/content/markdown/macros/swf-macro.md
index 0392035..d548989 100644
--- a/content/markdown/macros/swf-macro.md
+++ b/content/markdown/macros/swf-macro.md
@@ -1,36 +1,33 @@
- ------
- Doxia - SWF Macro
- ------
- The Maven Team
- ------
- 2007-05-17
- ------
-
-~~ 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.
-
-SWF Macro
-
- The SWF macro enables users of APT to put SWF (Flash) assets in their
documentation.
-
- Flash assets typically need to be wrappered in <<<object>>> and <<<embed>>>
tags and can have
- a variety of parameters. Below is a typical example:
-
-+----
+---
+title: Doxia - SWF Macro
+author:
+ - The Maven Team
+date: 2007-05-17
+---
+
+<!-- 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.-->
+# SWF Macro
+
+The SWF macro enables users of APT to put SWF \(Flash\) assets in their
documentation\.
+
+Flash assets typically need to be wrappered in `object` and `embed` tags and
can have a variety of parameters\. Below is a typical example:
+
+```unknown
<object classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000'
codebase='http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=6,0,29,0'
width='400' height='400' id='MyMovie'>
@@ -42,53 +39,41 @@ SWF Macro
pluginspage='http://www.macromedia.com/go/getflashplayer'
type='application/x-shockwave-flash' menu='false'></embed>
</object>
-+----
+```
- In order to use a *.swf in your APT file, use the basic syntax:
+In order to use a \*\.swf in your APT file, use the basic syntax:
-+----
+```unknown
%{swf|src=swf/myfile.swf|id=MyMovie|width=600|height=200}
-+----
+```
- For which <<<src>>> is the required parameter. Make sure to put your *.swf
file into
- the <</resources>> folder so that it will get copied to /target when running
the <<<mvn site>>> task.
+For which `src` is the required parameter\. Make sure to put your \*\.swf file
into the **/resources** folder so that it will get copied to /target when
running the `mvn site` task\.
- You can use more advanced parameters to control the output, as per below:
+You can use more advanced parameters to control the output, as per below:
-+----
+```unknown
%{swf|src=swf/myfile.swf|id=MyMovie|width=600|height=200|version=9|allowScript=always}
-+----
+```
- For a full listing of parameters and their values see the Adobe knowledge
base:
+For a full listing of parameters and their values see the Adobe knowledge base:
-
{{{http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=tn_12701}http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=tn_12701}}
+[http://www\.adobe\.com/cfusion/knowledgebase/index\.cfm?id=tn\_12701](http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=tn_12701)
-*Parameters and Defaults
+## Parameters and Defaults
- Currently the following parameters are available through the macro. If no
value is placed within a parameter, the
- value will default to the following:
+Currently the following parameters are available through the macro\. If no
value is placed within a parameter, the value will default to the following:
- * id = "swf"
+- id = "swf"
+- width = "400"
+- height = "400"
+- quality = "high"
+- menu = "false"
+- loop = "0"
+- play = "true"
+- version = "9,0,45,0"
+- allowScript = "sameDomain"
- * width = "400"
+Note: There is some provided shorthand for versions, i\.e\. \- version=6 \-
becomes version=6,0,29,0\.
- * height = "400"
+_TODO:_ only shorthand for 6 and 9 are functional\. Need to find standard long
version for other types\.
- * quality = "high"
-
- * menu = "false"
-
- * loop = "0"
-
- * play = "true"
-
- * version = "9,0,45,0"
-
- * allowScript = "sameDomain"
-
- []
-
- Note: There is some provided shorthand for versions, i.e. - version=6 -
becomes version=6,0,29,0.
-
- <TODO:> only shorthand for 6 and 9 are functional. Need to find standard
long
- version for other types.
diff --git a/content/markdown/modules/index.md
b/content/markdown/modules/index.md
index 0a0e52c..67feb61 100644
--- a/content/markdown/modules/index.md
+++ b/content/markdown/modules/index.md
@@ -1,179 +1,123 @@
- -----
- Doxia Modules Guide
- -----
- Vincent Siveton
- ------
- 2009-06-15
- ------
+---
+title: Doxia Modules Guide
+author:
+ - Vincent Siveton
+date: 2009-06-15
+---
-~~ 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.
+<!-- 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 Modules Guide
-Doxia Modules Guide
+Doxia has several built\-in modules that support some standard markup
languages, see the [References](../references/index.html) page for an
overview\. The following is just a collection of reference links for the
individual formats\.
- Doxia has several built-in modules that support some standard markup
languages,
- see the {{{../references/index.html}References}} page for an overview. The
following
- is just a collection of reference links for the individual formats.
+<!-- MACRO{toc|section=1|fromDepth=2|toDepth=2} -->
+## <a id="APT"></a>APT
-%{toc|section=1|fromDepth=2|toDepth=2}
+APT \(Almost Plain Text\) is a simple text format\.
+**References**:
-* {APT}
+- [Apt Reference](../references/apt-format.html)
+## <a id="Confluence"></a>Confluence
- APT (Almost Plain Text) is a simple text format.
+[Confluence](http://confluence.atlassian.com) is an Enterprise wiki from
[Atlassian](http://www.atlassian.com)\. It uses
[Textile](http://textism.com/tools/textile/) inside as an APT language\.
- <<References>>:
+**References**:
- * {{{../references/apt-format.html}Apt Reference}}
+- [Confluence Notation Guide
Overview](http://confluence.atlassian.com/display/CONF25/Confluence+Notation+Guide+Overview)
+- [Confluence Element
Reference](http://confluence.atlassian.com/renderer/notationhelp.action?section=all)
+<!-- Textile in Java
{{{https://sourceforge.net/projects/jtextile/}JTextile}}.-->
+<!-- http://hobix.com/textile/-->
+## <a id="Simplified_DocBook"></a>Simplified DocBook
- []
+[DocBook](http://docbook.org/) is a markup language for technical
documentation\. [Simplified DocBook](http://www.docbook.org/schemas/simplified)
is a simpler subset\.
-* {Confluence}
+**References**:
- {{{http://confluence.atlassian.com}Confluence}} is an Enterprise wiki from
{{{http://www.atlassian.com}Atlassian}}.
- It uses {{{http://textism.com/tools/textile/}Textile}} inside as an APT
language.
+- [Simplified DocBook Introduction](https://www.docbook.org/schemas/simplified)
+- [Simplified DocBook Element
Reference](http://www.docbook.org/xml/simple/sdocbook/elements.html)
+## <a id="FML"></a>FML
- <<References>>:
+FML \(FAQ Markup Language\) is a FAQ markup language\.
- *
{{{http://confluence.atlassian.com/display/CONF25/Confluence+Notation+Guide+Overview}Confluence
Notation Guide Overview}}
+**References**:
- *
{{{http://confluence.atlassian.com/renderer/notationhelp.action?section=all}Confluence
Element Reference}}
+- [FML Reference](../references/fml-format.html)
+## <a id="iText"></a>iText
- []
+[iText](http://www.lowagie.com/iText/) is a free Java/PDF library\.
-~~ Textile in Java {{{https://sourceforge.net/projects/jtextile/}JTextile}}.
-~~ http://hobix.com/textile/
+**References**:
-* {Simplified DocBook}
+- [iText tutorial](http://itextdocs.lowagie.com/tutorial/)
+<!-- * {{{http://www.lowagie.com/iText/tutorial/ch07.html}(out-dated) chapter
on XML support}}-->
+## <a id="FO"></a>FO
- {{{http://docbook.org/}DocBook}} is a markup language for technical
documentation.
- {{{http://www.docbook.org/schemas/simplified}Simplified DocBook}} is a
simpler subset.
+XSL formatting objects \(XSL\-FO\)
- <<References>>:
+**References**:
- * {{{https://www.docbook.org/schemas/simplified}Simplified DocBook
Introduction}}
+- [XSL\-FO Recommendation \(05 December 2006\)](https://www.w3.org/TR/xsl11/)
+- [XSL FO reference](https://zvon.org/xxl/xslfoReference/Output/index.html)
+- [Apache FOP](https://xmlgraphics.apache.org/fop/)
+## <a id="LaTeX"></a>LaTeX
- * {{{http://www.docbook.org/xml/simple/sdocbook/elements.html}Simplified
DocBook Element Reference}}
+[LaTeX](https://www.latex-project.org/) is a popular document markup language\.
- []
+**References**:
-* {FML}
+- [LaTeX2e for authors](https://www.latex-project.org/guides/usrguide.pdf)
+- [Latex reference sheet](http://www.stdout.org/~winston/latex/latexsheet.pdf)
+## <a id="Markdown"></a>Markdown
- FML (FAQ Markup Language) is a FAQ markup language.
+[Markdown](http://en.wikipedia.org/wiki/Markdown) is a widespread Markup
language\.
- <<References>>:
+**References**:
- * {{{../references/fml-format.html}FML Reference}}
+- [Official Markdown project at Daring
Fireball](https://daringfireball.net/projects/markdown/)
+## <a id="RTF"></a>RTF
- []
+[RTF](http://www.microsoft.com/downloads/details.aspx?FamilyId=DD422B8D-FF06-4207-B476-6B5396A18A2B&displaylang=en)
is a proprietary document file format\.
-* {iText}
+**References**:
- {{{http://www.lowagie.com/iText/}iText}} is a free Java/PDF library.
+- [Microsoft Office Word 2007 Rich Text Format \(RTF\)
Specification](http://www.microsoft.com/downloads/info.aspx?na=46&p=1&SrcDisplayLang=en&SrcCategoryId=&SrcFamilyId=dd422b8d-ff06-4207-b476-6b5396a18a2b&u=http%3a%2f%2fdownload.microsoft.com%2fdownload%2f2%2ff%2f5%2f2f599e18-07ee-4ec5-a1e7-f4e6a9423592%2fWord2007RTFSpec9.doc&oRef=http%3a%2f%2fmsdn2.microsoft.com%2fen-us%2foffice%2faa905482.aspx)
+- [RTF
Cookbook](http://search.cpan.org/~sburke/RTF-Writer/lib/RTF/Cookbook.pod)
+## <a id="TWiki"></a>TWiki
- <<References>>:
+[TWiki](https://twiki.org/) is a structured wiki\.
- * {{{http://itextdocs.lowagie.com/tutorial/}iText tutorial}}
+**References**:
-~~ * {{{http://www.lowagie.com/iText/tutorial/ch07.html}(out-dated) chapter
on XML support}}
+- [ TWiki Text
Formatting](https://twiki.org/cgi-bin/view/TWiki04x01/TextFormattingRules)
+## <a id="XDoc"></a>XDoc
- []
+XDoc is a generic format for document into a styled HTML document\.
-* {FO}
+**References**:
- XSL formatting objects (XSL-FO)
+- [XDoc Reference](../references/xdoc-format.html)
+## <a id="XHTML"></a>XHTML
- <<References>>:
+[XHTML](https://www.w3.org/MarkUp/) is a markup language with the same
expressions as HTML, but also conforms to XML syntax\.
- * {{{https://www.w3.org/TR/xsl11/}XSL-FO Recommendation (05 December 2006)}}
+**References**:
- * {{{https://zvon.org/xxl/xslfoReference/Output/index.html}XSL FO reference}}
-
- * {{{https://xmlgraphics.apache.org/fop/}Apache FOP}}
-
- []
-
-* {LaTeX}
-
- {{{https://www.latex-project.org/}LaTeX}} is a popular document markup
language.
-
- <<References>>:
-
- * {{{https://www.latex-project.org/guides/usrguide.pdf}LaTeX2e for authors}}
-
- * {{{http://www.stdout.org/~winston/latex/latexsheet.pdf}Latex reference
sheet}}
-
- []
-
-* {Markdown}
-
- {{{http://en.wikipedia.org/wiki/Markdown}Markdown}} is a widespread Markup
language.
-
- <<References>>:
-
- * {{{https://daringfireball.net/projects/markdown/}Official Markdown project
at Daring Fireball}}
-
- []
-
-* {RTF}
-
-
{{{http://www.microsoft.com/downloads/details.aspx?FamilyId=DD422B8D-FF06-4207-B476-6B5396A18A2B&displaylang=en}RTF}}
- is a proprietary document file format.
-
- <<References>>:
-
- *
{{{http://www.microsoft.com/downloads/info.aspx?na=46&p=1&SrcDisplayLang=en&SrcCategoryId=&SrcFamilyId=dd422b8d-ff06-4207-b476-6b5396a18a2b&u=http%3a%2f%2fdownload.microsoft.com%2fdownload%2f2%2ff%2f5%2f2f599e18-07ee-4ec5-a1e7-f4e6a9423592%2fWord2007RTFSpec9.doc&oRef=http%3a%2f%2fmsdn2.microsoft.com%2fen-us%2foffice%2faa905482.aspx}Microsoft
Office Word 2007 Rich Text Format (RTF) Specification}}
-
- * {{{http://search.cpan.org/~sburke/RTF-Writer/lib/RTF/Cookbook.pod}RTF
Cookbook}}
-
- []
-
-* {TWiki}
-
- {{{https://twiki.org/}TWiki}} is a structured wiki.
-
- <<References>>:
-
- * {{{https://twiki.org/cgi-bin/view/TWiki04x01/TextFormattingRules} TWiki
Text Formatting}}
-
- []
-
-* {XDoc}
-
- XDoc is a generic format for document into a styled HTML document.
-
- <<References>>:
-
- * {{{../references/xdoc-format.html}XDoc Reference}}
-
- []
-
-* {XHTML}
-
- {{{https://www.w3.org/MarkUp/}XHTML}} is a markup language with the same
expressions as HTML, but also
- conforms to XML syntax.
-
- <<References>>:
-
- * {{{http://www.iangraham.org/books/xhtml1/extras/html-7nov2000.pdf}HTML and
XHTML Quick Reference Charts: Head and Body Markup}}
-
- * {{{https://www.w3.org/TR/xhtml1/}XHTML 1.0 Specification}}
-
- []
+- [HTML and XHTML Quick Reference Charts: Head and Body
Markup](http://www.iangraham.org/books/xhtml1/extras/html-7nov2000.pdf)
+- [XHTML 1\.0 Specification](https://www.w3.org/TR/xhtml1/)
diff --git a/content/markdown/references/apt-format.md
b/content/markdown/references/apt-format.md
index 521321c..a253ab3 100644
--- a/content/markdown/references/apt-format.md
+++ b/content/markdown/references/apt-format.md
@@ -1,103 +1,78 @@
- -----
- The APT format
- -----
- Jason van Zyl
- -----
- 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
-
-The APT format
-~~~~~~~~~~~~~~
-
- APT stands for "Almost Plain Text". APT is a markup language that takes the
- hassle out of documentation writing by striving for simplicity. Its syntax
- resembles plain-text more than it resembles most other markup formats
- (such as HTML).
-
- This document provides some examples of available APT formatting.
-
-* Important Notice
-
- The information contained in this document corresponds to the original
- APT format as published by {{{http://www.xmlmind.com/}Xmlmind}}.
- In version 1.1 Maven Doxia has applied several modifications to this original
- format, see this separate {{{./doxia-apt.html}document}}
- for a detailed description. Notable differences are highlighted below
- with a {{{./doxia-apt.html}\[Change\]}} link.
-
- The following sections contain formatted text that demonstrates the use
- of APT to create paragraphs, headers, sections, lists, code samples,
- figures, tables, rules, breaks, and text level elements such as font styles,
- anchors, and special characters.
- Boxes containing text in typewriter-like font are examples of APT source.
-
-* {Document structure}
-~~~~~~~~~~~~~~~~~~~~~~
-
- A short APT document is contained in a single text file. A longer document
- may be contained in a ordered list of text files. For instance, first text
- file contains section 1, second text file contains section 2, and so on.
-
- [Note:] Splitting the APT document in several text files on a section
- boundary is not mandatory. The split may occur anywhere.
- However doing so is recommended because a text file containing a
- section is by itself a valid APT document.
-
- A file contains a sequence of paragraphs and ``displays'' (non paragraphs
- such as tables) separated by open lines.
-
- A paragraph is simply a sequence of consecutive text lines.
-
-+------------------------------------------------------------------------+
+---
+title: The APT format
+author:
+ - Jason van Zyl
+date: 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.-->
+
+# The APT format
+
+<!--~~~~~~~~~~~~-->
+
+APT stands for "Almost Plain Text"\. APT is a markup language that
takes the hassle out of documentation writing by striving for simplicity\. Its
syntax resembles plain\-text more than it resembles most other markup formats
\(such as HTML\)\.
+
+This document provides some examples of available APT formatting\.
+
+## Important Notice
+
+The information contained in this document corresponds to the original APT
format as published by [Xmlmind](http://www.xmlmind.com/)\. In version 1\.1
Maven Doxia has applied several modifications to this original format, see this
separate [document](./doxia-apt.html) for a detailed description\. Notable
differences are highlighted below with a [\[Change\]](./doxia-apt.html) link\.
+
+The following sections contain formatted text that demonstrates the use of APT
to create paragraphs, headers, sections, lists, code samples, figures, tables,
rules, breaks, and text level elements such as font styles, anchors, and
special characters\. Boxes containing text in typewriter\-like font are
examples of APT source\.
+
+## <a id="Document_structure"></a>Document structure
+
+<!--~~~~~~~~~~~~~~~~~~~~-->
+
+A short APT document is contained in a single text file\. A longer document
may be contained in a ordered list of text files\. For instance, first text
file contains section 1, second text file contains section 2, and so on\.
+
+<dl>
+<dt>Note:</dt>
+<dd>Splitting the APT document in several text files on a section boundary is
not mandatory. The split may occur anywhere. However doing so is recommended
because a text file containing a section is by itself a valid APT document.</dd>
+</dl>
+
+A file contains a sequence of paragraphs and \`\`displays'' \(non
paragraphs such as tables\) separated by open lines\.
+
+A paragraph is simply a sequence of consecutive text lines\.
+
+```unknown
First line of first paragraph.
Second line of first paragraph.
Third line of first paragraph.
Line 1 of paragraph 2 (separated from first paragraph by an open line).
Line 2 of paragraph 2.
-+------------------------------------------------------------------------+
+```
- The indentation of the first line of a paragraph is the main method used by
- an APT processor to recognize the type of the paragraph. For example, a
- section title must not be indented at all.
+The indentation of the first line of a paragraph is the main method used by an
APT processor to recognize the type of the paragraph\. For example, a section
title must not be indented at all\.
- A ``plain'' paragraph must be indented by a certain amount of space. For
- example, a plain paragraph which is not contained in a list may be indented
- by two spaces.
+A \`\`plain'' paragraph must be indented by a certain amount of
space\. For example, a plain paragraph which is not contained in a list may be
indented by two spaces\.
-+-------------------------------------------------+
+```unknown
My section title (not indented).
My paragraph first line (indented by 2 spaces).
-+-------------------------------------------------+
+```
- Indentation is not rigid. Any amount of space will do. You don't even need
- to use a consistent indentation all over your document. What really matters
- for an APT processor is whether the paragraph is not indented at all or,
- when inside a list, whether a paragraph is more or less indented than the
- first item of the list (more about this later).
+Indentation is not rigid\. Any amount of space will do\. You don't even
need to use a consistent indentation all over your document\. What really
matters for an APT processor is whether the paragraph is not indented at all
or, when inside a list, whether a paragraph is more or less indented than the
first item of the list \(more about this later\)\.
-+-------------------------------------------------------+
+```unknown
First paragraph has its first line indented by four
spaces. Then the author did not even bother to indent the
other lines of the paragraph.
@@ -105,90 +80,81 @@ other lines of the paragraph.
Second paragraph contains several lines which are all
indented by two spaces. This style is much nicer than
the one used for the previous paragraph.
-+-------------------------------------------------------+
+```
+
+Note that tabs are expanded with a tab width set to 8\.
- Note that tabs are expanded with a tab width set to 8.
+## Document elements
-* Document elements
-~~~~~~~~~~~~~~~~~~~
+<!--~~~~~~~~~~~~~~~~~-->
+### Block level elements
-** Block level elements
-~~~~~~~~~~~~~~~~~~~~~~~
+<!--~~~~~~~~~~~~~~~~~~~~~-->
+#### Title
-*** Title
-~~~~~~~~~~
+<!--~~~~~~~~-->
- A title is optional. If used, it must appear as the first block of the
- document.
+A title is optional\. If used, it must appear as the first block of the
document\.
-+----------------------------------------------------------------------------+
+```unknown
------
Title
------
Author
------
Date
-+----------------------------------------------------------------------------+
+```
- A title block is indented (centering it is nicer). It begins with a line
- containing at least 3 dashes (<<<--->>>).
+A title block is indented \(centering it is nicer\)\. It begins with a line
containing at least 3 dashes \(`---`\)\.
- After the first <<<--->>> line, one or several consecutive lines of text
- (implicit line break after each line) specify the title of the document.
+After the first `---` line, one or several consecutive lines of text
\(implicit line break after each line\) specify the title of the document\.
- This text may immediately be followed by another <<<--->>> line and one or
- several consecutive lines of text which specifies the author(s) of the
- document. Each line represents an individual author.
+This text may immediately be followed by another `---` line and one or several
consecutive lines of text which specifies the author\(s\) of the document\.
Each line represents an individual author\.
- The author sub-block may optionally be followed by a date sub-block using the
- same syntax.
+The author sub\-block may optionally be followed by a date sub\-block using
the same syntax\.
- The following example is used for a document with an title and a date but
- with no declared author.
+The following example is used for a document with an title and a date but with
no declared author\.
-+----------------------------------------------------------------------------+
+```unknown
------
Title
------
------
Date
------
-+----------------------------------------------------------------------------+
+```
- The last line is ignored. It is just there to make the block nicer.
+The last line is ignored\. It is just there to make the block nicer\.
- <<Note>>: the date has no specific format and will be parsed as string. But
we recommend to use the ISO-8601 standard,
- since formatting a date varies around the world:
+**Note**: the date has no specific format and will be parsed as string\. But
we recommend to use the ISO\-8601 standard, since formatting a date varies
around the world:
- <<YYYY-MM-DD>>
+**YYYY\-MM\-DD**
- where <<YYYY>> is the year in the Gregorian calendar, <<MM>> is the month of
- the year between 01 (January) and 12 (December), and <<DD>> is the day of the
- month between 01 and 31.
+where **YYYY** is the year in the Gregorian calendar, **MM** is the month of
the year between 01 \(January\) and 12 \(December\), and **DD** is the day of
the month between 01 and 31\.
-*** Paragraph
-~~~~~~~~~~~~~
+#### Paragraph
- Paragraphs other than the title block may appear before the first section.
+<!--~~~~~~~~~~~-->
-+----------------------+
+Paragraphs other than the title block may appear before the first section\.
+
+```unknown
Paragraph 1, line 1.
Paragraph 1, line 2.
Paragraph 2, line 1.
Paragraph 2, line 2.
-+----------------------+
+```
+
+Paragraphs are indented\. They have already been described in the [Document
structure](#Document_structure) section\.
- Paragraphs are indented. They have already been described in the
- {{{Document_structure}Document structure}} section.
+#### Section
-*** Section
-~~~~~~~~~~~
+<!--~~~~~~~~~-->
- Sections are created by inserting section titles into the document. Simple
- documents need not contain sections.
+Sections are created by inserting section titles into the document\. Simple
documents need not contain sections\.
-+-----------------------------------+
+```unknown
Section title
* Sub-section title
@@ -198,16 +164,15 @@ Section title
*** Sub-sub-sub-section title
**** Sub-sub-sub-sub-section title
-+-----------------------------------+
+```
+
+Section titles are not indented\. A sub\-section title begins with one
asterisk \(`*`\), a sub\-sub\-section title begins with two asterisks \(`**`\),
and so forth up to four sub\-section levels\.
- Section titles are not indented. A sub-section title begins with one
- asterisk (<<<*>>>), a sub-sub-section title begins with two asterisks
- (<<<**>>>), and so forth up to four sub-section levels.
+#### List
-*** List
-~~~~~~~~
+<!--~~~~~~-->
-+---------------------------------------+
+```unknown
* List item 1.
* List item 2.
@@ -219,22 +184,17 @@ Section title
* Sub-list item 2.
* List item 3.
-+---------------------------------------+
+```
- List items are indented and begin with a asterisk (<<<*>>>).
+List items are indented and begin with a asterisk \(`*`\)\.
- Plain paragraphs more indented than the first list item are nested in that
- list. Displays such as tables (not indented) are always nested in the
- current list.
+Plain paragraphs more indented than the first list item are nested in that
list\. Displays such as tables \(not indented\) are always nested in the
current list\.
- To nest a list inside a list, indent its first item more than its parent
- list. To end a list, add a paragraph or list item less indented than the
- current list.
+To nest a list inside a list, indent its first item more than its parent
list\. To end a list, add a paragraph or list item less indented than the
current list\.
- Section titles always end a list. Displays cannot end a list but the
- <<<[]>>> pseudo-element may be used to force the end of a list.
+Section titles always end a list\. Displays cannot end a list but the `[]`
pseudo\-element may be used to force the end of a list\.
-+------------------------------------+
+```unknown
* List item 3.
Force end of list:
@@ -243,16 +203,13 @@ Section title
--------------------------------------------
Verbatim text not contained in list item 3
--------------------------------------------
-+------------------------------------+
+```
- In the previous example, without the <<<[]>>>, the verbatim text (not
- indented as all displays) would have been contained in list item 3.
+In the previous example, without the `[]`, the verbatim text \(not indented as
all displays\) would have been contained in list item 3\.
- A single <<<[]>>> may be used to end several nested lists at the same
- time. The indentation of <<<[]>>> may be used to specify exactly which
- lists should be ended. Example:
+A single `[]` may be used to end several nested lists at the same time\. The
indentation of `[]` may be used to specify exactly which lists should be
ended\. Example:
-+------------------------------------+
+```unknown
* List item 1.
* List item 2.
@@ -266,12 +223,11 @@ Verbatim text not contained in list item 3
-------------------------------------------------------------------
Verbatim text contained in list item 2, but not in sub-list item 2
-------------------------------------------------------------------
-+------------------------------------+
+```
- There are three kind of lists, the bulleted lists we have already described,
- the numbered lists and the definition lists.
+There are three kind of lists, the bulleted lists we have already described,
the numbered lists and the definition lists\.
-+-----------------------------------------+
+```unknown
[[1]] Numbered item 1.
[[A]] Numbered item A.
@@ -279,104 +235,81 @@ Verbatim text contained in list item 2, but not in
sub-list item 2
[[B]] Numbered item B.
[[2]] Numbered item 2.
-+-----------------------------------------+
-
- A numbered list item begins with a label between two square brackets. The
- label of the first item establishes the numbering scheme for the whole list:
-
- [<<<[[1\]\]>>>] Decimal numbering: 1, 2, 3, 4, etc.
-
- [<<<[[a\]\]>>>] Lower-alpha numbering: a, b, c, d, etc.
-
- [<<<[[A\]\]>>>] Upper-alpha numbering: A, B, C, D, etc.
-
- [<<<[[i\]\]>>>] Lower-roman numbering: i, ii, iii, iv, etc.
-
- [<<<[[I\]\]>>>] Upper-roman numbering: I, II, III, IV, etc.
-
- The labels of the items other than the first one are ignored. It is
- recommended to take the time to type the correct label for each item in
- order to keep the APT source document readable.
-
-+-------------------------------------------+
+```
+
+A numbered list item begins with a label between two square brackets\. The
label of the first item establishes the numbering scheme for the whole list:
+
+<dl>
+<dt><code>[[1]]</code></dt>
+<dd>Decimal numbering: 1, 2, 3, 4, etc.</dd>
+<dt><code>[[a]]</code></dt>
+<dd>Lower-alpha numbering: a, b, c, d, etc.</dd>
+<dt><code>[[A]]</code></dt>
+<dd>Upper-alpha numbering: A, B, C, D, etc.</dd>
+<dt><code>[[i]]</code></dt>
+<dd>Lower-roman numbering: i, ii, iii, iv, etc.</dd>
+<dt><code>[[I]]</code></dt>
+<dd>Upper-roman numbering: I, II, III, IV, etc.</dd>
+</dl>
+
+The labels of the items other than the first one are ignored\. It is
recommended to take the time to type the correct label for each item in order
to keep the APT source document readable\.
+
+```unknown
[Defined term 1] of definition list 2.
[Defined term 2] of definition list 2.
-+-------------------------------------------+
+```
+
+A definition list item begins with a defined term: text between square
brackets\.
- A definition list item begins with a defined term: text between square
- brackets.
+#### Verbatim text
-*** Verbatim text
-~~~~~~~~~~~~~~~~~
+<!--~~~~~~~~~~~~~~~-->
-+----------------------------------------+
+```unknown
----------------------------------------
Verbatim
text,
preformatted,
escaped.
----------------------------------------
-+----------------------------------------+
+```
- A verbatim block is not indented. It begins with a non indented line
- containing at least 3 dashes (<<<--->>>). It ends with a similar line.
+A verbatim block is not indented\. It begins with a non indented line
containing at least 3 dashes \(`---`\)\. It ends with a similar line\.
- <<<+-->>> instead of <<<--->>> draws a box around verbatim text.
+`+--` instead of `---` draws a box around verbatim text\.
- Like in HTML, verbatim text is preformatted. Unlike HTML, verbatim text is
- escaped: inside a verbatim display, markup is not interpreted by the APT
- processor.
+Like in HTML, verbatim text is preformatted\. Unlike HTML, verbatim text is
escaped: inside a verbatim display, markup is not interpreted by the APT
processor\.
-*** Figure
-~~~~~~~~~~
+#### Figure
-+---------------------------+
-[Figure name] Figure caption
-+---------------------------+
+<!--~~~~~~~~-->
- A figure block is not indented. It begins with the figure name between
- square brackets. The figure name is optionally followed by some text: the
- figure caption.
-
- The figure name is the pathname of the file containing the figure but
- without an extension. Example: if your figure is contained in
- <<</home/joe/docs/mylogo.jpeg>>>, the figure name is
- <<</home/joe/docs/mylogo>>>.
{{{./doxia-apt.html#Figure_extensions}\[Change\]}}
+```unknown
+[Figure name] Figure caption
+```
- If the figure name comes from a relative pathname (recommended practice)
- rather than from an absolute pathname, this relative pathname is taken to be
- relative to the directory of the current APT document (a la HTML)
- rather than relative to the current working directory.
+A figure block is not indented\. It begins with the figure name between square
brackets\. The figure name is optionally followed by some text: the figure
caption\.
- Why not leave the file extension in the figure name? This is better
- explained by an example. You need to convert an APT document to PostScript
- and your figure name is <<</home/joe/docs/mylogo>>>. An APT processor will
- first try to load <<</home/joe/docs/mylogo.eps>>>. When the desired format
- is not found, a APT processor tries to convert one of the existing
- formats. In our example, the APT processor tries to convert
- <<</home/joe/docs/mylogo.jpeg>>> to encapsulated PostScript.
+The figure name is the pathname of the file containing the figure but without
an extension\. Example: if your figure is contained in
`/home/joe/docs/mylogo.jpeg`, the figure name is `/home/joe/docs/mylogo`\.
[\[Change\]](./doxia-apt.html#Figure_extensions)
-*** Table
-~~~~~~~~~
+If the figure name comes from a relative pathname \(recommended practice\)
rather than from an absolute pathname, this relative pathname is taken to be
relative to the directory of the current APT document \(a la HTML\) rather than
relative to the current working directory\.
- A table block is not indented. It begins with a non indented line containing
- an asterisk and at least 2 dashes (<<<*-->>>). It ends with a
- similar line.
+Why not leave the file extension in the figure name? This is better explained
by an example\. You need to convert an APT document to PostScript and your
figure name is `/home/joe/docs/mylogo`\. An APT processor will first try to
load `/home/joe/docs/mylogo.eps`\. When the desired format is not found, a APT
processor tries to convert one of the existing formats\. In our example, the
APT processor tries to convert `/home/joe/docs/mylogo.jpeg` to encapsulated
PostScript\.
- The first line is not only used to recognize a table but also to specify
- column justification. In the following example,
+#### Table
- * the second asterisk (<<<*>>>) is used to specify that column 1 is
- centered,
+<!--~~~~~~~-->
- * the plus sign (<<<+>>>) specifies that column 2 is left aligned,
+A table block is not indented\. It begins with a non indented line containing
an asterisk and at least 2 dashes \(`*--`\)\. It ends with a similar line\.
- * the colon (<<<:>>>) specifies that column 3 is right aligned.
+The first line is not only used to recognize a table but also to specify
column justification\. In the following example,
- []
+- the second asterisk \(`*`\) is used to specify that column 1 is centered,
+- the plus sign \(`+`\) specifies that column 2 is left aligned,
+- the colon \(`:`\) specifies that column 3 is right aligned\.
-+---------------------------------------------+
+```unknown
*----------*--------------+----------------:
| Centered | Left-aligned | Right-aligned |
| cell 1,1 | cell 1,2 | cell 1,3 |
@@ -384,165 +317,143 @@ Verbatim
| cell 2,1 | cell 2,2 | cell 2,3 |
*----------*--------------+----------------:
Table caption
-+---------------------------------------------+
+```
- Rows are separated by a non indented line beginning with <<<*-->>>.
+Rows are separated by a non indented line beginning with `*--`\.
- An optional table caption (non indented text) may immediately follow the
- table.
+An optional table caption \(non indented text\) may immediately follow the
table\.
- Rows may contain single line or multiple line cells. Each line of cell text
- is separated from the adjacent cell by the pipe character (<<<|>>>).
- (<<<|>>> may be used in the cell text if quoted: <<<\\|>>>.)
+Rows may contain single line or multiple line cells\. Each line of cell text
is separated from the adjacent cell by the pipe character \(`|`\)\. \(`|` may
be used in the cell text if quoted: `\|`\.\)
- The last <<<|>>> is only used to make the table nicer. The first <<<|>>> is
- not only used to make the table nicer, but also to specify that a grid is to
- be drawn around table cells.
+The last `|` is only used to make the table nicer\. The first `|` is not only
used to make the table nicer, but also to specify that a grid is to be drawn
around table cells\.
- The following example shows a simple table with no grid and no caption.
+The following example shows a simple table with no grid and no caption\.
-+---------------+
+```unknown
*-----*------*
cell | cell
*-----*------*
cell | cell
*-----*------*
-+---------------+
+```
+
+#### Horizontal rule
-*** Horizontal rule
-~~~~~~~~~~~~~~~~~~~
+<!--~~~~~~~~~~~~~~~~~-->
-+---------------------+
+```unknown
=====================
-+---------------------+
+```
+
+A non indented line containing at least 3 equal signs \(`===`\)\.
- A non indented line containing at least 3 equal signs (<<<===>>>).
+#### Page break
-*** Page break
-~~~~~~~~~~~~~~
+<!--~~~~~~~~~~~~-->
-+---+
+```unknown
^L
-+---+
+```
- A non indented line containing a single form feed character (Control-L).
+A non indented line containing a single form feed character \(Control\-L\)\.
-** Text level elements
-~~~~~~~~~~~~~~~~~~~~~~
+### Text level elements
-*** Font
-~~~~~~~~
+<!--~~~~~~~~~~~~~~~~~~~~-->
+#### Font
-+-----------------------------------------------------+
+<!--~~~~~~-->
+
+```unknown
<Italic> font. <<Bold>> font. <<<Monospaced>>> font.
-+-----------------------------------------------------+
+```
+
+Text between < and > must be rendered in italic\. Text between <<
and >> must be rendered in bold\. Text between <<< and
>>> must be rendered using a monospaced, typewriter\-like font\.
- Text between \< and > must be rendered in italic. Text between \<\< and >>
- must be rendered in bold. Text between \<\<\< and >>> must be rendered using
- a monospaced, typewriter-like font.
+Font elements may appear anywhere except inside other font elements\.
- Font elements may appear anywhere except inside other font elements.
+It is not recommended to use font elements inside titles, section titles,
links and defined terms because an APT processor automatically applies
appropriate font styles to these elements\.
- It is not recommended to use font elements inside titles, section titles,
- links and defined terms because an APT processor automatically applies
- appropriate font styles to these elements.
+#### Anchor and link
-*** Anchor and link
-~~~~~~~~~~~~~~~~~~~
+<!--~~~~~~~~~~~~~~~~~-->
-+-----------------------------------------------------------------+
+```unknown
{Anchor}. Link to {{anchor}}. Link to {{http://www.pixware.fr}}.
Link to {{{anchor}showing alternate text}}.
Link to {{{http://www.pixware.fr}Pixware home page}}.
-+-----------------------------------------------------------------+
+```
- Text between curly braces (<<<\{}>>>) specifies an anchor. Text between
- double curly braces (<<<\{\{}}>>>) specifies a link.
+Text between curly braces \(`{}`\) specifies an anchor\. Text between double
curly braces \(`{{}}`\) specifies a link\.
- It is an error to create a link element that does not refer to an anchor of
- the same name. The name of an anchor/link is its text with all non
- alphanumeric characters stripped.
{{{./doxia-apt.html#Anchor_construction}\[Change\]}}
+It is an error to create a link element that does not refer to an anchor of
the same name\. The name of an anchor/link is its text with all non
alphanumeric characters stripped\.
[\[Change\]](./doxia-apt.html#Anchor_construction)
- This rule does not apply to links to <external> anchors. Text beginning
- with <<<http:/>>>, <<<https:/>>>, <<<ftp:/>>>, <<<file:/>>>, <<<mailto:>>>,
- <<<../>>>, <<<./>>> (<<<..\\>>> and <<<.\\>>> on Windows) is recognized as
- an external anchor name.
+This rule does not apply to links to _external_ anchors\. Text beginning with
`http:/`, `https:/`, `ftp:/`, `file:/`, `mailto:`, `../`, `./` \(`..\` and `.\`
on Windows\) is recognized as an external anchor name\.
- When the construct <<\{\{\{>><name><<}>><text><<}}>> is used, the link text
- <text> may differ from the link name <name>.
+When the construct **\{\{\{**_name_**\}**_text_**\}\}** is used, the link text
_text_ may differ from the link name _name_\.
- Anchor/link elements may appear anywhere except inside other anchor/link
- elements.
+Anchor/link elements may appear anywhere except inside other anchor/link
elements\.
- Section titles are implicitly defined anchors.
- {{{./doxia-apt.html#Anchors_for_section_titles}\[Change\]}}
+Section titles are implicitly defined anchors\.
[\[Change\]](./doxia-apt.html#Anchors_for_section_titles)
-*** Line break
-~~~~~~~~~~~~~~
+#### Line break
-+-------------+
+<!--~~~~~~~~~~~~-->
+
+```unknown
Force line\
break.
-+-------------+
+```
+
+A backslash character \(`\`\) followed by a newline character\.
- A backslash character (<<<\\>>>) followed by a newline character.
+Line breaks must not be used inside titles and tables \(which are line
oriented blocks with implicit line breaks\)\.
- Line breaks must not be used inside titles and tables (which are line
- oriented blocks with implicit line breaks).
+#### Non breaking space
-*** Non breaking space
-~~~~~~~~~~~~~~~~~~~~~~
+<!--~~~~~~~~~~~~~~~~~~~~-->
-+----------------------+
+```unknown
Non\ breaking\ space.
-+----------------------+
+```
+
+A backslash character \(`\`\) followed by a space character\.
- A backslash character (<<<\\>>>) followed by a space character.
+#### Special character
-*** Special character
-~~~~~~~~~~~~~~~~~~~~~
+<!--~~~~~~~~~~~~~~~~~~~-->
-+---------------------------------------------------------------------------+
+```unknown
Escaped special characters: \~, \=, \-, \+, \*, \[, \], \<, \>, \{, \}, \\.
-+---------------------------------------------------------------------------+
+```
- In certain contexts, these characters have a special meaning and therefore
- must be escaped if needed as is. They are escaped by adding a backslash in
- front of them. The backslash may itself be escaped by adding another
- backslash in front of it.
+In certain contexts, these characters have a special meaning and therefore
must be escaped if needed as is\. They are escaped by adding a backslash in
front of them\. The backslash may itself be escaped by adding another backslash
in front of it\.
- Note that an asterisk, for example, needs to be escaped only if its begins a
- paragraph. (<<<*>>> has no special meaning in the middle of a paragraph.)
+Note that an asterisk, for example, needs to be escaped only if its begins a
paragraph\. \(`*` has no special meaning in the middle of a paragraph\.\)
-+--------------------------------------+
+```unknown
Copyright symbol: \251, \xA9, \u00a9.
-+--------------------------------------+
+```
- Latin-1 characters (whatever is the encoding of the APT document) may be
- specified by their codes using a backslash followed by one to three octal
- digits or by using the <<<\x>>><NN> notation, where <NN> are two hexadecimal
- digits.
+Latin\-1 characters \(whatever is the encoding of the APT document\) may be
specified by their codes using a backslash followed by one to three octal
digits or by using the `\x`_NN_ notation, where _NN_ are two hexadecimal
digits\.
- Unicode characters may be specified by their codes using the <<<\u>>><NNNN>
- notation, where <NNNN> are four hexadecimal digits.
+Unicode characters may be specified by their codes using the `\u`_NNNN_
notation, where _NNNN_ are four hexadecimal digits\.
-*** Comment
-~~~~~~~~~~~
+#### Comment
-+---------------+
+<!--~~~~~~~~~-->
+
+```unknown
~~Commented out.
-+---------------+
+```
- Text found after two tildes (<<<\~~>>>) is ignored up to the end of line.
+Text found after two tildes \(`~~`\) is ignored up to the end of line\.
- A line of <<<~>>> is often used to ``underline'' section titles in order to
- make them stand out of other paragraphs.
+A line of `~` is often used to \`\`underline'' section titles in
order to make them stand out of other paragraphs\.
-
-* The APT format at a glance
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+<!--~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-------------------------------------------------------------------------------
+```
------
Title
------
@@ -647,6 +558,5 @@ Table caption
Copyright symbol: \251, \xA9, \u00a9.
~~Commented out.
-
-------------------------------------------------------------------------------
+```
diff --git a/content/markdown/references/doxia-apt.md
b/content/markdown/references/doxia-apt.md
index 171241d..124607a 100644
--- a/content/markdown/references/doxia-apt.md
+++ b/content/markdown/references/doxia-apt.md
@@ -1,214 +1,179 @@
- -----
- Doxia APT Enhancements
- -----
- Lukas Theussl
- Robert Scholte
- -----
- 2013-04-06
- ------
-
-~~ 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
-
-Enhancements to the APT format
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- In the following we provide a list of differences/enhancements to the
- original {{{./apt-format.html}APT}} format that were incorporated in Doxia.
- Apart from some exceptions, these differences are usually
- 'backwards-compatible'. That is, any document that gets correctly processed
- by Aptconvert should also
- be a valid Doxia input file and lead to identical results when processed
- by a Doxia parser.
-
-%{toc|section=1|fromDepth=2|toDepth=2}
-
-* {Paragraphs in list items}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- Contrary to the original APT parser, the Doxia APT parser does not
- put list items within paragraphs. Eg, the example given in the APT guide:
-
-+---------------------------------------------------------------------------+
+---
+title: Doxia APT Enhancements
+author:
+ - Lukas Theussl
+ - Robert Scholte
+date: 2013-04-06
+---
+
+<!-- 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.-->
+
+# Enhancements to the APT format
+
+<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
+
+In the following we provide a list of differences/enhancements to the original
[APT](./apt-format.html) format that were incorporated in Doxia\. Apart from
some exceptions, these differences are usually
'backwards\-compatible'\. That is, any document that gets correctly
processed by Aptconvert should also be a valid Doxia input file and lead to
identical results when processed by a Doxia parser\.
+
+<!-- MACRO{toc|section=1|fromDepth=2|toDepth=2} -->
+## <a id="Paragraphs_in_list_items"></a>Paragraphs in list items
+
+<!--~~~~~~~~~~~~~~~~~~~~~~~~~~-->
+
+Contrary to the original APT parser, the Doxia APT parser does not put list
items within paragraphs\. Eg, the example given in the APT guide:
+
+```unknown
* List item 1.
-+---------------------------------------------------------------------------+
+```
- will, for instance, produce the following html:
+will, for instance, produce the following html:
-+---------------------------------------------------------------------------+
+```unknown
<li>List item 1.</li>
-+---------------------------------------------------------------------------+
+```
- To get the same result as aptconvert, use
+To get the same result as aptconvert, use
-+---------------------------------------------------------------------------+
+```unknown
*
List item 1.
-+---------------------------------------------------------------------------+
+```
- which will produce:
+which will produce:
-+---------------------------------------------------------------------------+
+```unknown
<li><p>List item 1.</p></li>
-+---------------------------------------------------------------------------+
+```
+## <a id="Table_header_cells"></a>Table header cells
-* {Table header cells}
-~~~~~~~~~~~~~~~~~~~~~~
+<!--~~~~~~~~~~~~~~~~~~~~-->
- Header cells are defined by an additional pipe character '|' at the beginning
- of the cell:
+Header cells are defined by an additional pipe character '|' at the
beginning of the cell:
-+---------------------------------------------------------------------------+
+```unknown
*-----------+-----------+
|| Header 1 || Header 2 |
*-----------+-----------+
| Cell 1 | Cell 2 |
*-----------+-----------+
-+---------------------------------------------------------------------------+
+```
- produces:
+produces:
-*-----------+-----------+
-|| Header 1 || Header 2 |
-*-----------+-----------+
-| Cell 1 | Cell 2 |
-*-----------+-----------+
+|Header 1|Header 2|
+|:---|:---|
+|Cell 1|Cell 2|
+## <a id="Multi-lines_cells_in_table"></a>Multi\-lines cells in table
-* {Multi-lines cells in table}
-~~~~~~~~~~~~~~~~~~~~~~
+<!--~~~~~~~~~~~~~~~~~~~~-->
- Since 1.1, multi-lines cells are recognized with the character '\' at the end
- of the cells:
+Since 1\.1, multi\-lines cells are recognized with the character
'\\' at the end of the cells:
-+---------------------------------------------------------------------------+
+```unknown
*-----------+-----------+
|| Header 1 || Header 2 |
*-----------+-----------+
| Cell\ | Cell 2 |
| 1 | |
*-----------+-----------+
-+---------------------------------------------------------------------------+
+```
- produces:
+produces:
-*-----------+-----------+
-|| Header 1 || Header 2 |
-*-----------+-----------+
-| Cell\ | Cell 2 |
-| 1 | |
-*-----------+-----------+
+|Header 1|Header 2|
+|:---|:---|
+|Cell�
+1|Cell 2|
+## <a id="Anchors"></a>Anchors
-* {Anchors}
-~~~~~~~~~~~~~~~~~~~~~
+<!--~~~~~~~~~~~~~~~~~~~-->
+### <a id="Anchors_for_section_titles"></a>Anchors for section titles
-** {Anchors for section titles}
+Contrary to the original APT format, section titles are **not** implicitly
defined anchors\. If you want an anchor for a section title you need to define
it explicitly as such:
- Contrary to the original APT format, section titles are <<not>> implicitly
- defined anchors. If you want an anchor for a section title you need to
- define it explicitly as such:
-
-+---------------------------------------------------------------------------+
+```unknown
* {Anchors for section titles}
-+---------------------------------------------------------------------------+
-
-** {Anchor construction}
+```
- Contrary to the original APT format, an anchor/link is <<not>> its text with
- all non alphanumeric characters stripped. Ideally, an anchor should be a
valid
- Doxia id, ie it must begin with a letter (\[A\-Za\-z\]) and may be
- followed by any number of letters, digits (\[0\-9\]), hyphens ("\-"),
- underscores ("_"), colons (":"), and periods ("."). Any anchor that does not
- satisfy this pattern is transformed according to the following rules:
+### <a id="Anchor_construction"></a>Anchor construction
- * Any whitespace at the start and end is removed
+Contrary to the original APT format, an anchor/link is **not** its text with
all non alphanumeric characters stripped\. Ideally, an anchor should be a valid
Doxia id, ie it must begin with a letter \(\[A\-Za\-z\]\) and may be followed
by any number of letters, digits \(\[0\-9\]\), hyphens \("\-"\),
underscores \("\_"\), colons \(":"\), and periods
\("\."\)\. Any anchor that does not satisfy this pattern is
transformed according to the following rules:
- * If the first character is not a letter, prepend the letter 'a'
+- Any whitespace at the start and end is removed
+- If the first character is not a letter, prepend the letter 'a'
+- Any spaces are replaced with an underscore '\_'
+- Any characters not matching the above pattern are stripped\.
- * Any spaces are replaced with an underscore '_'
+Note in particular that case is preserved in this conversation and that APT
anchors and links are case\-sensitive\. So the anchor for the section title in
the previous example would be `Anchors_for_section_titles`\.
- * Any characters not matching the above pattern are stripped.
+## <a id="Links"></a>Links
- Note in particular that case is preserved in this conversation and that APT
- anchors and links are case-sensitive. So the anchor for the section
- title in the previous example would be <<<Anchors_for_section_titles>>>.
+<!--~~~~~~~~~~~~~~~~~~~-->
-* {Links}
-~~~~~~~~~~~~~~~~~~~~~
+In **Doxia\-1\.1** the notion of a '_local_' link was introduced in
addition to _internal_ links and _external_ links\.
- In <<Doxia-1.1>> the notion of a '<local>' link was introduced in addition to
- <internal> links and <external> links.
+- An **internal** link is a link to an anchor within the same source document\.
- * An <<internal>> link is a link to an anchor within the same source
document.
+ In the APT format used by **Doxia\-1\.1**, internal links have to be valid
Doxia ids, as specified in the anchors section above\.
- In the APT format used by <<Doxia-1.1>>, internal links have to be valid
- Doxia ids, as specified in the anchors section above.
+ Note in particular that internal links in APT do **not** start with
'\#'\.
- Note in particular that internal links in APT do <<not>> start with '#'.
+- A **local** link is a link to another document within the same site\.
- * A <<local>> link is a link to another document within the same site.
+ In the APT format used by **Doxia\-1\.1**, local links **have to** start
with either `./` or `../` to distinguish them from internal links\. E\.g\.,
- In the APT format used by <<Doxia-1.1>>, local links <<have to>> start with
- either <<<./>>> or <<<../>>> to distinguish them from internal links. E.g.,
-
----
- {{{doc/standalone.html}Standalone}}
----
+ ```
+ {{{doc/standalone.html}Standalone}}
+ ```
is not valid, it should be
----
- {{{./doc/standalone.html}Standalone}}
----
+ ```
+ {{{./doc/standalone.html}Standalone}}
+ ```
Note in particular that the following link
----
- {{{standalone.html}Standalone}}
----
+ ```
+ {{{standalone.html}Standalone}}
+ ```
- will be interpreted as an internal link (dots are valid characters in
anchor names).
- Since you most likely meant to
- link to another source document, you should again prepend a "./".
+ will be interpreted as an internal link \(dots are valid characters in
anchor names\)\. Since you most likely meant to link to another source
document, you should again prepend a "\./"\.
- * An <<external>> link is a link that is neither local nor internal.
+- An **external** link is a link that is neither local nor internal\.
- An external link should be a valid
{{{http://www.ietf.org/rfc/rfc2396.txt}URI}}.
-
- []
-
- Anchors are always translated to a valid id, including escaping. In some
situation this can cause issues, especially when referring to a javadoc-link.\
- Since Doxia 1.4 there is support for literal anchors, by using 2 hashed (##)
instead of 1.
- This implies that the writer is responsible for using the right URL encoding!
-
----
+ An external link should be a valid
[URI](http://www.ietf.org/rfc/rfc2396.txt)\.
+
+Anchors are always translated to a valid id, including escaping\. In some
situation this can cause issues, especially when referring to a javadoc\-link\.
+Since Doxia 1\.4 there is support for literal anchors, by using 2 hashed
\(\#\#\) instead of 1\. This implies that the writer is responsible for using
the right URL encoding\!
+
+```
{{{../apidocs/groovyx/net/http/ParserRegistry.html##parseText(org.apache.http.HttpResponse)}ParserRegistry}}
----
+```
-* {Figure extensions}
-~~~~~~~~~~~~~~~~~~~~~
+## <a id="Figure_extensions"></a>Figure extensions
- Contrary to the original APT format, a figure name has to be given fully
- <<with>> extension. For instance:
+<!--~~~~~~~~~~~~~~~~~~~-->
-+---------------------------------------------------------------------------+
+Contrary to the original APT format, a figure name has to be given fully
**with** extension\. For instance:
+
+```unknown
[/home/joe/docs/mylogo.jpeg] Figure caption
-+---------------------------------------------------------------------------+
+```
+
diff --git a/content/markdown/resources.md b/content/markdown/resources.md
index d456567..1c25363 100644
--- a/content/markdown/resources.md
+++ b/content/markdown/resources.md
@@ -1,56 +1,41 @@
- -----
- External Resources
- -----
- 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
-
-External Resources
-
-* Extensions
-
-*-----------+--------------+
-|| Name || Author
-*-----------+--------------+
-| {{{http://doxia-include.sourceforge.net/}Doxia :: Include Macro}} | Juergen
Kellerer
-*-----------+--------------+
-
-* Articles
-
-*-----------+--------------+--------------+
-|| Title || Publisher || Author
-*-----------+--------------+--------------+
-| {{{https://www.linux.com/news/quick-and-dirty-typesetting-apt/}Quick and
dirty typesetting with APT}} | linux.com | Scott Nesbitt
-*-----------+--------------+--------------+
-| {{{http://en.wikipedia.org/wiki/Lightweight_markup_language}Lightweight
markup language}} | wikipedia.org | ?
-*-----------+--------------+--------------+
-
-Related External Projects
-
- * {{{http://www.xwiki.org/}XWiki}} which uses Doxia in its
-
{{{http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-rendering/xwiki-rendering-parsers/xwiki-rendering-parser-doxia/}rendering}}.
-
- * {{{http://wiki.eclipse.org/Mylyn/Incubator/WikiText}Mylyn WikiText}}
(originally known as Textile-J).
-
- []
+---
+title: External Resources
+author:
+ - Vincent Siveton
+date: 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.-->
+
+# External Resources
+
+## Extensions
+
+|Name|Author|
+|:---|:---|
+|[Doxia :: Include Macro](http://doxia-include.sourceforge.net/)|Juergen
Kellerer|
+## Articles
+
+|Title|Publisher|Author|
+|:---|:---|:---|
+|[Quick and dirty typesetting with
APT](https://www.linux.com/news/quick-and-dirty-typesetting-apt/)|linux\.com|Scott
Nesbitt|
+|[Lightweight markup
language](http://en.wikipedia.org/wiki/Lightweight_markup_language)|wikipedia\.org|?|
+# Related External Projects
+
+- [XWiki](http://www.xwiki.org/) which uses Doxia in its
[rendering](http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-rendering/xwiki-rendering-parsers/xwiki-rendering-parser-doxia/)\.
+- [Mylyn WikiText](http://wiki.eclipse.org/Mylyn/Incubator/WikiText)
\(originally known as Textile\-J\)\.
diff --git a/content/site.xml b/content/site.xml
index 276f47c..966d191 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -58,8 +58,7 @@ under the License.
<item name="Doxia Modules Guide" href="modules/index.html"/>
<item name="Doxia Macros Guide" href="macros/index.html"/>
<item name="Writing Books" href="book/index.html"/>
- <!-- MSITE-333: remove double-amp when fixed -->
- <item name="Issues &amp; Gotchas" href="issues/index.html"/>
+ <item name="Issues & Gotchas" href="issues/index.html"/>
<item name="External Resources" href="resources.html"/>
</menu>
