You are viewing a plain text version of this content. The canonical link for it is here.
Posted to doxia-commits@maven.apache.org by lt...@apache.org on 2007/08/21 14:51:02 UTC
svn commit: r568105 - in /maven/doxia/site/src/site: apt/modules/index.apt
apt/references/index.apt site.xml xdoc/ xdoc/references/
xdoc/references/fml-format.xml xdoc/references/xdoc-format.xml
Author: ltheussl
Date: Tue Aug 21 05:51:02 2007
New Revision: 568105
URL: http://svn.apache.org/viewvc?rev=568105&view=rev
Log:
Adding some docs about fml and xdoc formats
Added:
maven/doxia/site/src/site/xdoc/
maven/doxia/site/src/site/xdoc/references/
maven/doxia/site/src/site/xdoc/references/fml-format.xml (with props)
maven/doxia/site/src/site/xdoc/references/xdoc-format.xml (with props)
Modified:
maven/doxia/site/src/site/apt/modules/index.apt
maven/doxia/site/src/site/apt/references/index.apt
maven/doxia/site/src/site/site.xml
Modified: maven/doxia/site/src/site/apt/modules/index.apt
URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/modules/index.apt?rev=568105&r1=568104&r2=568105&view=diff
==============================================================================
--- maven/doxia/site/src/site/apt/modules/index.apt (original)
+++ maven/doxia/site/src/site/apt/modules/index.apt Tue Aug 21 05:51:02 2007
@@ -36,7 +36,7 @@
<<References>>:
- * {{{../references/apt-format.html}Apt Element Reference}}
+ * {{{../references/apt-format.html}Apt Reference}}
[]
@@ -74,7 +74,7 @@
<<References>>:
- * FML Reference
+ * {{{../references/fml-format.html}FML Reference}}
[]
@@ -121,7 +121,7 @@
<<References>>:
- * XDoc Reference
+ * {{{../references/xdoc-format.html}XDoc Reference}}
[]
Modified: maven/doxia/site/src/site/apt/references/index.apt
URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/references/index.apt?rev=568105&r1=568104&r2=568105&view=diff
==============================================================================
--- maven/doxia/site/src/site/apt/references/index.apt (original)
+++ maven/doxia/site/src/site/apt/references/index.apt Tue Aug 21 05:51:02 2007
@@ -32,8 +32,8 @@
* {{{./apt-format.html}APT (Almost Plain Text) Format}}
- * FML (FAQ Markup Language) Format
+ * {{{./fml-format.html} FML (FAQ Markup Language) Format}}
- * Xdoc Format
+ * {{{./xdoc-format.html} Xdoc Format}}
[]
Modified: maven/doxia/site/src/site/site.xml
URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/site.xml?rev=568105&r1=568104&r2=568105&view=diff
==============================================================================
--- maven/doxia/site/src/site/site.xml (original)
+++ maven/doxia/site/src/site/site.xml Tue Aug 21 05:51:02 2007
@@ -63,7 +63,11 @@
</menu>
<menu name="Documentation">
- <item name="References" href="references/index.html"/>
+ <item name="References" href="references/index.html">
+ <item name="Apt Format" href="references/apt-format.html"/>
+ <item name="FML Format" href="references/fml-format.html"/>
+ <item name="Xdoc Format" href="references/xdoc-format.html"/>
+ </item>
<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"/>
Added: maven/doxia/site/src/site/xdoc/references/fml-format.xml
URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/xdoc/references/fml-format.xml?rev=568105&view=auto
==============================================================================
--- maven/doxia/site/src/site/xdoc/references/fml-format.xml (added)
+++ maven/doxia/site/src/site/xdoc/references/fml-format.xml Tue Aug 21 05:51:02 2007
@@ -0,0 +1,100 @@
+<?xml version="1.0"?>
+<!--
+/*
+ * 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.
+ */
+ -->
+<document>
+
+ <properties>
+ <title>The FML (FAQ Markup Language) format</title>
+ <author email="ltheussl_AT_apache_DOT_org">Lukas Theussl</author>
+ </properties>
+
+ <body>
+
+ <section name="The FML format">
+
+ <subsection name="Overview">
+
+ <p>
+ An 'fml' is an XML document conforming to a small and simple set of tags.
+ The format was first used in the <a href="http://maven.apache.org/maven-1.x/">Maven 1</a>,
+ version of the <a href="http://maven.apache.org/maven-1.x/plugins/faq/">FAQ plugin</a>.
+ </p>
+
+ </subsection>
+
+ <subsection name="The FML format">
+
+ <p>
+ The following is a sample FML document:
+ </p>
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+
+<faqs title="Frequently Asked Questions" toplink="false">
+
+ <part id="general">
+ <title>General</title>
+
+ <faq id="whats-foo">
+ <question>
+ What is Foo?
+ </question>
+ <answer>
+ <p>some markup goes here</p>
+
+ <source>some source code</source>
+
+ <p>some markup goes here</p>
+ </answer>
+ </faq>
+
+ <faq id="whats-bar">
+ <question>
+ What is Bar?
+ </question>
+ <answer>
+ <p>some markup goes here</p>
+ </answer>
+ </faq>
+ </part>
+
+ <part id="install">
+
+ <title>Installation</title>
+
+ <faq id="how-install">
+ <question>
+ How do I install Foo?
+ </question>
+ <answer>
+ <p>some markup goes here</p>
+ </answer>
+ </faq>
+
+ </part>
+
+</faqs>
+]]></source>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
Propchange: maven/doxia/site/src/site/xdoc/references/fml-format.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/doxia/site/src/site/xdoc/references/fml-format.xml
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Added: maven/doxia/site/src/site/xdoc/references/xdoc-format.xml
URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/xdoc/references/xdoc-format.xml?rev=568105&view=auto
==============================================================================
--- maven/doxia/site/src/site/xdoc/references/xdoc-format.xml (added)
+++ maven/doxia/site/src/site/xdoc/references/xdoc-format.xml Tue Aug 21 05:51:02 2007
@@ -0,0 +1,280 @@
+<?xml version="1.0"?>
+<!--
+/*
+ * 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.
+ */
+ -->
+<document>
+
+ <properties>
+ <title>The Xdoc format</title>
+ <author email="ltheussl_AT_apache_DOT_org">Lukas Theussl</author>
+ </properties>
+
+ <body>
+
+ <section name="The XDoc format">
+
+ <subsection name="Overview">
+
+ <p>
+ An 'xdoc' is an XML document conforming to a small and simple set of tags.
+ Xdoc was the primary documentation format in <a href="http://maven.apache.org/maven-1.x/">Maven 1</a>,
+ Maven 2 largely replaced this by <a href="apt-format.html">Apt</a>, but xdoc is still supported.
+ </p>
+
+ <p>
+ Historically, the xdoc format can be traced back to the
+ <a href="http://jakarta.apache.org/site/jakarta-site2.html">Anakia</a> format, as once used by the
+ <a href="http://jakarta.apache.org/">Apache Jakarta</a> project.
+ </p>
+
+ <p>
+ The Maven 1 Xdoc plugin introduced a few additions to the Anakia format, they are highlighted in the
+ <a href="http://maven.apache.org/maven-1.x/plugins/xdoc/reference/xdocs.html">plugin</a> documentation.
+ </p>
+
+ </subsection>
+
+ <subsection name="The XDoc format">
+
+ <p>
+ The following is a sample XDoc document:
+ </p>
+ <source><![CDATA[
+<document>
+
+ <properties>
+ <title>Page Title</title>
+ <author email="user@company.com">John Doe</author>
+ </properties>
+
+ <!-- Optional HEAD element, which is copied as is into the XHTML <head> element -->
+ <head>
+ <meta ... />
+ </head>
+
+ <body>
+
+ <!-- The body of the document contains a number of sections -->
+ <section name="section 1">
+
+ <!-- Within sections, any XHTML can be used -->
+ <p>Hi!</p>
+
+ <!-- in addition to XHTML, any number of subsections can be within a section -->
+ <subsection name="subsection 1">
+ <p>Subsection!</p>
+ </subsection>
+
+ </section>
+
+ <section name="other section">
+
+ <!-- You can also include preformatted source blocks in the document -->
+ <source>
+code line 1
+code line 2
+ </source>
+
+ </section>
+
+ </body>
+
+</document>]]></source>
+
+ </subsection>
+
+ <subsection name="Additional sectioning">
+
+ <p>
+ Doxia will produce <code><h2></code> and
+ <code><h3></code> headings for <code><section></code>
+ and <code><subsection></code> elements, respectively.
+ It is therefore perfectly valid to put some sub-headings
+ (<code><h4></code>, <code><h5></code>,
+ <code><h6></code>) inside a subsection. For instance,
+ </p>
+
+ <source><![CDATA[<h4>A subsubsection</h4>]]></source>
+
+ <p>
+ will produce:
+ </p>
+
+ <h4>A subsubsection</h4>
+
+ </subsection>
+
+ <subsection name="Referencing sections and subsections">
+
+ <p>
+ The core doxia modules do <b>not</b> construct anchors from
+ section/subsection names. If you want to reference a section,
+ you have to provide an explicit anchor:
+ </p>
+
+ <source><![CDATA[<a name="Section1"/>
+<section name="Section">
+
+ <a name="SubSection1"/>
+ <subsection name="SubSection">
+ </subsection>
+
+</section>]]></source>
+
+ <p>
+ <b>Note</b> that this differs from previous behavior, where anchors
+ were constructed from section/subsection names, replacing special
+ characters by underscores. This behavior presents two shortcomings:
+ </p>
+
+ <ul>
+
+ <li>
+ If two sections or subsections have identical names
+ (within one source document), you will get an ambiguity when
+ referencing them. Also the resulting html document will not be
+ valid XHTML. For other output formats (eg pdf), it might even be impossible
+ to generate the target document.
+ </li>
+
+ <li>
+ For long section titles, this leads to rather cumbersome anchor names.
+ </li>
+
+ </ul>
+
+ <p>
+ If automatic anchor generation is desired for a particular output format,
+ it should be implemented / overridden by the corresponding low-level Sink.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ <section name="Validation">
+
+ <p>
+ Doxia is currently not able to validate your xdoc files as no schema or DTD
+ exists yet (however this is planned before the 1.0 release).
+ It is therefore necessary to check manually whether your source files are valid xdocs,
+ this should ensure that the generated html files are valid
+ <a href="http://www.w3.org/TR/xhtml1/">XHTML1-transitional</a>.
+ </p>
+
+ <p>
+ Here is a list of common mistakes to be aware of:
+ </p>
+
+ <subsection name="Don't nest block level elements">
+
+ <p>Wrong:</p>
+
+ <source><![CDATA[<p>
+ Here's a list:
+ <ul>
+ <li>item 1</li>
+ <li>item 2</li>
+ </ul>
+ of things to do.
+</p>]]></source>
+
+ <p>Correct:</p>
+
+ <source><![CDATA[<p>
+ Here's a list:
+</p>
+<ul>
+ <li>item 1</li>
+ <li>item 2</li>
+</ul>
+<p>
+ of things to do.
+</p>]]></source>
+
+ <p>
+ Typical block level elements are list elements,
+ <code><table></code>, <code><source></code>,
+ <code><div></code>, <code><p></code> and
+ <code><pre></code>.
+ </p>
+
+ </subsection>
+
+ <subsection name="Put inline elements inside block level elements">
+
+ <p>Wrong:</p>
+
+ <source><![CDATA[<section name="Downloads">
+ <a href="downloads.html">Downloads</a>
+</section>]]></source>
+
+ <p>Correct:</p>
+
+ <source><![CDATA[<section name="Downloads">
+ <p>
+ <a href="downloads.html">Downloads</a>
+ </p>
+</section>]]></source>
+
+ <p>
+ Typical inline elements are
+ <code><a></code>, <code><strong></code>,
+ <code><code></code>, <code><font></code>,
+ <code><br></code> and <code><img></code>.
+ </p>
+
+ </subsection>
+
+ <subsection name="Right order of elements in <properties>">
+
+ <p>
+ The <code><title></code> element has to come before
+ <code><author></code>.
+ </p>
+
+ </subsection>
+
+ <subsection name="Dont put <source> inside paragraphs">
+
+ <p>Wrong:</p>
+
+ <source><![CDATA[<p>
+ The following command executes the program:
+ <source>java -jar CoolApp.jar</source>
+</p>]]></source>
+
+ <p>Correct:</p>
+
+ <source><![CDATA[<p>
+ The following command executes the program:
+</p>
+<source>java -jar CoolApp.jar</source>]]></source>
+
+ <p>
+ However, you may put <code><source></code> elements inside
+ list items or table rows.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
Propchange: maven/doxia/site/src/site/xdoc/references/xdoc-format.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/doxia/site/src/site/xdoc/references/xdoc-format.xml
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"