Home

Apache Maven Doxia - The Apache Software Foundation!

1. Apache Maven Doxia v 1 6 User Guide The Apache Software Foundation 2015 12 09 Table of Contents i Table of Contents Table of Contents RA i What is Doxia Sart loa TS O a A tae iaes 2 FAQ A OE Y EN 4 What s new Idilio is 7 HOTEL COS E Ad 8 APURO Mid OA E ned O as 10 Doxia Apt Enhancements oooccoccoccnccccnccncnncnnnrn ee eeeeeeeee 20 EML Format ienee a ea anae E aa Ei ena he eddie a A aid 23 Xd c FORMAS a A A ae ee 26 Doxia Modules Guide irradia 31 Doxia Macros Guide 0 00 ia 34 Writing BOOKS piu A A ASA 38 Developer C ntre s c cis iii teed dawn a cia Sweet ewe 41 Create a Doxia Module 0ccccece cece cece eee eee eeeneeneneee 42 Create a Doxia Macro 0cccc cece cece eee e cece cence ee eeeeeeneeaees 44 Using the Sink APh ssy eis vcs sien es tena cr a ew eee ee aw a 46 Integration With Maven 0 cecee cece eee rn 50 Issues Samp Gotchas iiss A eee 52 External Resources cess Siew Ad eet 54 2015 The Apache Software Foundation ALL RIGHTS RESERVED Table of Contents 2015 The Apache Software Foundation ALL RIGHTS RESERVED 1 What is Doxia 1 What is Doxia 1 1 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 in web based publishing context to generate static sites in addition to being incorporated into dynamic content generation system
2. 2015 The Apache Software Foundation ALL RIGHTS RESERVED 16 Using th e Sink API 16 1 3 Passing attributes to Sink events 48 With Doxia 1 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 Sink atts sink EventAttributeSet a tts new SinkEventAttributeSet addAttribute Sink paragraph atts EventAttributes ALIGN center 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 16 1 4 Avoid sink rawText In Doxia 1 0 it was a common practice to use sink rawText to generate elements that were not supported by the Sink API For example the following snippet could be used to generate a styled HTML lt div gt block sink RawText lt div style cool gt sink text A text with a cool style sink rawText lt div gt This has a major drawback however it only works if the receiving Sink is a HTML Sink In other words the above method will not work for target documents in any other format than HTML think of the FO Sink to generate a pdf or a LaTeX sink In Doxia 1 1 a new method unknown was added to the Sink API that can be used to emit an arbitra
3. ALL RIGHTS RESERVED 6 Apt Format 13 List item 3 Force end of list Verbatim text not contained in list item 3 In the previous example without the the verbatim text not indented as all displays would have been contained in list item 3 A single may be used to end several nested lists at the same time The indentation of may be used to specify exactly which lists should be ended Example List item 1 List item 2 Sub list item 1 Sub list item 2 Verbatim text contained in list item 2 but not in sub list item 2 There are three kind of lists the bulleted lists we have already described the numbered lists and the definition lists 1 Numbered item 1 A Numbered item A B Numbered item B 2 Numbered item 2 A numbered list item begins with a label between two square brackets The label of the first item establishes the numbering scheme for the whole list 1 Decimal numbering 1 2 3 4 etc a Lower alpha numbering a b c d etc A Upper alpha numbering A B C D etc i 2015 The Apache Software Foundation ALL RIGHTS RESERVED 6 Apt Format 14 Lower roman numbering i ii ili iv etc I Upper roman numbering I I IMI IV etc The labels of the items other than the first one are ignored It is recommended to take the time to type the correct label f
4. Doxia has several built in modules that support some standard markup languages see the References page for an overview The following is just a collection of reference links for the individual formats e APT e Confluence e Simplified DocBook e FML e iText e FO since Doxia 1 1 e LaTeX e Markdown since Doxia 1 3 e RTF e TWiki since Doxia 1 1 e XDoc e XHTML 10 1 1 APT APT Almost Plain Text is a simple text format References e Apt Reference 10 1 2 Confluence Confluence is an Enterprise wiki from Atlassian It uses Textile inside as an APT language References e Confluence Notation Guide Overview Confluence Element Reference 10 1 3 Simplified DocBook DocBook is a markup language for technical documentation Simplified DocBook is a simpler subset References e Simplified DocBook Introduction e Simplified DocBook Element Reference 10 1 4 FML FML FAQ Markup Language is a FAQ markup language References e FML Reference 10 1 5 iText iText is a free Java PDF library 2015 The Apache Software Foundation ALL RIGHTS RESERVED 10 Doxia Modules Guide 32 References e Text tutorial 10 1 6 FO since Doxia 1 1 XSL formatting objects XSL FO References e XSL FO Recommendation 05 December 2006 e XSL FO reference e Apache FOP 10 1 7 LaTeX LaTeX is a popular document markup language References e LaTeX2e for authors e Latex reference sheet 10 1 8 Markdown since D
5. the Site Module 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 2 1 3 Doxia Modules A Doxia module is an implementation of a given markup language like APT or Xdoc Each module should implement these interfaces e Parser interface more specifically the AbstractParser class e SiteModule interface Several modules provide also a Sink implementation to handle a specific output markup language For more information on modules read the Doxia Module Guide 2 1 4 Doxia Site Tools The Site Tools are a collection of tools to renderer an output The main tool used by Maven specifically the Maven Site Plugin is the doxia site renderer which renders in HTML any documents written with supported markup syntax It uses 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 2015 The Apache Software Foundation ALL RIGHTS RESERVED 3 FAQ 4 3 1 Frequently Asked Questions 1 How to handle style in the APT markup language 2 How to export in PDF 3 Is it possible to create a book 4 Why XML based sinks don t generate nicely formatted documents 5 Where are the Maven Doxia XSD schemas files 6 How to define character entities i
6. 251 xA9 u00a9 Latin 1 characters whatever is the encoding of the APT document may be specified by their codes using a backslash followed by one to three octal digits or by using the x NN notation where NN are two hexadecimal digits Unicode characters may be specified by their codes using the u NNNN notation where NNNN are four hexadecimal digits 2015 The Apache Software Foundation ALL RIGHTS RESERVED 6 Apt Format 6 Comment Commented out Text found after two tildes is ignored up to the end of line A line of is often used to underline section titles in order to make them stand out of other paragraphs 2015 The Apache Software Foundation ALL RIGHTS RESERVED 17 6 Apt Format 2015 The Apache Software Foundation ALL RIGHTS RESERVED 18 6 Apt Format Paragraph 1 line 1 Paragraph 1 line 2 Paragraph 2 line 1 Paragraph 2 line 2 Section title Sub section title Sub sub section title xxx Sub sub sub section title Sub sub sub sub section title List item 1 List item 2 Paragraph contained in list item 2 Sub list item 1 Sub list item 2 List item 3 Force end of list H Verbatim text not contained in list item 3 H 1 Numbered item 1 A Numbered item A B Numbered item B 2 Numbered item 2 List numbering schemes 1 a A
7. Overview 2 2 Overview 2 1 Overview Of The Doxia Framework The following figure represents the main components of the Doxia Framework Sink API Doxia Core Doxia Modules Doxia Site Tools Doxia Tools Note Just like Maven Doxia uses Plexus extensively 2 1 1 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 2015 The Apache Software Foundation ALL RIGHTS RESERVED 2 Overview 3 sink paragraph sink text my text sink paragraph_ similar to this HTML markup lt p gt my text lt p gt To find out more about the Sink API you could read the Javadoc here 2 1 2 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 Doxia Macro Guide Finally
8. are all indented by two spaces This style is much nicer than the one used for the previous paragraph Note that tabs are expanded with a tab width set to 8 6 1 3 Document elements 6 1 3 1 Block level elements 6 Title A title is optional If used it must appear as the first block of the document Title Author Date A title block is indented centering it is nicer It begins with a line containing at least 3 dashes After the first line one or several consecutive lines of text implicit line break after each line specify the title of the document This text may immediately be followed by another line and one or several consecutive lines of text which specifies the author of the document The author sub block may optionally be followed by a date sub block using the same syntax The following example is used for a document with an title and a date but with no declared author The last line is ignored It is just there to make the block nicer Note the date has no specific format and will be parsed as string But we recommend to use the ISO 8601 standard since formatting a date varies around the world YYYY MM DD 2015 The Apache Software Foundation ALL RIGHTS RESERVED 6 Apt Format 12 where Y Y YY is the year in the Gregorian calendar MM is the month of the year between 01 January and 12 December and DD is the day of the month between 01 and 31 6 Paragrap
9. document gt Note if CDATA is used to specify entity Doxia will replace amp by amp amp i e lt CDATA amp iexcl gt becomes amp amp iexcl top How to integrate Doxia 1 1 with Maven See this page top 2015 The Apache Software Foundation ALL RIGHTS RESERVED 4 What s new in 1 1 7 What s new in 1 1 4 1 What s new in 1 1 This document describes the changes made to Maven Doxia between versions 1 0 and 1 1 4 1 1 Notable New Features Logging added logging support with a new project called doxia logging api e Sink API improvements added a new SinkEventAttributes interface to handle attributes The Sink interface has been updated to use this new interface Added new methods for comments and unknown events to the Sink interface e SinkFactory all Sink implementations can be retrieved via a factory e XSDs created several XSDs in particular for FML and Xdoc e Tools created some tools like a converter and a linkchecker to use Doxia outside of Maven e New Sinks for Confluence XLS FO and Twiki e Applied afew modifications to the APT format The full list of changes for 1 1 can be found in our issue management system 1 1 1 1 1 1 1 2 1 1 3 1 1 4 4 1 2 Binary Incompatibility Please note that in version 1 1 a number of new methods were added to the Sink and SinkFactory APIs which makes them binary incompatible with version 1 0 However maven reporting plugi
10. foo gt lt question gt What is Foo lt question gt lt answer gt lt p gt some markup goes here lt p gt lt source gt some source code lt source gt lt p gt some markup goes here lt p gt lt answer gt lt faq gt lt faq id whats bar gt lt question gt What is Bar lt question gt lt answer gt lt p gt some markup goes here lt p gt lt answer gt lt faq gt lt part gt lt part id install gt lt title gt Installation lt title gt lt faq id how install gt lt question gt How do I install Foo lt question gt lt answer gt lt p gt some markup goes here lt p gt lt answer gt lt faq gt lt part gt lt faqs gt 2015 The Apache Software Foundation ALL RIGHTS RESERVED 8 FML Format 8 2 Validation Doxia is able to validate your fml files as described here 2015 The Apache Software Foundation ALL RIGHTS RESERVED 25 9 Xdoc Format 26 9 Xdoc Format 9 1 Content e Content e The XDoc format e Overview e The XDoc xsd e XDoc Sample e The lt source gt tag e Additional sectioning e Referencing sections and subsections e Validation e Don t nest block level elements e Put inline elements inside block level elements Right order of elements in lt properties gt e Dont put lt source gt inside paragraphs 9 2 The XDoc format 9 2 1 Overview An xdoc is an XML document conforming to a small and simple set of ta
11. link element that does not refer to an anchor of the same name The name of an anchor link is its text with all non alphanumeric characters stripped Change This rule does not apply to links to external anchors Text beginning with http https ftp file mailto and on Windows is recognized as an external anchor name When the construct name text is used the link text text may differ from the link name name Anchor link elements may appear anywhere except inside other anchor link elements Section titles are implicitly defined anchors Change 6 Line break Force line break A backslash character followed by a newline character Line breaks must not be used inside titles and tables which are line oriented blocks with implicit line breaks 6 Non breaking space Non breaking space A backslash character followed by a space character 6 Special character Escaped special characters t Ml Ml lt M gt My Mir AN In certain contexts these characters have a special meaning and therefore must be escaped if needed as is They are escaped by adding a backslash in front of them The backslash may itself be escaped by adding another backslash in front of it Note that an asterisk for example needs to be escaped only if its begins a paragraph has no special meaning in the middle of a paragraph Copyright symbol
12. to make the table nicer The first is not only used to make the table nicer but also to specify that a grid is to be drawn around table cells The following example shows a simple table with no grid and no caption 6 Horizontal rule A non indented line containing at least 3 equal signs 6 Page break E A non indented line containing a single form feed character Control L 6 1 3 2 Text level elements 6 Font lt Italic gt font lt lt Bold gt gt font lt lt lt Monospaced gt gt gt font Text between lt and gt must be rendered in italic Text between lt lt and gt gt must be rendered in bold Text between lt lt lt and gt gt gt must be rendered using a monospaced typewriter like font Font elements may appear anywhere except inside other font elements 2015 The Apache Software Foundation ALL RIGHTS RESERVED 6 Apt Format 16 It is not recommended to use font elements inside titles section titles links and defined terms because an APT processor automatically applies appropriate font styles to these elements 6 Anchor and link Anchor Link to anchor Link to http www pixware fr Link to ffanchor showing alternate text Link to http www pixware fr Pixware home page Text between curly braces specifies an anchor Text between double curly braces specifies a link It is an error to create a
13. Format 6 1 The APT format APT stands for Almost Plain Text APT is a markup language that takes the hassle out of documentation writing by striving for simplicity Its syntax resembles plain text more than it resembles most other markup formats such as HTML This document provides some examples of available APT formatting 6 1 1 Important Notice The information contained in this document corresponds to the original APT format as published by Xmlmind In version 1 1 Maven Doxia has applied several modifications to this original format see this separate document for a detailed description Notable differences are highlighted below with a Change link The following sections contain formatted text that demonstrates the use of APT to create paragraphs headers sections lists code samples figures tables rules breaks and text level elements such as font styles anchors and special characters Boxes containing text in typewriter like font are examples of APT source 6 1 2 Document structure A short APT document is contained in a single text file A longer document may be contained in a ordered list of text files For instance first text file contains section 1 second text file contains section 2 and so on Note Splitting the APT document in several text files on a section boundary is not mandatory The split may occur anywhere However doing so is recommended because a text file containing a section is by itself a valid A
14. L String javascriptCode An function javascriptFunction n SinkEventAttributeSet atts new SinkEventAttributeSet atts addAttribute SinkEventAttributes TYPE text javascript sink unknown Script new Object new Integer HtmlMarkup TAG_TYPE_START att sink unknown cdata new Object new Integer HtmlMarkup CDATA_TYPE javascrip sink unknown script new Object new Integer HtmlMarkup TAG_TYPE_END null 16 1 6 References Doxia Modules Guide Doxia Macros Guide Doxia API Reference Doxia Sitetools API Reference 2015 The Apache Software Foundation ALL RIGHTS RESERVED 17 17 Integration With Maven 50 Integration With Maven 17 1 Integration With Maven This page presents how to use Doxia 1 1 under Maven 2 0 x and 2 1 x with a Maven reporting plugin Its goal is to help the Maven reporting plugin developer to integrate it 17 1 1 Maven 2 0 x Doxia 1 0 API is embedded in Maven 2 0 x see MNG 3402 so your Maven reporting plugin needs to shade Doxia 1 1 API and Logging to be backward compatible with Maven 2 0 x lt project gt lt build gt lt plugins gt lt plugin gt lt artifactId gt maven shade plugin lt artifactId gt lt version gt 1 2 lt version gt lt executions gt lt execution gt lt phase gt package lt phase gt lt goals gt lt goal gt shade lt goal gt lt goals gt lt configuration gt
15. PT document A file contains a sequence of paragraphs and displays non paragraphs such as tables separated by open lines A paragraph is simply a sequence of consecutive text lines First line of first paragraph Second line of first paragraph Third line of first paragraph Line 1 of paragraph 2 separated from first paragraph by an open line Line 2 of paragraph 2 The indentation of the first line of a paragraph is the main method used by an APT processor to recognize the type of the paragraph For example a section title must not be indented at all A plain paragraph must be indented by a certain amount of space For example a plain paragraph which is not contained in a list may be indented by two spaces My section title not indented My paragraph first line indented by 2 spaces 2015 The Apache Software Foundation ALL RIGHTS RESERVED 6 Apt Format 11 Indentation is not rigid Any amount of space will do You don t even need to use a consistent indentation all over your document What really matters for an APT processor is whether the paragraph is not indented at all or when inside a list whether a paragraph is more or less indented than the first item of the list more about this later First paragraph has its first line indented by four spaces Then the author did not even bother to indent the other lines of the paragraph Second paragraph contains several lines which
16. a xdoc file it will be 2015 The Apache Software Foundation ALL RIGHTS RESERVED 11 Doxia Macros Guide 37 lt macro name swf gt lt param name width lt macro gt lt param name src value swf myfile swf gt lt param name id value MyMovie gt value 600 gt lt param name height value 200 gt src Specifies the location URL of the movie to be loaded Identifies the Flash movie to the host environment a web browser for example so that it can be referenced using a scripting language width height quality Specifies the width of the movie in either pixels or percentage of browser window Specifies the height of the movie in either pixels or percentage of browser window 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 play 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 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 percen
17. acro name macro_name gt lt param name paraml value valuel gt lt param name param2 value value2 gt lt macro gt As of Doxia 1 1 the following macros are available e Echo Macro e Snippet Macro e TOC Macro e SWF Macro 11 1 1 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 fecho paraml valuel param2 value2 Similarly 1t will be for xdoc file lt macro name echo gt lt param name paraml value valuel gt lt param name param2 value value2 gt lt macro gt and it will output paraml gt valuel param2 gt value2 11 1 2 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 S snippet id myid url http myserver path to file txt 2015 The Apache Software Foundation ALL RIGHTS RESERVED 11 Doxia Macros Guide 35 In a xdoc file it will be lt macro name snippet gt lt param name id value myid gt lt param name url value http myserver path to file txt gt lt macro gt The id parameter is not required if you want to include the entire file If you want to include only a part of a file you should add start and end demarcators any line typically a comment that contains the str
18. aven apache org DECORATION 1 lt project gt 0 0 http maven apa Note for preformance reasons all XSDs DTDs use a cache in java io tmpdir 2015 The Apache Software Foundation ALL RIGHTS RESERVED 3 FAQ 6 top How to define character entities in Doxia XML files with XSD Since it is not possible to define character entity references like amp copy in XSDs unlike DTDs each XML file should have a lt DOCTYPE gt to define the character entity set For instance you could add the following in your Xdoc XML files to be similar to XHTML 1 0 Transitional dtd lt DOCTYPE document lt These are th ntity sets for ISO Latin 1 characters for the XHTML gt lt ENTITY HTMLlatl PUBLIC W3C ENTITIES Latin 1 for KHTML EN http w SHTMLlat1 lt These are th ntity sets for special characters for the XHTML gt lt ENTITY HTMLsymbol PUBLIC W3C ENTITIES Symbols for XHTML EN http SHTMLsymbol lt These are th ntity sets for symbol characters for the XHTML gt lt ENTITY HTMLspecial PUBLIC W3C ENTITIES Special for XHTML EN http SHTMLspecial gt lt document xmlns http maven apache org XDOC 2 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http maven apache org XDOC 2 0 http maven apache org xs lt
19. cells Header cells are defined by an additional pipe character l at the beginning of the cell Header 1 Header 2 Cell 1 Cell 2 produces 2015 The Apache Software Foundation ALL RIGHTS RESERVED 7 Doxia Apt Enhancements 21 Cell 1 Cell 2 7 1 3 Multi lines cells in table Since 1 1 multi lines cells are recognized with the character V at the end of the cells Header 1 Header 2 Cell Cell 2 1 produces Cell Cell 2 7 1 4 Anchors 7 1 4 1 Anchors for section titles Contrary to the original APT format section titles are not implicitly defined anchors If you want an anchor for a section title you need to define it explicitly as such Anchors for section titles 7 1 4 2 Anchor construction Contrary to the original APT format an anchor link is not its text with all non alphanumeric characters stripped Ideally an anchor should be a valid Doxia id ie it must begin with a letter A Za z and may be followed by any number of letters digits 0 9 hyphens underscores _ colons and periods Any anchor that does not satisfy this pattern is transformed according to the following rules e Any whitespace at the start and end is removed e If the first character is not a letter prepend the letter a tt e Any spaces are replaced with an u
20. d to convert an APT document to PostScript and your figure name is home joe docs mylogo An APT processor will first try to load home j0e docs mylogo eps When the desired format 1s not found a APT processor tries to convert one of the existing formats In our example the APT processor tries to convert home joe docs mylogo jpeg to encapsulated PostScript 6 Table A table block is not indented It begins with a non indented line containing an asterisk and at least 2 dashes It ends with a similar line 2015 The Apache Software Foundation ALL RIGHTS RESERVED 6 Apt Format 15 The first line is not only used to recognize a table but also to specify column justification In the following example e the second asterisk is used to specify that column 1 is centered e the plus sign specifies that column 2 is left aligned e the colon specifies that column 3 is right aligned Centered Left aligned Right aligned CELULA eert I2 p eed ES cell lt 2 4 gerl 242 cell 2 3 x Table caption Rows are separated by a non indented line beginning with An optional table caption non indented text may immediately follow the table Rows may contain single line or multiple line cells Each line of cell text is separated from the adjacent cell by the pipe character may be used in the cell text if quoted The last is only used
21. e parser In princip parser directly Parser parser macros will not be available inputFile E apt Plexus lookup NUrrSE ys le you could instantiate the new AptParser but then some special features like You could also use the Doxia Converter Tool to parse a given file dir to another file dir 16 1 2 Generating documents The snippet below gives a simple example of how to generate a document using the Doxia Sink API 2015 The Apache Software Foundation ALL RIGHTS RESERVED 16 Using the Sink API Generate a simple document and emit it into the specified sink The sink is flushed but not closed param sink The sink to receive th vents tg public static void generate Sink sink sink head sink title sink text Title sink title_ sink author sink text Author sink author_ sink date sink text Date sink date_ sink head_ sink body sink paragraph j sink text A paragraph of text sink paragraph_ sink sectionl sink sectionTitlel sink text Section title sink sectionTitlel_ sink paragraph sink text Paragraph in section sink paragraph_ sink sectionl_ sink body_ sink flush A more complete example that also shows the canonical order of events to use when generating a document can be found in the Doxia SinkTestDocument class
22. gs Xdoc was the primary documentation format in Maven 1 Maven 2 largely replaced this by Apt but xdoc is still supported Historically the xdoc format can be traced back to the Anakia format as once used by the Apache Jakarta project The Maven 1 Xdoc plugin introduced a few additions to the Anakia format they are highlighted in the plugin documentation 9 2 2 The XDoc xsd The full documentation is available here 9 2 3 XDoc Sample The following is a sample XDoc document 2015 The Apache Software Foundation ALL RIGHTS RESERVED 9 Xdoc Format 27 lt xml version 1 0 encoding UTF 8 gt lt document xmlns http maven apache org XDOC 2 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http maven apache org XDOC 2 0 http maven apache org xsd lt properties gt lt title gt Page Title lt title gt lt author email user company com gt John Doe lt author gt lt properties gt lt Optional HEAD element which is copied as is into the XHTML lt head gt element lt head gt lt meta gt lt head gt lt body gt lt The body of the document contains a number of sections lt section name section 1 gt lt Within sections any XHTML can be used gt lt p gt Hi lt p gt lt in addition to XHTML any number of subsections can be within a section lt subsection name subsection 1 gt lt p gt Subsection lt p gt
23. h Paragraphs other than the title block may appear before the first section line 1 line 2 Paragraph 1 Paragraph 1 line 1 line 2 Paragraph 2 Paragraph 2 Paragraphs are indented They have already been described in the Document structure section 6 Section Sections are created by inserting section titles into the document Simple documents need not contain sections Section title Sub section title Sub sub section title Sub sub sub section title Sub sub sub sub section title Section titles are not indented A sub section title begins with one asterisk a sub sub section title begins with two asterisks and so forth up to four sub section levels 6 List List item 1 List item 2 Paragraph contained in list item 2 Sub list item 1 Sub list item 2 List item 3 List items are indented and begin with a asterisk Plain paragraphs more indented than the first list item are nested in that list Displays such as tables not indented are always nested in the current list To nest a list inside a list indent its first item more than its parent list To end a list add a paragraph or list item less indented than the current list Section titles always end a list Displays cannot end a list but the pseudo element may be used to force the end of a list 2015 The Apache Software Foundation
24. he maven doxia lt groupId gt lt artifactId gt doxia modules lt artifactId gt lt version gt 1 0 lt version gt lt Latest releas gt lt parent gt lt modelVersion gt 4 0 0 lt modelVersion gt lt artifactId gt doxia module my lt artifactId gt lt name gt Doxia MY Module lt name gt lt project gt Secondly you should implement some Doxia classes e MyParser class import org apache maven doxia parser AbstractParser kk plexus component role org apache maven doxia parser Parsex role hint my public class MyParser extends AbstractParser e MyParseException class optional import org apache maven doxia parser ParseException public class MyParseException extends ParseException e MySiteModule class optional will be used by doxia sitetools 2015 The Apache Software Foundation ALL RIGHTS RESERVED 14 Create a Doxia Module e MySink class e MySinkFactory class import org apache maven doxia module site AbstractSiteModule El public class MySiteModule extends AbstractSiteModule import org apache maven doxia sink SinkAdapter public class MySink extends SinkAdapter import org apache maven doxia sink SinkFactory plexus component role org apache maven doxia sink SinkFact y public class MySinkFactory extends SinkFactory 14 1 1 References e Doxia Modules Guide e Doxia Macros Guide e D
25. ill Defined term 1 of definition list Defined term 2 of definition list Verbatim text 2015 The Apache Software Fowndatigng ALL RIGHTS RESERVED instead of suppresses the box around verbatim text 7 Doxia Apt Enhancements 20 Doxia Apt Enhancements 7 1 Enhancements to the APT format In the following we provide a list of differences enhancements to the original APT format that were incorporated in Doxia Note that the original specification still applies to Doxia 1 0 used e g by Maven 2 0 x the changes outlined here only apply from Doxia 1 1 used by Maven gt 2 1 x Apart from some exceptions these differences are usually backwards compatible i e any document that gets correctly processed by Aptconvert should also be a valid Doxia input file and lead to identical results when processed by a Doxia parser e Paragraphs in list items e Table header cells e Multi lines cells in table e Anchors e Links e Figure extensions 7 1 1 Paragraphs in list items Contrary to the original APT parser the Doxia APT parser does not put list items within paragraphs Eg the example given in the APT guide List item 1 will for instance produce the following html lt li gt List item 1 lt li gt To get the same result as aptconvert use List item 1 which will produce lt li gt lt p gt List item 1 lt p gt lt 1li gt 7 1 2 Table header
26. ings START SNIPPET and myia where myid is the id of the snippet is a start demarcator and similarly END SNIPPET myid denotes the end of the snippet to include For example e Start and end snippets in a Java file public class MyClass START SNIPPET myid public static void main String args throws Exception END SNIPPET myid e Start and end snippets in a XML file lt project gt lt build gt lt plugins gt lt START SNIPPET myid gt lt plugin gt lt plugin gt lt END SNIPPET myid gt lt plugins gt lt build gt lt project gt The id of the snippet to include If omitted the whole file url will be included since Doxia 1 1 The path of the URL to include file The path of the file to include since doxia 1 0 alpha 9 verbatim If the content should be output as verbatim escaped text If this is set to false then the content of the snippet will not be escaped This means that you can use it like Server Side Includes on a webserver Default value is t rue 2015 The Apache Software Foundation ALL RIGHTS RESERVED 11 Doxia Macros Guide 36 encoding The encoding of the file to read since Doxia 1 6 If omitted the default JVM encoding will be used 11 1 3 TOC Macro The TOC macro prints a Table Of Content of a document It is useful if you have se
27. ion gt 18 1 5 Empty Generated Page After running mvn site using your Maven reporting plugin you see that the generated page is empty Be sure that the the code calls sink close 2015 The Apache Software Foundation ALL RIGHTS RESERVED 19 19 External Resources 54 External Resources 19 1 External Resources 19 1 1 Extensions Doxia Include Macro Juergen Kellerer 19 1 2 Articles Quick and dirty typesetting with linux com Scott Nesbitt APT Lightweight markup language wikipedia org 2 Simple Ascii Based Text Formats project knowledgeforge net 2 19 1 3 Tools APT Editor Eclipse plugin Mathieu Avoine nb doxia support NetBeans plugin Allan Lykke Christensen 19 2 Related External Projects e XWiki which uses Doxia in its rendering e Mylyn WikiText originally known as Textile J 2015 The Apache Software Foundation ALL RIGHTS RESERVED
28. ist lt p gt lt ul gt lt li gt item 1 lt 1i gt lt li gt item 2 lt 1i gt lt ul gt lt p gt of things to do lt p gt Typical block level elements are list elements lt table gt lt source gt lt div gt lt p gt and lt pre gt 9 3 2 Put inline elements inside block level elements Wrong lt section name Downloads gt lt a href downloads html gt Downloads lt a gt lt section gt Correct lt section name Downloads gt lt p gt lt a href downloads html gt Downloads lt a gt lt p gt lt section gt Typical inline elements are lt a gt lt strong gt lt code gt lt font gt lt br gt and lt img gt 2015 The Apache Software Foundation ALL RIGHTS RESERVED 9 Xdoc Format 9 3 3 Right order of elements in lt properties gt The lt title gt element has to come before lt author gt 9 3 4 Dont put lt source gt inside paragraphs Wrong lt p gt The following command executes the program lt source gt java jar CoolApp jar lt source gt lt p gt Correct lt p gt The following command executes the program lt p gt lt source gt java jar CoolApp jar lt source gt However you may put lt source gt elements inside list items or table rows 2015 The Apache Software Foundation ALL RIGHTS RESERVED 30 10 10 Doxia Modules Guide 31 Doxia Modules Guide 10 1 Doxia Modules Guide
29. lt subsection gt lt section gt lt section name other section gt lt You can also include preformatted source blocks in the document gt lt source gt code line 1 code line 2 lt source gt lt section gt lt body gt lt document gt 9 2 4 The lt source gt tag lt source gt tags are special Anything within this tag is rendered within a verbatim box as pre formatted text If you are embedding other XML XHTML markup within the source tags then you need to place a CDATA section within the source section Example lt source gt lt CDATA content here lt a href gt foo lt a gt gt lt source gt 2015 The Apache Software Foundation ALL RIGHTS RESERVED 9 Xdoc Format 28 9 2 5 Additional sectioning Doxia will produce lt h2 gt and lt h3 gt headings for lt section gt and lt subsection gt elements respectively It is therefore perfectly valid to put some sub headings lt h4 gt lt h5 gt lt h6 gt inside a subsection For instance lt h4 gt A subsubsection lt h4 gt will produce 9 2 5 1 A subsubsection 9 2 6 Referencing sections and subsections The core doxia modules do not construct anchors from section subsection names If you want to reference a section you should either provide an explicit anchor lt a name Sectionl gt lt section name Section gt lt a name SubSectionl gt lt subsection name SubSection gt l
30. lt finalName gt project build finalName lt finalName gt lt createDependencyReducedPom gt false lt createDependencyReducedPom gt lt keepDependenciesWithProvidedScope gt true lt keepDependenciesWithProvided lt transformers gt lt transformer implementation org apache maven plugins shade resourc lt transformers gt lt artifactSet gt lt includes gt lt include gt org apache maven doxia doxia sink api lt include gt lt include gt org apache maven doxia doxia logging api lt include gt lt includes gt lt artifactSet gt lt configuration gt lt execution gt lt executions gt lt plugin gt lt plugins gt lt build gt lt project gt 2015 The Apache Software Foundation ALL RIGHTS RESERVED 17 Integration With Maven 17 1 2 Maven 2 1 x Doxia 1 1 API and Logging are embedded in Maven 2 1 x your Maven reporting plugin is directly compatible with 2 1 x 17 2 Common Bugs and Pitfalls Please read the Doxia Issues page 2015 The Apache Software Foundation ALL RIGHTS RESERVED 51 18 18 Issues Gotchas 52 Issues amp amp Gotchas 18 1 Doxia Issues Gotchas This document collects some infos about specific issues and gotchas when working with Doxia Please check also the Frequently Asked Questions Apt anchors and links TOC macro issues Verbatim blocks not boxed Figure sink events Empty Generated Page 18 1 1 Apt anchors and links Usi
31. my myParam myValue lt my is the macro name defined by role hint gt e XDoc lt macro name my gt lt my is the required macro name defined by role hint gt lt param name myParam value myValue gt lt macro gt 15 1 1 References e Doxia Modules Guide e Doxia Macros Guide e Doxia API Reference e Doxia Sitetools API Reference 2015 The Apache Software Foundation ALL RIGHTS RESERVED 16 16 Using the Sink API Using the Sink API 16 1 Using the Doxia Sink API e Transforming documents e Generating documents e Passing attributes to Sink events e Avoid sink rawText e How to inject javascript code into HTML e References 16 1 1 Transforming documents 46 Doxia can be used to transform an arbitrary input document to any supported output format The following snippet shows how to use a Doxia Parser to transform an apt file to html File userDir new File System getProperty File inputFile new File userDir test apt File outputFile new File userDir SinkFactory sinkFactory SinkFactory lookup test html user dir i y SinkFactory ROLE html Pl Sink sink sinkFactory createSink outputFil getParentFil outputFile getNam Parser parser AptParser lookup Parser ROL Reader reader ReaderFactory newReader parser parse reader sink It is recommended that you use Plexus to look up th
32. n Doxia XML files with XSD 7 How to integrate Doxia 1 1 with Maven How to handle style in the APT markup language APT does not support style If you need more control you should use xdoc instead top How to export in PDF There are two modules available that can be used to generate pdf output an iText module that uses the iText framework and a FO module that can be used e g in conjunction with Apache FOP to generate a pdf Unfortunately the iText team has discontinued the XML to PDF functionalities so probably only the fo module is going to be supported in the future For Maven there is a pdf plugin available top Is it possible to create a book 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 The Doxia Book code is still limited but fully functional See Writing Books in Doxia for more information top Why XML based sinks don t generate nicely formatted documents We decided to keep pretty printing out of the core modules So XML based sinks like Xdoc or XHTML are intentionally unformatted You could always do this after the document generation or directly by creating a specialized end user sink see DOXIA 255 top Where are the Maven Doxia XSD schemas files The Doxia XSD files are located here Xdoc XSD 2 0 http maven apache org xsd xdoc 2 0 xsd 2015 The Apache S
33. nderscore _ e Any characters not matching the above pattern are stripped Note in particular that case is preserved in this conversation and that APT anchors and links are case sensitive So the anchor for the section title in the previous example would be Anchors_for_section_titles 7 1 5 Links In Doxia 1 1 the notion of a local link was introduced in addition to internal links and external links 2015 The Apache Software Foundation ALL RIGHTS RESERVED 7 Doxia Apt Enhancements 22 e An internal link is a link to an anchor within the same source document In the APT format used by Doxia 1 1 internal links have to be valid Doxia ids as specified in the anchors section above Note in particular that internal links in APT do not start with e A local link is a link to another document within the same site In the APT format used by Doxia 1 1 local links have to start with either or to distinguish them from internal links E g doc standalone html Standalone is not valid it should be doc standalone html Standalone Note in particular that the following link standalone html Standalone will be interpreted as an internal link dots are valid characters in anchor names Since you most likely meant to link to another source document you should again prepend a e An external link is a link that is neither local nor internal An external link should be a valid URI Anchors are always tra
34. ng Doxia 1 1 you may see a lot of warnings when processing old Apt source files and WARNING Apt Parser Ambiguous link doxia apt html If this is a local link p WARNING Apt Parser Modified invalid link references doxia apt html The reason is that in Apt links to other source documents have to start with either or to distinguish them from internal links Please read the sections on anchors and links in our Apt guide Note in particular that internal links in Apt do not start with You should pay attention to these warnings since your links will most likely be broken Unfortunately the warning message cannot indicate the source file with the broken link see eg MPDF 11 however if you run in DEBUG mode eg invoke maven with the x switch you can see which source document is being parsed when the warning is emitted 18 1 2 TOC macro issues There was a particular bug in the TOC macro in version 1 0 that has been fixed but leads to a backward incompatibility in some cases If you have specified the sect ion parameter in your TOC as for instance toc section 1 fromDepth 1 toDepth 1 then the generated TOC is probably different from the result with Doxia 1 0 In Doxia 1 1 depth 1 is section depth 2 is sub section etc as documented in the macro guide 18 1 3 Verbatim blocks not boxed There was a particular bug in Doxia 1 0 that verbatim blocks were always b
35. ns have been kept binary compatible If you are a Maven Plugin developer and you plan to switch to Doxia 1 1 please read this Maven Integration page to understand how to integrate correctly Doxia 1 1 with Maven 2015 The Apache Software Foundation ALL RIGHTS RESERVED 5 References References 5 1 Doxia Markup Languages References The following table gives an overview of the markup languages currently supported by Doxia e if a Parser is available for a given format it means that you can write your documentation in this language and Doxia can generate output from it e if a Sink is available it means you can generate output in this format The source directory is the directory under which Maven expects source documents in this format e g src site apt for Apt the file extension is the default file extension and the parser id is gives the unique identifier that is used by plexus to lookup the corresponding component Apt Confluence Simplified DocBook FML iText EO LaTex Markdown RTF TWiki Xdoc 2015 The Apache Software Foundation Almost Plain Text Confluence Enterprise Wiki Simplified DocBook XML Standard FAQ Markup Language Text PDF Library XSL formatting objects XSL FO LaTeX typesetting system Markdown markup language Microsoft Rich Text Format TWiki Structured Wiki XML Documentatic Format o Ge PpP o E E amp amp ap
36. nslated to a valid id including escaping In some situation this can cause issues especially when referring to a javadoc link Since Doxia 1 4 there is support for literal anchors by using 2 hashed instead of 1 This implies that the writer is responsible for using the right URL encoding apidocs groovyx net http ParserRegistry html parseText org apache http HttpRes 7 1 6 Figure extensions Contrary to the original APT format a figure name has to be given fully with extension For instance home joe docs mylogo jpeg Figure caption 2015 The Apache Software Foundation ALL RIGHTS RESERVED 8 FML Format 23 FML Format 8 1 The FML format 8 1 1 Overview An fml FAQ Markup Language is an XML document conforming to a small and simple set of tags The format was first used in the Maven 1 version of the FAQ plugin 8 1 2 The FML format The full documentation is available at here 8 1 3 FML Sample The following is a sample FML document 2015 The Apache Software Foundation ALL RIGHTS RESERVED 8 FML Format 24 lt xml version 1 0 encoding UTF 8 gt lt faqs xmlns http maven apache org FML 1 0 1 xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http maven apache org FML 1 0 1 http maven apache org xsd title Frequently Asked Questions toplink false gt lt part id general gt lt title gt General lt title gt lt faq id whats
37. oftware Foundation ALL RIGHTS RESERVED 3 FAQ FML XSD 1 0 1 http maven apache org xsd fml 1 0 1 xsd Book XSD 1 0 http maven apache org xsd book 1 0 0 xsd Document XSD 1 0 1 http maven apache org xsd document 1 0 1 xsd Decoration XSD 1 0 http maven apache org xsd decoration 1 0 0 xsd Your favorite IDE probably supports XSD schema s for Xdoc and FML files You need to specify the following lt document xmlns http maven apache org XDOC 2 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http maven apache org XDOC 2 0 http lt document gt maven apache org lt fags xmlns http maven apache org FML 1 0 1 xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http maven apache org FML 1 0 1 http maven apache org lt faqs gt lt book xmlns http maven apache org BOOK 1 0 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http maven apache org BOOK 1 0 0 ht lt book gt tp maven apache or lt document xmlns http maven apache org DOCUMENT 1 0 1 xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLlLocation http maven apache org DOCUMENT 1 0 outputName gt lt document gt http maven apache lt project xmlns http maven apache org DECORATION 1 0 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http m
38. or each item in order to keep the APT source document readable Defined term 1 of definition list 2 Defined term 2 of definition list 2 A definition list item begins with a defined term text between square brackets 6 Verbatim text Verbatim text preformatted escaped A verbatim block is not indented It begins with a non indented line containing at least 3 dashes It ends with a similar line instead of draws a box around verbatim text Like in HTML verbatim text is preformatted Unlike HTML verbatim text is escaped inside a verbatim display markup is not interpreted by the APT processor 6 Figure Figure name Figure caption A figure block is not indented It begins with the figure name between square brackets The figure name is optionally followed by some text the figure caption The figure name is the pathname of the file containing the figure but without an extension Example if your figure is contained in home joe docs mylogo jpeg the figure name is home joe docs mylogo Change If the figure name comes from a relative pathname recommended practice rather than from an absolute pathname this relative pathname is taken to be relative to the directory of the current APT document a la HTML rather than relative to the current working directory Why not leave the file extension in the figure name This is better explained by an example You nee
39. oxed If after an upgrade to Doxia 1 1 you find that your blocks are not boxed anymore check that you actually start your verbatim block with and not 18 1 4 Figure sink events Doxia distinguishes between figures which are block level elements and images or icons which are in line elements For instance the following sequence of sink events 2015 The Apache Software Foundation ALL RIGHTS RESERVED 18 Issues Gotchas 53 sink figu sink figu sink figu sink figu sink figu re null reGraphics figure png null reCaption null sink text Figure caption reCaption_ re_ null should output the equivalent of this html snippet lt div gt lt div class figure gt lt p gt lt img src figure png gt lt p gt lt p gt Figure caption lt p gt while the figureGraphics the lt img gt tag in case of html event alone can be used to generate an in line image i e just 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 lt img src figure png alt Figure capt
40. oxia 1 3 Markdown is a widespread Markup language References e Official Markdown project at Daring Fireball 10 1 9 RTF RTF is a proprietary document file format References e Microsoft Office Word 2007 Rich Text Format RTF Specification e RTF Cookbook 10 1 10 TWiki since Doxia 1 1 TWiki is a structured wiki References e TWiki Text Formatting 10 1 11 XDoc XDoc is a generic format for document into a styled HTML document References e XDoc Reference 10 1 12 XHTML XHTML is a markup language with the same expressions as HTML but also conforms to XML syntax 2015 The Apache Software Foundation ALL RIGHTS RESERVED 10 Doxia Modules Guide References e HTML and XHTML Quick Reference Charts Head and Body Markup e XHTML 1 0 Specification 2015 The Apache Software Foundation ALL RIGHTS RESERVED 33 11 11 Doxia Macros Guide 34 Doxia Macros Guide 11 1 Doxia Macros Guide The Doxia Core includes macro mechanisms to facilitate the documentation writing Macros are currently only supported for the standard Maven input formats APT and Xdoc Support in FML files will be added in a future version of Doxia Macros are not and probably will never be supported by Confluence Docbook Twiki and XHTML modules A macro in an APT source file is a non indented line that looks like this macro_name paraml valuel param2 value2 An Xdoc macro has the following syntax lt m
41. oxia API Reference e Doxia Sitetools API Reference 2015 The Apache Software Foundation ALL RIGHTS RESERVED 43 ory plexus component role org apache maven doxia module site SiteModule role role hint 1 15 15 Create a Doxia Macro Create a Doxia Macro 15 1 Create a New Doxia Macro 44 You need to add the following plugin configuration to generate the correct Plexus component xml file for the project containing your macro lt project gt lt build gt lt plugins gt lt plugin gt lt groupId gt org codehaus plexus lt groupld gt lt artifactId gt plexus maven plugin lt artifactId gt lt executions gt lt execution gt lt goals gt lt goal gt descriptor lt goal gt lt goals gt lt execution gt lt executions gt lt plugin gt lt plugins gt lt build gt lt project gt You should implement the AbstractMacro class import org apache maven doxia macro AbstractMacro uf public class MyMacro extends AbstractMacro public void execute Sink sink MacroRequest request on throws MacroExecutionException String myValue String request getParameter plexus component role org apache maven doxia macro Macro role hint my myParam To use it you need to write the following markups e APT 2015 The Apache Software Foundation ALL RIGHTS RESERVED 15 Create a Doxia Macro 45 S
42. ry event without making special assumptions about the receiving Sink Depending on the parameters a Sink may decide whether or not to process the event emit it as raw text as a comment log it etc The correct way to generate the above lt div gt block is now Sink atts sink sink sink Read the javadocs of the unknown method in the Sink interface and the XhtmlbaseSink for EventAttributeSet a addAttribute Sink unknown div new Object new Integer HtmlMarkup TAG_TYP text A text with unknown div new Object new Integer HtmlMarkup TAG_TYPE tts new SinkEventAttributeSet EventAttributes STYLE cool a cool style ea START END information on the method parameters Note that an arbitrary sink may be expected to ignore the unknown event completely In general the rawText method should be avoided alltogether when emitting events into an arbitrary Sink 16 1 5 How to inject javascript code into HTML Related to the above here is the correct way of injecting a javascript snippet into a Sink 2015 The Apache Software Foundation ALL RIGHTS RESERVED Ji Ji null atts y 16 Using the Sink API 49 the javascript code is emitted within a commented CDATA section so we have to start with a newline and comment the CDATA closing in the end note that the sink will replace the newline by the system EO
43. s 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 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 The current version of Doxia base framework is 1 6 1 1 1 Maven Doxia Enhancements e Upgrading from earlier versions 1 1 2 Brief History Based on the now defunct Aptconvert project developed by Xmlmind Doxia was initially hosted by Codehaus to become a sub project of Maven early in 2006 1 1 3 Main Features e Developed in Java e Support of several markup formats APT Almost Plain Text Confluence Simplified DocBook Markdown FML FAQ Markup Language FO iText LaTeX RTF TWiki XDoc popular in Apache land XHTML e Easy to learn the syntax of the supported markup formats e Macro support e No need to have a corporate infrastructure like wiki to host your documentation e Extensible framework e Site Tools extension for site or document rendering e Additional Tools like Doxia Converter IDE integration 1 1 4 Doxia Reference Pages See Doxia Markup Languages References page for a listing of all supported markups for each format 2015 The Apache Software Foundation ALL RIGHTS RESERVED 2
44. t subsection gt lt section gt or use an id attribute for section and subsections note that id s have to be unique within one xdoc source document lt section name Section id Sectionl gt lt subsection name SubSection id SubSectionl gt lt subsection gt lt section gt Note that this differs from previous behavior where anchors were constructed from section subsection names replacing special characters by underscores This behavior presents two shortcomings e If two sections or subsections have identical names within one source document you will get an ambiguity when referencing them Also the resulting html document will not be valid XHTML For other output formats eg pdf it might even be impossible to generate the target document e For long section titles this leads to rather cumbersome anchor names If automatic anchor generation is desired for a particular output format it should be implemented overridden by the corresponding low level Sink 9 3 Validation 2015 The Apache Software Foundation ALL RIGHTS RESERVED 9 Xdoc Format Doxia is able to validate your xdoc files as described here Here is a list of common mistakes to be aware of 9 3 1 Don t nest block level elements Wrong lt p gt Here s a list lt ul gt lt li gt item 1 lt 1i gt lt li gt item 2 lt 1i gt lt ul gt of things to do lt p gt Correct lt p gt Here s a l
45. t apt de confluenc conf luenc amp docbook xml fml fml e E E markdown md e twiki twiki E zdoe xml E ALL RIGHTS RESERVED doxia apt module apt doxia confluence module confluenc dora doc book module docbook simple doxia fml module izau dotas module itext doxia module BO doxia module latex doxia markdown module markdown doras module TEAT doxia twiki module twiki doxia xdoc module OS 5 References XHTML Extensible ai xhtml xhtml doxia xhtml Hypertext sd ssl module Markup xhtml Language Note some modules are not included per default with the site plugin Have a look at the available modules here http repo maven apache org maven2 org apache maven doxia If you need to add module for the maven site plugin simply add it as a dependency of the plugin lt plugin gt lt groupId gt org apache maven plugins lt grouplId gt lt artifactId gt maven site plugin lt artifactId gt lt version gt 3 2 lt version gt lt dependencies gt lt dependency gt lt groupId gt org apache maven doxia lt groupId gt lt artifactId gt doxia module markdown lt artifactId gt lt version gt 1 3 lt version gt lt dependency gt lt dependencies gt lt plugin gt Since Doxia 1 1 Since Doxia 1 3 2015 The Apache Software Foundation ALL RIGHTS RESERVED 6 Apt Format 10 Apt
46. t chapters gt lt chapter gt lt id gt bind lt id gt lt title gt Bindings lt title gt lt sections gt lt section gt lt id gt bindings lt id gt lt section gt lt section gt lt id gt aegis binding lt id gt lt section gt lt section gt lt id gt castor lt id gt lt section gt lt sections gt lt chapter gt lt chapter gt lt id gt transports lt id gt lt title gt Transports lt title gt lt sections gt lt section gt lt id gt transport and channel api lt id gt lt section gt lt section gt lt id gt http transport lt id gt lt section gt lt section gt lt id gt jms transport lt id gt lt section gt lt section gt lt id gt local transport lt id gt lt section gt lt sections gt lt chapter gt lt chapters gt lt book gt pa pn apache org xsd 12 1 3 Configuring Doxia Book Maven Plugin This example illustrates how to configure the Doxia Book Maven Plugin It will render the book in three different formats By default the output will be under target generated site lt format gt lt book id gt The currently supported format ids are xdoc pdf latex rtf xhtml doc book A sample pom xml is given below 2015 The Apache Software Foundation ALL RIGHTS RESERVED 12 Writing Books lt plugin gt lt groupld gt org apache maven doxia lt groupId gt lt artifactlid gt doxia book maven pl
47. tage 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 page 2015 The Apache Software Foundation ALL RIGHTS RESERVED 12 12 Writing Books 38 Writing Books 12 1 Introduction Doxia allows you to write books like user manuals and guides in any format supported by Doxia Combined with the Doxia Book Maven you are able to include the manuals directly in your generated site with links to the off line friendly formats like XDoc PDF RTF and LaTeX The Xdoc output which has been rendered into this site can be viewed here The generated PDF is here and the generated RTF here 12 1 1 How It Works The only thing you need in addition to the content files itself is a simple book descriptor which is used to specify the ordering of the sections and the names for the chapters See The Book Descriptor Reference for a reference to the descriptor 12 1 2 Creating a Book Descriptor An XML file is used to describe the layout of the book A sample is given below 2015 The Apache Software Foundation ALL RIGHTS RESERVED 12 Writing Books 39 lt book xmlns http maven apache org B00K 1 0 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http maven apache org BOOK 1 0 0 http mave lt id gt doxia example book lt id gt lt title gt XFire User Manual lt title gt l
48. ugin lt artifactld gt lt version gt 1 3 SNAPSHOT lt version gt lt executions gt lt execution gt lt phase gt pre site lt phase gt lt goals gt lt goal gt render books lt goal gt lt goals gt lt execution gt lt executions gt lt configuration gt lt books gt lt book gt lt directory gt content books example book lt directory gt lt descriptor gt content books example book xml lt descriptor gt lt formats gt lt format gt lt id gt latex lt id gt lt format gt lt format gt lt id gt xdoc lt id gt lt format gt lt format gt lt id gt pdf lt id gt lt format gt lt format gt lt id gt rtf lt id gt lt format gt lt formats gt lt book gt lt books gt lt configuration gt ct lt plugin gt 2015 The Apache Software Foundation ALL RIGHTS RESERVED 40 13 Developer Centre 41 13 Developer Centre 13 1 Doxia Developers Centre This documentation centre is for those that are developing Doxia modules or macro Currently you can find information on the following topics e Creating Doxia Modules e Creating Doxia Macros e Using the Doxia Sink API 2015 The Apache Software Foundation ALL RIGHTS RESERVED 14 Create a Doxia Module 42 14 Create a Doxia Module 14 1 Create a New Doxia Module First you need to create a POM with doxia modules as parent lt project gt lt parent gt lt groupId gt org apac
49. veral sections and subsections in your document For instance in an APT file you could write toc section 2 fromDepth 2 toDepth 3 This displays a TOC for the second section in the document including all subsections depth 2 and sub subsections depth 3 Note that in Doxia apt section titles are not implicit anchors see Enhancements to the APT format so you need to insert explicit anchors for links to work In a xdoc file it will be lt macro name toc gt lt param name section value 2 gt lt param name fromDepth value 0 gt lt param name toDepth value 4 gt lt macro gt section Display a TOC for the specified section only or all sections if 0 Positive int not mandatory O by default fromDepth Minimum section depth to include in the TOC sections are depth 1 sub sections depth 2 etc Positive int not mandatory O by default toDepth Maximum section depth to include in the TOC Positive int not mandatory 5 by default From Doxia 1 1 1 on you may also specify any of the html base attributes i e any of id class style lang title as parameters e g s toc class myTOC This can be used for styling the TOC via css 11 1 4 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 In

Apache Maven Doxia - The Apache Software Foundation!

Contents

Download Pdf Manuals

Related Search

Related Contents