maven-doxia-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ltheu...@apache.org
Subject 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
Date Mon, 10 Mar 2008 10:50:30 GMT
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 &amp; 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>
 



Mime
View raw message