You are viewing a plain text version of this content. The canonical link for it is here.
Posted to doxia-dev@maven.apache.org by Dennis Lundberg <de...@apache.org> on 2007/07/23 14:50:11 UTC
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/
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
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/
Posted by Vincent Siveton <vi...@gmail.com>.
Hi Lukas,
2007/7/24, Lukas Theussl <lt...@apache.org>:
> Yeah! Now let anybody say that we can't write docs! (well, why couldn't
> you do that before I started getting familiar with doxia?... ;) )
>
> Two comments:
>
> - I never quite understood the (apparently general) maven philosophy of
> separating the site from the rest of the project. I would at least like
> to have a link to the project pages, where you have all the javadocs,
> code reports etc. Could I suggest to leave the current doxia-site as a
> user documentation site, and use the project sites for developer docs? WDYT?
Sounds good for me:
doxia-site => user documentation
core/modules/tools site => dev documentation
> - in the "Using A Doxia Module" example, you make reference to plexus, I
> think this is not necessary and might be confusing. Even though doxia
> uses plexus, it is not necessary to be familiar with it in order to use
> doxia. The simplest way to convert eg apt to xdoc with doxia is:
>
> FileReader source = new FileReader( new File( "test.apt" ) );
> XdocSink sink = new XdocSink( new FileWriter( new File( "test.xml" ) ) );
> AptParser parser = new AptParser();
> parser.parse( source, sink );
We need to lookup the parser with Plexus. If not, the macromanager in
the AbstractParser is not instantiated (and a NPE is throw...).
Cheers,
Vincent
>
> Thanks for all that anyway!
> -Lukas
>
>
> Dennis Lundberg wrote:
> > 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?
> >
>
>
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/
Posted by Lukas Theussl <lt...@apache.org>.
Yeah! Now let anybody say that we can't write docs! (well, why couldn't
you do that before I started getting familiar with doxia?... ;) )
Two comments:
- I never quite understood the (apparently general) maven philosophy of
separating the site from the rest of the project. I would at least like
to have a link to the project pages, where you have all the javadocs,
code reports etc. Could I suggest to leave the current doxia-site as a
user documentation site, and use the project sites for developer docs? WDYT?
- in the "Using A Doxia Module" example, you make reference to plexus, I
think this is not necessary and might be confusing. Even though doxia
uses plexus, it is not necessary to be familiar with it in order to use
doxia. The simplest way to convert eg apt to xdoc with doxia is:
FileReader source = new FileReader( new File( "test.apt" ) );
XdocSink sink = new XdocSink( new FileWriter( new File( "test.xml" ) ) );
AptParser parser = new AptParser();
parser.parse( source, sink );
Thanks for all that anyway!
-Lukas
Dennis Lundberg wrote:
> 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?
>
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/
Posted by Lukas Theussl <lt...@apache.org>.
[replying to doxia-dev@ as I think this was meant to go there]
I'd like to chime in here and try to clarify a design issue that I've
been thinking about recently.
The general doxia philosophy is clear from your description, what is not
specified IMO is the separation of responsibilities of a parser and a sink.
IMO all our core modules should try to achieve a 1-1 translation of the
core doxia events *only*. In particular, a parser shouldn't add anything
to a model that's not in the original. Good example is the commit I had
to revert recently (for backward compat reasons): the xdoc parser emits
an anchor for each section event. That's because it is needed in the
xhtml output, but it also means that the anchor will end up explicitly
in any sink document you might choose, even where it doesn't make any
sense. IMO it's only the low-end sink that should produce such
format-dependent elements.
As an extreme example you might imagine feeding the xhtml output back
into an xdoc sink; closing the circle you would end up adding anchors
indefinetly. One way to ensure this doesn't happen is the test I have
outlined at DOXIA-134: parsing an arbitrary model and feeding it back
into the corresponding sink, should give you back the original
unchanged. I don't know if it's possible in practice to achieve this for
all our modules, but it would certainly be a good quality control.
So, as you say, a sink is ultimately responsible for the final format
and structure, a parser should just stupidly forward the events it
receives. The core modules should just do 1-1 translations. Any special
output features should be handled by a low-end sink (eg
SiteRendererSink) for the particular format where this is desired.
Thoughts?
-Lukas
Jason van Zyl wrote:
>
> On 23 Jul 07, at 5:50 AM 23 Jul 07, Dennis Lundberg wrote:
>
>> 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?
>>
>
> Parser -> emission of Doxia events -> Sink
>
> A Sink consumes Doxia events in a resultant output format like Docbook,
> PDF, or XHTML.
>
> The upshot is that you can parse any front-end format, the parser is
> responsible for emitting the standard Doxia events which can then be
> consumed by any Doxia Sink. This is what allow us to parse the front-
> end format like APT, FML, and Xdoc for the Maven site plugin and have
> them all contribute to the final XHTML version of a site. All documents
> being parsed results in a stream of Doxia events (paragraph, bold,
> italic, text) which are then fed in the XHTML sink which results in a
> set of XHTML pages.
>
> A sink if ultimately responsible for the final format and structure.
> So, for example, you can take a series of APT documents and have that
> be fed into a Sink which makes a single PDF, a book, a site, or a Word
> document. The Sink is fully responsible for the final output. Once you
> have Doxia events you can leverage any existing Sink. So if you wanted
> to integrate your custom XML format, or custom Wiki format, you would
> create a Doxia parser which could then be fed into any Sink to produce
> your desired final output.
>
>
> Thanks,
>
> Jason
>
> ----------------------------------------------------------
> Jason van Zyl
> Founder and PMC Chair, Apache Maven
> jason at sonatype dot com
> ----------------------------------------------------------
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
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/
Posted by Jason van Zyl <ja...@maven.org>.
On 23 Jul 07, at 5:50 AM 23 Jul 07, Dennis Lundberg wrote:
> 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?
>
Parser -> emission of Doxia events -> Sink
A Sink consumes Doxia events in a resultant output format like
Docbook, PDF, or XHTML.
The upshot is that you can parse any front-end format, the parser is
responsible for emitting the standard Doxia events which can then be
consumed by any Doxia Sink. This is what allow us to parse the front-
end format like APT, FML, and Xdoc for the Maven site plugin and have
them all contribute to the final XHTML version of a site. All
documents being parsed results in a stream of Doxia events
(paragraph, bold, italic, text) which are then fed in the XHTML sink
which results in a set of XHTML pages.
A sink if ultimately responsible for the final format and structure.
So, for example, you can take a series of APT documents and have that
be fed into a Sink which makes a single PDF, a book, a site, or a
Word document. The Sink is fully responsible for the final output.
Once you have Doxia events you can leverage any existing Sink. So if
you wanted to integrate your custom XML format, or custom Wiki
format, you would create a Doxia parser which could then be fed into
any Sink to produce your desired final output.
Thanks,
Jason
----------------------------------------------------------
Jason van Zyl
Founder and PMC Chair, Apache Maven
jason at sonatype dot com
----------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org