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 2008/03/10 11:50:30 UTC
svn commit: r635518 - in /maven/doxia/site/src/site:
apt/developers/index.apt apt/issues/ apt/issues/index.apt
apt/macros/index.apt apt/modules/index.apt site.xml xdoc/references/index.xml
Author: ltheussl
Date: Mon Mar 10 03:50:27 2008
New Revision: 635518
URL: http://svn.apache.org/viewvc?rev=635518&view=rev
Log:
Update docs
Added:
maven/doxia/site/src/site/apt/issues/
maven/doxia/site/src/site/apt/issues/index.apt (with props)
Modified:
maven/doxia/site/src/site/apt/developers/index.apt
maven/doxia/site/src/site/apt/macros/index.apt
maven/doxia/site/src/site/apt/modules/index.apt
maven/doxia/site/src/site/site.xml
maven/doxia/site/src/site/xdoc/references/index.xml
Modified: maven/doxia/site/src/site/apt/developers/index.apt
URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/developers/index.apt?rev=635518&r1=635517&r2=635518&view=diff
==============================================================================
--- maven/doxia/site/src/site/apt/developers/index.apt (original)
+++ maven/doxia/site/src/site/apt/developers/index.apt Mon Mar 10 03:50:27 2008
@@ -30,7 +30,9 @@
This documentation centre is for those that are developing Doxia modules or macro.
-*Create a New Doxia Module
+%{toc|section=1|fromDepth=1|toDepth=1}
+
+* {Create a New Doxia Module}
First, you need to create a POM with <doxia-modules> as parent:
@@ -110,7 +112,7 @@
[]
-*Create a New Doxia Macro
+* {Create a New Doxia Macro}
You need to add the following plugin configuration to generate the correct Plexus <component.xml> file
for the project containing your macro:
@@ -180,7 +182,25 @@
[]
-*References
+* {Passing attributes to Sink events}
+
+ With Doxia-1.0-beta-1 a number of methods have been added to the Sink API that
+ allow to pass a set of attributes to many sink events. A typical use case would be:
+
+-----
+SinkEventAttributeSet atts = new SinkEventAttributeSet();
+atts.addAttribute( SinkEventAttributes.ALIGN, "center" );
+
+sink.paragraph( atts );
+-----
+
+ What kind of attributes are 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
+ preferably when emitting events.
+
+
+* {References}
* {{{../modules/index.html}Doxia Modules Guide}}
Added: maven/doxia/site/src/site/apt/issues/index.apt
URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/issues/index.apt?rev=635518&view=auto
==============================================================================
--- maven/doxia/site/src/site/apt/issues/index.apt (added)
+++ maven/doxia/site/src/site/apt/issues/index.apt Mon Mar 10 03:50:27 2008
@@ -0,0 +1,71 @@
+ -----
+ Doxia Issues
+ -----
+ Lukas Theussl
+ ------
+ March 2008
+ ------
+
+~~ 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/guides/mini/guide-apt-format.html
+
+Doxia Issues & Gotchas
+
+ This document collects some infos about specific issues and 'gotchas' when working with Doxia.
+
+%{toc|section=1|fromDepth=1|toDepth=1}
+
+* {Figure sink events}
+
+ Doxia distinguishes bewteen figures, which are block-level elements, and images (or icons),
+ which are in-line elements. For instance, the following sequence of sink events
+
+-----
+sink.figure( null );
+
+sink.figureGraphics( "figure.png", null );
+
+sink.figureCaption( null );
+sink.text( "Figure caption", null );
+sink.figureCaption_();
+
+sink.figure_();
+-----
+
+ should output the equivalent of this html snippet:
+
+-----
+<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.
+
+ <<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
+
+-----
+<img src="figure.png" alt="Figure caption"/>
+-----
Propchange: maven/doxia/site/src/site/apt/issues/index.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/doxia/site/src/site/apt/issues/index.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Modified: maven/doxia/site/src/site/apt/macros/index.apt
URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/macros/index.apt?rev=635518&r1=635517&r2=635518&view=diff
==============================================================================
--- maven/doxia/site/src/site/apt/macros/index.apt (original)
+++ maven/doxia/site/src/site/apt/macros/index.apt Mon Mar 10 03:50:27 2008
@@ -52,18 +52,9 @@
As of Doxia-1.0-beta-1, the following macros are available:
- * {{{Echo_Macro} Echo Macro}}: print out parameters
+%{toc|section=1|fromDepth=1|toDepth=2}
- * {{{Snippet_Macro} Snippet Macro}}: include (parts of) external files
-
- * {{{TOC_Macro} TOC Macro}}: print a Table of Contents
-
- * {{{SWF_Macro} SWF Macro}}: print Shockwave Flash assets
-
- []
-
-
-*{Echo Macro}
+* {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:
@@ -88,7 +79,7 @@
param2 ---> value2
-----
-*{Snippet Macro}
+* {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:
@@ -160,7 +151,7 @@
| | webserver. Default value is <<<true>>>.
*-----------+--------------+
-*{TOC Macro}
+* {TOC Macro}
The <TOC> macro prints a Table Of Content of a document. It is useful if you have several sections and
subsections in your document. For instance, in an APT file, you could write:
@@ -169,6 +160,10 @@
%{toc|section=2|fromDepth=0|toDepth=4}
-----
+ <<Note>> that in Doxia, apt section titles are not implicit anchors
+ (see {{{../references/doxia-apt.html}Enhancements to the APT format}}), so you need
+ to insert explicit anchors for links to work!
+
In a xdoc file, it will be:
-----
@@ -182,14 +177,14 @@
*-----------+--------------+
|| Parameter || Description |
*-----------+--------------+
-| section | Display the specificated section number or all sections if 0 (in this case, other parameters are ignored). Positive int, not mandatory, 0 by default.
+| section | Display a TOC for the specified section only, or all sections if 0 (in this case, other parameters are ignored). Positive int, not mandatory, 0 by default.
*-----------+--------------+
-| fromDepth | Display the depth starting for the given section number. Positive int, not mandatory, 0 by default.
+| fromDepth | Minimum section depth to include in the TOC. Positive int, not mandatory, 0 by default.
*-----------+--------------+
-| toDepth | Display the depth ending for the given section number. Positive int, not mandatory, 5 by default.
+| toDepth | Maximum section depth to include in the TOC. Positive int, not mandatory, 5 by default.
*-----------+--------------+
-*{SWF Macro}
+* {SWF Macro}
The <Swf> macro prints Shockwave Flash assets in the documentation. For instance, in an APT file,
you could write:
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=635518&r1=635517&r2=635518&view=diff
==============================================================================
--- maven/doxia/site/src/site/apt/modules/index.apt (original)
+++ maven/doxia/site/src/site/apt/modules/index.apt Mon Mar 10 03:50:27 2008
@@ -28,9 +28,15 @@
Doxia Modules Guide
- Doxia has several out-of-box modules that support several markup languages.
+ 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.
-*APT
+%{toc|section=1|fromDepth=1|toDepth=1}
+%{toc|section=2|fromDepth=0|toDepth=0}
+
+
+* {APT}
APT (Almost Plain Text) is a simple text format.
@@ -40,7 +46,7 @@
[]
-*Confluence
+* {Confluence}
{{{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.
@@ -56,7 +62,7 @@
~~ Textile in Java {{{https://sourceforge.net/projects/jtextile/}JTextile}}.
~~ http://hobix.com/textile/
-*DocBook
+* {DocBook}
{{{http://docbook.org/}DocBook}} is a markup language for technical documentation.
@@ -68,7 +74,7 @@
[]
-*FML
+* {FML}
FML (FAQ Markup Language) is a FAQ markup language.
@@ -80,7 +86,7 @@
~~ iText should be replaced by FOP
-*iText
+* {iText}
{{{http://www.lowagie.com/iText/}iText}} is a free Java/PDF library.
@@ -93,7 +99,7 @@
[]
-*LaTeX
+* {LaTeX}
{{{http://www.latex-project.org/}LaTeX}} is a popular document markup language.
@@ -105,7 +111,7 @@
[]
-*RTF
+* {RTF}
{{{http://www.microsoft.com/downloads/details.aspx?FamilyId=DD422B8D-FF06-4207-B476-6B5396A18A2B&displaylang=en}RTF}}
is a proprietary document file format.
@@ -118,7 +124,7 @@
[]
-*TWiki
+* {TWiki}
{{{http://twiki.org/}TWiki}} is a structured wiki.
@@ -128,7 +134,7 @@
[]
-*XDoc
+* {XDoc}
XDoc is a generic format for document into a styled HTML document.
@@ -138,7 +144,7 @@
[]
-*XHTML
+* {XHTML}
{{{http://www.w3.org/MarkUp/}XHTML}} is a markup language with the same expressions as HTML, but also
conforms to XML syntax.
@@ -151,15 +157,20 @@
[]
-Using A Doxia Module
+{Using A Doxia Module}
- The following snippet shows how to use a Doxia <Parser> in Java.
+ The following snippet shows how to use a Doxia <Parser> to transform an apt file to html:
-----
- Sink sink = new AptSink( ... );
+ Sink sink = new XhtmlSink( new FileWriter( "test.html" ) );
- Reader reader = new FileReader( "/tmp/test.apt" );
+ Reader reader = new FileReader( "test.apt" );
Parser parser = (AptParser) lookup( Parser.ROLE, "apt" ); // Plexus lookup
+
parser.parse( reader, sink );
-----
+
+ It is recommended that you use 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.
Modified: maven/doxia/site/src/site/site.xml
URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/site.xml?rev=635518&r1=635517&r2=635518&view=diff
==============================================================================
--- maven/doxia/site/src/site/site.xml (original)
+++ maven/doxia/site/src/site/site.xml Mon Mar 10 03:50:27 2008
@@ -73,6 +73,7 @@
<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"/>
+ <item name="Issues & Gotchas" href="issues/index.html"/>
<item name="Developer Centre" href="developers/index.html"/>
<item name="External Resources" href="resources.html"/>
</menu>
Modified: maven/doxia/site/src/site/xdoc/references/index.xml
URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/xdoc/references/index.xml?rev=635518&r1=635517&r2=635518&view=diff
==============================================================================
--- maven/doxia/site/src/site/xdoc/references/index.xml (original)
+++ maven/doxia/site/src/site/xdoc/references/index.xml Mon Mar 10 03:50:27 2008
@@ -160,9 +160,9 @@
<td>Extensible Hypertext Markup Language</td>
<td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td>
<td align="center"><img src="../images/icon_success_sml.gif" alt="Yes"/></td>
- <td></td>
- <td></td>
- <td></td>
+ <td>xhtml</td>
+ <td>xhtml</td>
+ <td>xhtml</td>
</tr>
</table>