maven-doxia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dennis Lundberg <denn...@apache.org>
Subject Re: svn commit: r558696 - in /maven/doxia/site: ./ src/site/ src/site/apt/ src/site/apt/developers/ src/site/apt/macros/ src/site/apt/modules/ src/site/apt/references/ src/site/fml/ src/site/resources/images/
Date Mon, 23 Jul 2007 12:50:11 GMT
This is excellent stuff Vincent!

I'm only missing one thing, that have been puzzling me since I got 
involved with Doxia:

   What is a Sink?

vsiveton@apache.org wrote:
> Author: vsiveton
> Date: Mon Jul 23 05:18:28 2007
> New Revision: 558696
> 
> URL: http://svn.apache.org/viewvc?view=rev&rev=558696
> Log:
> DOXIA-140: Review the Doxia site documentation
> 
> o structured the site and updated the site.xml
> o added several pages and faq
> o moved the apt format doc in references dir
> o moved the swf macro doc in macros dir
> 
> Added:
>     maven/doxia/site/src/site/apt/developers/
>     maven/doxia/site/src/site/apt/developers/index.apt   (with props)
>     maven/doxia/site/src/site/apt/macros/
>     maven/doxia/site/src/site/apt/macros/index.apt   (with props)
>     maven/doxia/site/src/site/apt/macros/swf-macro.apt
>       - copied unchanged from r558690, maven/doxia/site/src/site/apt/swf-macro.apt
>     maven/doxia/site/src/site/apt/modules/
>     maven/doxia/site/src/site/apt/modules/index.apt   (with props)
>     maven/doxia/site/src/site/apt/overview.apt   (with props)
>     maven/doxia/site/src/site/apt/references/
>     maven/doxia/site/src/site/apt/references/apt-format.apt
>       - copied unchanged from r558690, maven/doxia/site/src/site/apt/format.apt
>     maven/doxia/site/src/site/apt/references/index.apt   (with props)
>     maven/doxia/site/src/site/apt/resources.apt   (with props)
>     maven/doxia/site/src/site/fml/
>     maven/doxia/site/src/site/fml/faq.fml   (with props)
>     maven/doxia/site/src/site/resources/images/
>     maven/doxia/site/src/site/resources/images/architecture.png   (with props)
> Removed:
>     maven/doxia/site/src/site/apt/format.apt
>     maven/doxia/site/src/site/apt/guide-doxia-macros.apt
>     maven/doxia/site/src/site/apt/swf-macro.apt
> Modified:
>     maven/doxia/site/pom.xml
>     maven/doxia/site/src/site/apt/index.apt
>     maven/doxia/site/src/site/site.xml
> 
> Modified: maven/doxia/site/pom.xml
> URL: http://svn.apache.org/viewvc/maven/doxia/site/pom.xml?view=diff&rev=558696&r1=558695&r2=558696
> ==============================================================================
> --- maven/doxia/site/pom.xml (original)
> +++ maven/doxia/site/pom.xml Mon Jul 23 05:18:28 2007
> @@ -37,6 +37,8 @@
>    <artifactId>doxia-site</artifactId>
>    <packaging>pom</packaging>
>    <name>Doxia Site</name>
> +  <description>Site of the Maven Doxia Framework</description>
> +  <inceptionYear>2005</inceptionYear>
>    <url>http://maven.apache.org/doxia</url>
>  
>    <issueManagement>
> 
> Added: maven/doxia/site/src/site/apt/developers/index.apt
> URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/developers/index.apt?view=auto&rev=558696
> ==============================================================================
> --- maven/doxia/site/src/site/apt/developers/index.apt (added)
> +++ maven/doxia/site/src/site/apt/developers/index.apt Mon Jul 23 05:18:28 2007
> @@ -0,0 +1,187 @@
> + -----
> + Doxia Developers Centre
> + -----
> + Vincent Siveton
> + ------
> + July 2007
> + ------
> +
> +~~ 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 Developers Centre
> +
> + This documentation centre is for those that are developing Doxia modules or macro.
> +
> +*Create a New Doxia Module
> +
> + First, you need to create a POM with <doxia-modules> as parent:
> +
> +-----
> +<project>
> +  <parent>
> +    <groupId>org.apache.maven.doxia</groupId>
> +    <artifactId>doxia-modules</artifactId>
> +    <version>1.0</version> <!-- Latest release -->
> +  </parent>
> +  <modelVersion>4.0.0</modelVersion>
> +  <artifactId>doxia-module-my</artifactId>
> +  <name>Doxia :: MY Module</name>
> +
> +  ...
> +</project>
> +-----
> +
> + Secondly, you should implement some Doxia classes:
> +
> + * <MyParser> class
> +
> +-----
> +import org.apache.maven.doxia.parser.AbstractParser;
> +
> +/**
> + * @plexus.component role="org.apache.maven.doxia.parser.Parser" role-hint="my"
> + */
> +public class MyParser
> +    extends AbstractParser
> +{
> +...
> +}
> +-----
> +
> + * <MyParseException> class
> +
> +-----
> +import org.apache.maven.doxia.parser.ParseException;
> +
> +public class MyParseException
> +    extends ParseException
> +{
> +...
> +}
> +-----
> +
> + * <MySiteModule> class
> +
> +-----
> +import org.apache.maven.doxia.site.module.AbstractSiteModule;
> +
> +/**
> + * @plexus.component role="org.apache.maven.doxia.site.module.SiteModule" role-hint="my"
> + */
> +public class MySiteModule
> +    extends AbstractSiteModule
> +{
> +...
> +}
> +-----
> +
> + * <MySink> class
> +
> +-----
> +import org.apache.maven.doxia.sink.SinkAdapter;
> +
> +/**
> + * @plexus.component
> + */
> +public class MySink
> +    extends SinkAdapter
> +{
> +...
> +}
> +-----
> +
> +  []
> +
> +*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:
> +
> +-----
> +<project>
> +  ...
> +  <build>
> +    ...
> +    <plugins>
> +      <plugin>
> +        <groupId>org.codehaus.plexus</groupId>
> +        <artifactId>plexus-maven-plugin</artifactId>
> +        <executions>
> +          <execution>
> +            <goals>
> +              <goal>descriptor</goal>
> +            </goals>
> +          </execution>
> +        </executions>
> +      </plugin>
> +      ...
> +    </plugins>
> +  ...
> +  </build>
> +  ...
> +</project>
> +-----
> +
> + You should implement the <AbstractMacro> class:
> +
> +-----
> +import org.apache.maven.doxia.macro.AbstractMacro;
> +
> +/**
> + * @plexus.component role="org.apache.maven.doxia.macro.Macro" role-hint="my"
> + */
> +public class MyMacro
> +    extends AbstractMacro
> +{
> +...
> +    public void execute( Sink sink, MacroRequest request )
> +        throws MacroExecutionException
> +    {
> +        String paramValue = (String) request.getParameter( "param" );
> +...
> +    }
> +...
> +}
> +-----
> +
> + To use it, you need to write the following markups:
> +
> +  * APT
> +
> +-----
> +%{my|param=value}
> +-----
> +
> +  * XDoc
> +
> +-----
> +<macro name="my" param="value" />
> +-----
> +
> +  []
> +
> +*References
> +
> +  * {{{../modules/index.html}Doxia Modules Guide}}
> +
> +  * {{{../macros/index.html}Doxia Macros Guide}}
> +
> +  []
> 
> Propchange: maven/doxia/site/src/site/apt/developers/index.apt
> ------------------------------------------------------------------------------
>     svn:eol-style = native
> 
> Propchange: maven/doxia/site/src/site/apt/developers/index.apt
> ------------------------------------------------------------------------------
>     svn:keywords = "Author Date Id Revision"
> 
> Modified: maven/doxia/site/src/site/apt/index.apt
> URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/index.apt?view=diff&rev=558696&r1=558695&r2=558696
> ==============================================================================
> --- maven/doxia/site/src/site/apt/index.apt (original)
> +++ maven/doxia/site/src/site/apt/index.apt Mon Jul 23 05:18:28 2007
> @@ -2,22 +2,65 @@
>   Doxia
>   -----
>   Jason van Zyl
> - -----
> + Vincent Siveton
> + ------
> + July 2007
> + ------
> +
> +~~ 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.
>  
> -What is Doxia?
> +~~ NOTE: For help with the syntax of this file, see:
> +~~ http://maven.apache.org/guides/mini/guide-apt-format.html
> +
> +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 to generate
static
> - sites in addition to being incorporated into dynamic content generation systems like
> - blogs, wikis and content management systems.
> + 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. 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 exensively by Maven and it powers the entire documentation system of
Maven.
> + Doxia is used extensively by 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.
>  
> -Writing Books in Doxia
> +* Brief History
> +
> + Based on the {{{http://www.xmlmind.com/aptconvert.html}Aptconvert}} project developed
by
> + {{{http://www.xmlmind.com/}Xmlmind}} company, Doxia was initially hosted by Codehaus,
to become
> + a sub-project of Maven early in 2006.
> +
> +* Main Features
> +
> +  * Developed in Java
> +
> +  * Support of several markup formats: APT (Almost Plain Text), Confluence, DocBook,
> +    FML (FAQ Markup Language), LaTeX, RTF, TWiki, XDoc (popular in Apache land), XHTML
> +
> +~~ iText should be replaced by FOP
> +
> +  * Easy to learn the syntax of the supported markup formats
> +
> +  * Macro support
> +
> +  * No need to have a corporate infrastructure (like wiki) to host your documentation
>  
> - Doxia also has a fairly simple tool for writing books. It comes complete with a Maven
plugin
> - to produce PDFs, LaTeX documents and Xdoc for direct integration in your Maven site.
> +  * Extensible framework
>  
> - The Doxia Book code is still in the sandbox but it is fully functional allthough limited.
> - See {{{book/index.html}Writing Books in Doxia}} for more information.
> +  []
> 
> Added: maven/doxia/site/src/site/apt/macros/index.apt
> URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/macros/index.apt?view=auto&rev=558696
> ==============================================================================
> --- maven/doxia/site/src/site/apt/macros/index.apt (added)
> +++ maven/doxia/site/src/site/apt/macros/index.apt Mon Jul 23 05:18:28 2007
> @@ -0,0 +1,155 @@
> + ------
> + Doxia Macros Guide
> + ------
> + Vincent Siveton
> + ------
> + July 2007
> + ------
> +
> +~~ 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 Macros Guide
> +
> + The Doxia <Core> includes macro mechanisms to facilitate the documentation writing.
> +
> +*Echo Macro
> +
> + The <Echo> macro is a very simple macro: it prints out the key and value of any
supplied parameters.
> + For instance, in an APT file, you could write:
> +
> +-----
> +%{echo|param=value|param2=value2}
> +-----
> +
> +  and it will output
> +
> +-----
> +  param ---> value
> +  param2 ---> value2
> +-----
> +
> +*Snippet Macro
> +
> + The <Snippet> macro is a very useful macro: it prints out the content of a file
or an URL. For instance,
> + in an APT file, you could write:
> +
> +-----
> +%{snippet|id=myid|url=http://myserver/path/to/file.txt}
> +-----
> +
> + If you need to include only a part of a file, you could add a start and end snippets.
> +
> +  * Start and end snippets in a Java file
> +
> +-----
> +public class MyClass
> +{
> +    // START SNIPPET: foo
> +    public static void main( String[] args ) throws Exception
> +    {
> +        ...
> +    }
> +    // END SNIPPET: foo
> +}
> +-----
> +
> +  * Start and end snippets in a XML file
> +
> +-----
> +<project>
> +...
> +  <build>
> +    <plugins>
> +<!-- START SNIPPET: foo -->
> +      <plugin>
> +        ...
> +      </plugin>
> +<!-- END SNIPPET: foo -->
> +    </plugins>
> +  </build>
> +</project>
> +-----
> +
> +  []
> +
> +*-----------+--------------+
> +|| Parameter || Description  |
> +*-----------+--------------+
> +| id        | The id of the snippet.
> +*-----------+--------------+
> +| url       | The path of the URL to include.
> +*-----------+--------------+
> +| file      | The path of the file to include.
> +*-----------+--------------+
> +
> +*TOC Macro
> +
> + The <TOC> macro prints a Table Of Content of a document. It is useful if you
have several sections and
> + subsections in your document. For instance, in an APT file, you could write:
> +
> +-----
> +%{toc|section=2|fromDepth=0|toDepth=4}
> +-----
> +
> +*-----------+--------------+
> +|| 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.
> +*-----------+--------------+
> +| fromDepth | Display the depth starting for the given section number. Positive int,
not mandatory, 0 by default.
> +*-----------+--------------+
> +| toDepth   | Display the depth ending for the given section number. Positive int, not
mandatory, 5 by default.
> +*-----------+--------------+
> +
> +*SWF Macro
> +
> + The <Swf> macro prints Shockwave Flash assets in the documentation. For instance,
in an APT file,
> + you could write:
> +
> +-----
> +%{swf|src=swf/myfile.swf|id=MyMovie|width=600|height=200}
> +-----
> +
> +*-----------+--------------+
> +|| 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.
> 
> Propchange: maven/doxia/site/src/site/apt/macros/index.apt
> ------------------------------------------------------------------------------
>     svn:eol-style = native
> 
> Propchange: maven/doxia/site/src/site/apt/macros/index.apt
> ------------------------------------------------------------------------------
>     svn:keywords = "Author Date Id Revision"
> 
> Added: maven/doxia/site/src/site/apt/modules/index.apt
> URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/modules/index.apt?view=auto&rev=558696
> ==============================================================================
> --- maven/doxia/site/src/site/apt/modules/index.apt (added)
> +++ maven/doxia/site/src/site/apt/modules/index.apt Mon Jul 23 05:18:28 2007
> @@ -0,0 +1,150 @@
> + -----
> + Doxia Modules Guide
> + -----
> + Vincent Siveton
> + ------
> + July 2007
> + ------
> +
> +~~ 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 Modules Guide
> +
> + Doxia has several out-of-box modules that support several markup languages.
> +
> +*APT
> +
> + APT (Almost Plain Text) is a simple text format.
> +
> + <<References>>:
> +
> +  * {{{../references/apt-format.html}Apt Element Reference}}
> +
> +  []
> +
> +*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.
> +
> + <<References>>:
> +
> +  * {{{http://confluence.atlassian.com/display/CONF25/Confluence+Notation+Guide+Overview}Confluence
Notation Guide Overview}}
> +
> +  * {{{http://confluence.atlassian.com/renderer/notationhelp.action?section=all}Confluence
Element Reference}}
> +
> +  []
> +
> +~~ Textile in Java {{{https://sourceforge.net/projects/jtextile/}JTextile}}.
> +~~ http://hobix.com/textile/
> +
> +*DocBook
> +
> + {{{http://docbook.org/}DocBook}} is a markup language for technical documentation.
> +
> + <<References>>:
> +
> +  * {{{http://docbook.org/tdg/}DocBook: The Definitive Guide}}
> +
> +  * {{{http://www.docbook.org/tdg/en/html/ref-elements.html}DocBook Element Reference}}
> +
> +  []
> +
> +*FML
> +
> + FML (FAQ Markup Language) is a FAQ markup language.
> +
> + <<References>>:
> +
> +  * FML Reference
> +
> +  []
> +
> +~~ iText should be replaced by FOP
> +
> +*LaTeX
> +
> + {{{http://www.latex-project.org/}LaTeX}} is a popular document markup language.
> +
> + <<References>>:
> +
> +  * {{{http://www.latex-project.org/guides/usrguide.pdf}LaTeX2e for authors}}
> +
> +  * {{{http://www.stdout.org/~winston/latex/latexsheet.pdf}Latex reference sheet}}
> +
> +  []
> +
> +*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
> +
> + {{{http://twiki.org/}TWiki}} is a structured wiki.
> +
> + <<References>>:
> +
> +  * {{{http://twiki.org/cgi-bin/view/TWiki04x01/TextFormattingRules} TWiki Text Formatting}}
> +
> +  []
> +
> +*XDoc
> +
> + XDoc is a generic format for document into a styled HTML document.
> +
> + <<References>>:
> +
> +  * XDoc Reference
> +
> +  []
> +
> +*XHTML
> +
> + {{{http://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}}
> +
> +  []
> +
> +Using A Doxia Module
> +
> + The following snippet shows how to use a Doxia <Parser> in Java.
> +
> +-----
> +  Sink sink = new AptSink( ... );
> +
> +  Reader reader = new FileReader( "/tmp/test.apt" );
> +
> +  Parser parser = (AptParser) lookup( Parser.ROLE, "apt" ); // Plexus lookup
> +  parser.parse( reader, sink );
> +-----
> 
> Propchange: maven/doxia/site/src/site/apt/modules/index.apt
> ------------------------------------------------------------------------------
>     svn:eol-style = native
> 
> Propchange: maven/doxia/site/src/site/apt/modules/index.apt
> ------------------------------------------------------------------------------
>     svn:keywords = "Author Date Id Revision"
> 
> Added: maven/doxia/site/src/site/apt/overview.apt
> URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/overview.apt?view=auto&rev=558696
> ==============================================================================
> --- maven/doxia/site/src/site/apt/overview.apt (added)
> +++ maven/doxia/site/src/site/apt/overview.apt Mon Jul 23 05:18:28 2007
> @@ -0,0 +1,104 @@
> + -----
> + Overview Of The Doxia Framework
> + -----
> + Vincent Siveton
> + ------
> + July 2007
> + ------
> +
> +~~ 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
> +
> +Overview Of The Doxia Framework
> +
> + The following figure represents the main components of the Doxia Framework.
> +
> +[images/architecture.png] Doxia Framework
> +
> + <<Note>>: As Maven, Doxia uses extensively {{{http://plexus.codehaus.org/}Plexus}}
inside.
> +
> +*Sink API
> +
> + The <Sink> interface is a generic markup language interface. It contains several
methods that
> + encapsulate common text syntax. A start tag is denoted by <xxxx()> method
> + and a end of tag by <xxxx_()> method.
> +
> + For instance, you could do things like:
> +
> +-----
> + sink.paragraph();
> + sink.text( "my text" );
> + sink.paragraph_();
> +-----
> +
> + similar to this HTML markup:
> +
> +-----
> +<p>my text</p>
> +-----
> +
> + To find out more about the Sink API, you could read the Javadoc
> + {{{http://maven.apache.org/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html}here}}.
> +
> +*Doxia Core
> +
> + The <Core> is the API to parse a source and populate it in a <Sink> object.
The <Parser> interface
> + contains only one method:
> +
> +-----
> +void parse( Reader source, Sink sink )
> +    throws ParseException;
> +-----
> +
> + The <ParseException> class has the responsibility to catch all parsing exceptions.
It provides an
> + helper method, <getLineNumber()>, which helps to find where an error occurred.
> +
> + The <AbstractParser> class is an abstract implementation of the <Parser>.
It provides a macro mechanism
> + to give dynamic functionalities for the parsing. For more information on macros, read
the
> + {{{macros/index.html}Doxia Macro Guide}}.
> +
> + Finally, the <SiteModule> interface is the last part of the puzzle. It provides
main definitions of a
> + given Doxia module and it is used by the <doxia-site-renderer> site tools.
> +
> +*Doxia Modules
> +
> + A Doxia module is an implementation of a given markup language like APT or Xdoc. Each
module should
> + implement these interfaces:
> +
> +  * <Parser> interface, more specifically the <AbstractParser> class
> +
> +  * <SiteModule> interface
> +
> +  []
> +
> + Several modules provide also a <Sink> implementation to handle a specific markup
language.
> +
> + For more information on modules, read the {{{modules/index.html}Doxia Module Guide}}.
> +
> +*Doxia Site Tools
> +
> + The <Site Tools> are a collection of tools to renderer an output. The main tool
used by Maven,
> + specifically the {{{http://maven.apache.org/plugins/maven-site-plugin/}Maven Site Plugin}},
is the
> + <doxia-site-renderer> which renders in HTML any documents wrote with supported
markup syntax. It used
> + {{{http://velocity.apache.org/}Velocity templates}} to customize the renderer and the
> + <site-decoration-model> tool to decorate the renderer. This component describes
the layout of the site
> + defined in the <site.xml> file.
> +
> + The <doxia-doc-renderer> tool is used to renderer any document in another document.
> 
> Propchange: maven/doxia/site/src/site/apt/overview.apt
> ------------------------------------------------------------------------------
>     svn:eol-style = native
> 
> Propchange: maven/doxia/site/src/site/apt/overview.apt
> ------------------------------------------------------------------------------
>     svn:keywords = "Author Date Id Revision"
> 
> Added: maven/doxia/site/src/site/apt/references/index.apt
> URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/references/index.apt?view=auto&rev=558696
> ==============================================================================
> --- maven/doxia/site/src/site/apt/references/index.apt (added)
> +++ maven/doxia/site/src/site/apt/references/index.apt Mon Jul 23 05:18:28 2007
> @@ -0,0 +1,39 @@
> + -----
> + Doxia Markup Languages References
> + -----
> + Vincent Siveton
> + ------
> + July 2007
> + ------
> +
> +~~ 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 Markup Languages References
> +
> + You will find here several markup languages references used by Doxia to write well
done documentation.
> +
> +  * {{{apt-format.html}APT (Almost Plain Text) Format}}
> +
> +  * FML (FAQ Markup Language) Format
> +
> +  * Xdoc Format
> +
> +  []
> 
> Propchange: maven/doxia/site/src/site/apt/references/index.apt
> ------------------------------------------------------------------------------
>     svn:eol-style = native
> 
> Propchange: maven/doxia/site/src/site/apt/references/index.apt
> ------------------------------------------------------------------------------
>     svn:keywords = "Author Date Id Revision"
> 
> Added: maven/doxia/site/src/site/apt/resources.apt
> URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/resources.apt?view=auto&rev=558696
> ==============================================================================
> --- maven/doxia/site/src/site/apt/resources.apt (added)
> +++ maven/doxia/site/src/site/apt/resources.apt Mon Jul 23 05:18:28 2007
> @@ -0,0 +1,49 @@
> + -----
> + External Resources
> + -----
> + Vincent Siveton
> + ------
> + July 2007
> + ------
> +
> +~~ 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
> +
> +External Resources
> +
> +*Articles
> +
> +*-----------+--------------+--------------+
> +|| Title    || Publisher  || Author
> +*-----------+--------------+--------------+
> +| {{{http://software.newsforge.com/article.pl?sid=04/04/16/1428219}Quick and dirty typesetting
with APT}} | newsforge.com  | Scott Nesbitt
> +*-----------+--------------+--------------+
> +| {{{http://en.wikipedia.org/wiki/Lightweight_markup_language}Lightweight markup language}}
| wikipedia.org  | ?
> +*-----------+--------------+--------------+
> +| {{{http://project.knowledgeforge.net/kforge/trac/wiki/TextProcessing}Simple (Ascii-Based)
Text Formats}} | project.knowledgeforge.net  | ?
> +*-----------+--------------+--------------+
> +
> +*Tools
> +
> +*-----------+--------------+
> +|| Name    || Author
> +*-----------+--------------+
> +| {{{http://apteditor.sourceforge.net/}APT Editor (Eclipse plugin)}} | Mathieu Avoine
> +*-----------+--------------+
> 
> Propchange: maven/doxia/site/src/site/apt/resources.apt
> ------------------------------------------------------------------------------
>     svn:eol-style = native
> 
> Propchange: maven/doxia/site/src/site/apt/resources.apt
> ------------------------------------------------------------------------------
>     svn:keywords = "Author Date Id Revision"
> 
> Added: maven/doxia/site/src/site/fml/faq.fml
> URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/fml/faq.fml?view=auto&rev=558696
> ==============================================================================
> --- maven/doxia/site/src/site/fml/faq.fml (added)
> +++ maven/doxia/site/src/site/fml/faq.fml Mon Jul 23 05:18:28 2007
> @@ -0,0 +1,64 @@
> +<?xml version="1.0" encoding="ISO-8859-1" ?>
> +
> +<!--
> +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.
> +-->
> +
> +<faqs title="Frequently Asked Questions">
> +  <part id="General">
> +    <faq id="How to handle style in the APT markup language">
> +      <question>How to handle style in the APT markup language?</question>
> +      <answer>
> +        <p>
> +          APT doesn't actually support style. It is in the roadmap.
> +        </p>
> +      </answer>
> +    </faq>
> +    <faq id="How to export in PDF">
> +      <question>How to export in PDF?</question>
> +      <answer>
> +        <p>
> +          An <a href="http://www.lowagie.com/iText/">iText</a> module exists
using the iText XML document.
> +          Unfortunately, the iText team discontinued the XML to PDF functionalities.
> +        </p>
> +        <p>
> +          A <a href="http://xmlgraphics.apache.org/fop/">FOP</a> module
is actually in development in the
> +          Doxia sandbox. You could get the source
> +          <a href="http://svn.apache.org/repos/asf/maven/sandbox/trunk/doxia/doxia-module-fo">here</a>.
> +        </p>
> +      </answer>
> +    </faq>
> +    <faq id="Is it possible to create a book">
> +      <question>Is it possible to create a book?</question>
> +      <answer>
> +        <p>
> +          Doxia also has a fairly simple tool for writing books. It comes complete with
a Maven plugin
> +          to produce PDFs, LaTeX documents and Xdoc for direct integration in your Maven
site.
> +        </p>
> +        <p>
> +          The Doxia Book code is still in the
> +          <a href="http://svn.apache.org/repos/asf/maven/sandbox/trunk/doxia/doxia-book">Doxia
sandbox</a>
> +          but it is fully functional allthough limited.
> +        </p>
> +        <p>
> +          See <a href="book/index.html">Writing Books in Doxia</a> for more
information.
> +        </p>
> +      </answer>
> +    </faq>
> +  </part>
> +</faqs>
> \ No newline at end of file
> 
> Propchange: maven/doxia/site/src/site/fml/faq.fml
> ------------------------------------------------------------------------------
>     svn:eol-style = native
> 
> Propchange: maven/doxia/site/src/site/fml/faq.fml
> ------------------------------------------------------------------------------
>     svn:keywords = "Author Date Id Revision"
> 
> Added: maven/doxia/site/src/site/resources/images/architecture.png
> URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/resources/images/architecture.png?view=auto&rev=558696
> ==============================================================================
> Binary file - no diff available.
> 
> Propchange: maven/doxia/site/src/site/resources/images/architecture.png
> ------------------------------------------------------------------------------
>     svn:mime-type = image/png
> 
> Modified: maven/doxia/site/src/site/site.xml
> URL: http://svn.apache.org/viewvc/maven/doxia/site/src/site/site.xml?view=diff&rev=558696&r1=558695&r2=558696
> ==============================================================================
> --- maven/doxia/site/src/site/site.xml (original)
> +++ maven/doxia/site/src/site/site.xml Mon Jul 23 05:18:28 2007
> @@ -55,13 +55,21 @@
>        </script>
>      </head>
>  
> -    <menu name="Doxia">
> -      <item name="Overview" href="index.html"/>
> -      <item name="APT Format" href="format.html"/>
> -      <item name="Macros" href="guide-doxia-macros.html"/>
> +    <menu name="About Doxia">
> +      <item name="What is Doxia?" href="index.html"/>
> +      <item name="Overview" href="overview.html"/>
> +      <item name="FAQ" href="faq.html"/>
> +    </menu>
> +
> +    <menu name="Documentation">
> +      <item name="References"  href="references/index.html"/>
> +      <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="Developer Centre" href="developers/index.html"/>
> +      <item name="External Resources" href="resources.html"/>
>      </menu>
>  
> -    ${reports}
> +    <menu ref="reports"/>
>    </body>
>  </project>
> 
> 


-- 
Dennis Lundberg

Mime
View raw message