Preparing to write some real guide ...
This commit is contained in:
Trustin Lee
parent
b14b4c8714
commit
77b23c97e2
5
pom.xml
5
pom.xml
@ -267,11 +267,6 @@
|
||||
</includes>
|
||||
</imageResource>
|
||||
<formats>
|
||||
<format>
|
||||
<formatName>pdf</formatName>
|
||||
<stylesheetResource>classpath:/xslt/org/jboss/main-pdf.xsl</stylesheetResource>
|
||||
<finalName>${project.artifactId}.pdf</finalName>
|
||||
</format>
|
||||
<format>
|
||||
<formatName>html</formatName>
|
||||
<stylesheetResource>classpath:/xslt/org/jboss/main-html.xsl</stylesheetResource>
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Binary file not shown.
|
Before Width: | Height: | Size: 48 KiB |
File diff suppressed because it is too large
Load Diff
Binary file not shown.
|
Before Width: | Height: | Size: 45 KiB |
File diff suppressed because it is too large
Load Diff
Binary file not shown.
|
Before Width: | Height: | Size: 60 KiB |
File diff suppressed because it is too large
Load Diff
Binary file not shown.
|
Before Width: | Height: | Size: 56 KiB |
@ -1,45 +1,32 @@
|
||||
<?xml version='1.0' encoding='ISO-8859-1'?>
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN" "../support/support/docbook-dtd/docbookx.dtd" [
|
||||
<!ENTITY introduction SYSTEM "module/introduction.xml">
|
||||
<!ENTITY howto SYSTEM "module/howto.xml">
|
||||
<!ENTITY styles SYSTEM "module/styles.xml">
|
||||
<!ENTITY introduction SYSTEM "module/introduction.xml">
|
||||
<!ENTITY architecture SYSTEM "module/architecture.xml">
|
||||
<!ENTITY codec SYSTEM "module/codec.xml">
|
||||
<!ENTITY threading SYSTEM "module/threading.xml">
|
||||
<!ENTITY security SYSTEM "module/security.xml">
|
||||
<!ENTITY transport SYSTEM "module/transport.xml">
|
||||
<!ENTITY appendix SYSTEM "module/appendix.xml">
|
||||
]>
|
||||
<book lang="en">
|
||||
<bookinfo>
|
||||
<title>How to use the JBoss DocBook system</title>
|
||||
<subtitle>A guide for content developers</subtitle>
|
||||
<releaseinfo>2.0</releaseinfo>
|
||||
<title>The Netty Project 3.0 User Guide</title>
|
||||
<subtitle>The proven approach for rapid network application development</subtitle>
|
||||
<releaseinfo>$Rev$, $Date$</releaseinfo>
|
||||
</bookinfo>
|
||||
|
||||
<toc/>
|
||||
<preface id="target" revision="1">
|
||||
<title>Target Audience</title>
|
||||
<para>All JBoss.org documentation content developers and style developers
|
||||
should read this document. You should also read this if you want to
|
||||
build JBoss.org DocBooks from the <ulink url="http://anonsvn.jboss.org">public SVN repositories</ulink>. </para>
|
||||
</preface>
|
||||
<preface id="preface" revision="1">
|
||||
|
||||
<preface id="preface">
|
||||
<title>Preface</title>
|
||||
<para>This document introduces the unified DocBook system for JBoss.org
|
||||
documentation based on Maven2. Using this system provides the following benefits:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>The DocBook libraries and all other dependencies are stored in Maven plugins located in the <ulink url="http://repository.jboss.org/maven2">JBoss public maven repository</ulink>. This allows the entire build environment to be automatically downloaded and configured from just a single <literal>pom.xml</literal> file stored in a project's <literal>docs</literal> directory.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Styles are also stored in Maven plugins so that they can be managed from a central location. This allows updates to be automatically downloaded when new designs are created or bugs are fixed.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>It provides a default style based on the JBoss.org community-driven theme that looks clean, fresh and modern.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Custom styles can easily be created for individual projects, or groups of related projects, to cater for different requirements. For example some projects may have their own logos or wish to have collapsable menus at the start of each chapter. </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The build process is simplified and standardized. Just
|
||||
follow the instructions in this guide to setup your <literal>docs</literal>
|
||||
directory and copy a very simple <literal>pom.xml</literal> file. </para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para> If you have any questions, please feel free to contact <ulink url="mailto:mark.newton@jboss.org">Mark Newton</ulink> (Content Lead) for more information. </para>
|
||||
<para>To be written...</para>
|
||||
</preface>
|
||||
&introduction;&howto;&styles;</book>
|
||||
|
||||
&introduction;
|
||||
&architecture;
|
||||
&codec;
|
||||
&threading;
|
||||
&securty;
|
||||
&transport;
|
||||
&appendix;
|
||||
</book>
|
||||
|
||||
5
src/docbook/module/appendix.xml
Normal file
5
src/docbook/module/appendix.xml
Normal file
@ -0,0 +1,5 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<chapter id="appendix">
|
||||
<title>Additional Resources</title>
|
||||
<para>To be written...</para>
|
||||
</chapter>
|
||||
5
src/docbook/module/architecture.xml
Normal file
5
src/docbook/module/architecture.xml
Normal file
@ -0,0 +1,5 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<chapter id="architecture">
|
||||
<title>Architecture & Road Map</title>
|
||||
<para>To be written...</para>
|
||||
</chapter>
|
||||
5
src/docbook/module/codec.xml
Normal file
5
src/docbook/module/codec.xml
Normal file
@ -0,0 +1,5 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<chapter id="codec">
|
||||
<title>Encoders and Decoders</title>
|
||||
<para>To be written...</para>
|
||||
</chapter>
|
||||
@ -1,179 +0,0 @@
|
||||
<?xml version='1.0' encoding='UTF-8'?><chapter id="howto">
|
||||
<title>How to develop content for JBoss DocBook</title>
|
||||
<section>
|
||||
<title>Install Maven2</title>
|
||||
<para>Before you can start to build DocBook documents you first need to install and configure <ulink url="http://maven.apache.org/">Maven2</ulink>. At the time of writing Maven 2.0.8 is the latest released version that has been tested and found to work correctly. System requirements and download instructions can be found <ulink url="http://maven.apache.org/download.html">here</ulink>.</para>
|
||||
<para>In order for Maven to reference the JBoss public maven repository you will need to create a <literal>~/.m2/settings.xml</literal> file with the following contents:</para>
|
||||
<programlisting><settings>
|
||||
<profiles>
|
||||
<profile>
|
||||
<id>jboss.repository</id>
|
||||
<activation>
|
||||
<property>
|
||||
<name>!jboss.repository.off</name>
|
||||
</property>
|
||||
</activation>
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>snapshots.jboss.org</id>
|
||||
<url>http://snapshots.jboss.org/maven2</url>
|
||||
<snapshots>
|
||||
<enabled>true</enabled>
|
||||
</snapshots>
|
||||
</repository>
|
||||
<repository>
|
||||
<id>repository.jboss.org</id>
|
||||
<url>http://repository.jboss.org/maven2</url>
|
||||
<snapshots>
|
||||
<enabled>false</enabled>
|
||||
</snapshots>
|
||||
</repository>
|
||||
</repositories>
|
||||
<pluginRepositories>
|
||||
<pluginRepository>
|
||||
<id>repository.jboss.org</id>
|
||||
<url>http://repository.jboss.org/maven2</url>
|
||||
<snapshots>
|
||||
<enabled>false</enabled>
|
||||
</snapshots>
|
||||
</pluginRepository>
|
||||
<pluginRepository>
|
||||
<id>snapshots.jboss.org</id>
|
||||
<url>http://snapshots.jboss.org/maven2</url>
|
||||
<snapshots>
|
||||
<enabled>true</enabled>
|
||||
</snapshots>
|
||||
</pluginRepository>
|
||||
</pluginRepositories>
|
||||
</profile>
|
||||
</profiles>
|
||||
</settings></programlisting>
|
||||
<para>If you already have a <literal>~/.m2/settings.xml</literal> file then you simply need to add the above <literal><profile></literal> element to your <literal><profiles></literal>.</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Setup the directories</title>
|
||||
<para>Each JBoss.org project stores its documentation in a <literal>docs</literal> directory, typically located at <literal><projectName>/trunk/docs</literal>. By convention the source for each DocBook should be placed into subdirectories directly beneath this. For example, the DocBook source for a project's User Guide should be placed in
|
||||
<literal><projectName>/trunk/docs/userguide</literal> whilst the DocBook source for a Reference Guide should be placed in <literal><projectName>/trunk/docs/reference</literal>. Alongside these DocBook subdirectories any number
|
||||
of other subdirectories containing API references, code examples, and articles may also be created.</para>
|
||||
<para>For example the
|
||||
docs directory for the JBoss Messaging
|
||||
project is shown in <xref linkend="aop.fig"/>. </para>
|
||||
<figure id="aop.fig">
|
||||
<title>The JBoss Messaging docs directory</title>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata align="center" fileref="image/messaging-docs.png"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
</figure>
|
||||
<para>To facilitate translation into other languages the original source of a DocBook is written in English and located in a directory named <literal>en</literal>. Within this there are typically two subdirectories for the content:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>images </literal>- stores images</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para> <literal>modules</literal> - stores DocBook
|
||||
text modules, usually one per chapter</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>The <literal>master.xml</literal> file contains the top-level <literal><book></literal> element and is used to group all of the other text modules together. If you choose to use Ant to perform the build then a <literal>build.xml</literal> file is used to call the relevant tasks. Otherwise a <literal>pom.xml</literal> file can be called using Maven2.</para>
|
||||
<para>The easiest way to
|
||||
setup a DocBook subdirectory within your project is to copy the
|
||||
<literal>
|
||||
<ulink url="http://anonsvn.jboss.org/repos/jbossas/trunk/docbook-support/docs/guide/">docbook-support/docs/guide</ulink>
|
||||
</literal> directory (containing the DocBook source for this guide) and use it as a template. </para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Author the content</title>
|
||||
<para>Now you can write your content in DocBook format. Make sure that
|
||||
the master file of your DocBook (i.e. the file that contains the
|
||||
<literal><book></literal> element) is called
|
||||
<literal>master.xml</literal> and lives directly under the <literal>en</literal>
|
||||
directory (see <xref linkend="aop.fig"/>). You can either put the
|
||||
entire content in <literal>master.xml</literal> or divide up the
|
||||
chapters and place them in the <literal>modules/</literal>
|
||||
directory. If you do the latter, you should reference the chapter
|
||||
files from the <literal>master.xml</literal> file via entity
|
||||
references. Please see the
|
||||
<literal>
|
||||
<ulink url="http://anonsvn.jboss.org/repos/jbossas/trunk/docbook-support/docs/guide/en/master.xml">docbook-support/docs/guide/en/master.xml</ulink>
|
||||
</literal> file to
|
||||
see how this is done. </para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Build the documents</title>
|
||||
<para>To perform a build using Maven you simply need to enter the following commands from the directory containing the <literal>pom.xml</literal> file:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><command>mvn compile</command> - processes the DocBook source using the XSL stylesheets</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><command>mvn package</command> - creates WAR archives containing the various output formats</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><command>mvn clean</command> - removes the target directory containing the build output</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>It is also possible to chain commands together if required. e.g. <command>mvn clean compile</command></para>
|
||||
<para>Once the <literal>compile</literal> or <literal>package</literal> goals have been reached then a <literal>target/</literal> directory will be created containing the build output.</para>
|
||||
<figure>
|
||||
<title>The JBoss Messaging target directory</title>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata align="center" fileref="image/target-dir.png"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
</figure>
|
||||
<para>The <literal>attach</literal> directory contains WAR archives that package together all of the files for the various output formats. The intention is that these can be easily deployed into a web server such as Tomcat or JBoss AS.</para>
|
||||
<para>The <literal>docbook</literal> directory contains a number of subdirectories; one per output format. This is where you will find the XHTML, PDF and Eclipse Help files.</para>
|
||||
<para>The <literal>staging</literal> directory contains resources such as CSS files, images and fonts that are needed for the final output. They need to be placed into this directory during the build as the DocBook XSL stylesheets can only reference a single location for images. Similarly the FOP libraries can only reference a single location for fonts.</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Migrating from Ant </title>
|
||||
<para>Previously the JBoss DocBook system used Ant to perform builds. This meant that each DocBook subdirectory contained a <literal>build.xml </literal>file as follows:</para>
|
||||
<programlisting>
|
||||
<project name="Documentation" default="all.doc" basedir=".">
|
||||
|
||||
<property name="pdf.name" value="jboss-mybook.pdf" />
|
||||
<import file="../../../docbook-support/support.xml" />
|
||||
|
||||
<target name="all.doc" depends="clean">
|
||||
<antcall target="lang.all">
|
||||
<param name="lang" value="en"/>
|
||||
</antcall>
|
||||
</target>
|
||||
|
||||
</project>
|
||||
</programlisting>
|
||||
<para>The idea was for this file to delegate most of the work to a
|
||||
<literal>support.xml</literal> file maintained by the
|
||||
<literal>
|
||||
<ulink url="http://anonsvn.jboss.org/repos/jbossas/trunk/docbook-support/">docbook-support</ulink>
|
||||
</literal> project. Developers were supposed to check out the <literal>docbook-support</literal> project alongside their own project in order to reference this file together with the associated libraries and XSL stylesheets. However what usually happened was that the contents of the <literal>docbook-support</literal> project were copied into each project's SVN tree. This meant that projects ended up having to maintain their own DocBook build systems and any changes made to the <literal>docbook-support</literal> project would have to be manually synchronised with their own copy.</para>
|
||||
<para>With the new Maven2 based system this is no longer an issue as Maven takes care of downloading dependencies automatically. As a result all of the build environment can now be centrally maintained by the Content Team as a set of Maven plugins. You are free to continue using Ant if you prefer but since you won't be using the Maven plugins you will have to maintain any DocBook libraries, XSL stylesheets and CSS files copied or referenced from the <literal>docbook-support</literal> project yourself.</para>
|
||||
<para>To perform the build using Ant simply enter the <command>ant</command> command from the directory containing the <literal>build.xml</literal> file. After it is finished, you should have three output documents in the following places:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>The <literal>build/en/html </literal>directory contains
|
||||
the HTML version of the document. Each chapter is broken into a
|
||||
separate HTML file and they are linked together by an
|
||||
<literal>index.html</literal> file.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The <literal>build/en/html_single</literal> directory
|
||||
contains a single <literal>index.html</literal> file which holds
|
||||
the entire document. </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The <literal>build/en/pdf</literal> directory contains
|
||||
the PDF version of the document. </para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<note>
|
||||
<para>The HTML output created by Ant is not XHTML. If you wish to gaurantee the separation of content and style then Maven2 should be used instead to produce strict XHTML.</para>
|
||||
</note>
|
||||
<para>If you wish to migrate from Ant to Maven then all you need to do is copy the <literal>
|
||||
<ulink url="http://anonsvn.jboss.org/repos/jbossas/trunk/docbook-support/docs/guide/pom.xml">docbook-support/docs/guide/pom.xml</ulink>
|
||||
</literal> file to your own DocBook subdirectory (alongside the <literal>build.xml</literal> file) and then follow the instructions in the previous section. You can then delete the <literal>build.xml</literal> file as it's not longer needed.</para>
|
||||
</section>
|
||||
</chapter>
|
||||
@ -1,25 +1,5 @@
|
||||
<?xml version='1.0' encoding='UTF-8'?><chapter id="introduction">
|
||||
<title>Introduction to DocBook processing</title>
|
||||
<para>DocBook is an XML format for writing documents. It allows the author to
|
||||
focus on the content itself during the writing process instead of
|
||||
worrying about the presentation. </para>
|
||||
<para>Using standard DocBook tags, we can tag the content according to
|
||||
its syntatic structure. The DocBook document is then processed using
|
||||
XSL stylesheets so that each tagged DocBook element is transformed to a
|
||||
corresponding element in the target output format. For example each <para></para> element in DocBook could be transformed into a <p></p> element in XHTML. </para>
|
||||
<para>Using different XSL stylesheets, we can generate different
|
||||
output formats. For example, we can generate both XHTML and PDF outputs from
|
||||
a single DocBook source. We can also generate multiple versions of XHTML
|
||||
(or PDF) files each with a different style if necessary.</para>
|
||||
<para>In the JBoss DocBook system, we provide XSL stylesheets to build XHTML, PDF and Eclipse Help output formats from the DocBook source. The build process is
|
||||
illustrated in <xref linkend="build.fig"/>. </para>
|
||||
<figure id="build.fig">
|
||||
<title>The DocBook build process </title>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata align="center" fileref="image/build.png"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
</figure>
|
||||
<para>XHTML is used instead of HTML as it ensures that the content is completely separated from its style using Cascading Style Sheets (CSS) and image files.</para>
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<chapter id="introduction">
|
||||
<title>Introduction</title>
|
||||
<para>To be written...</para>
|
||||
</chapter>
|
||||
|
||||
5
src/docbook/module/security.xml
Normal file
5
src/docbook/module/security.xml
Normal file
@ -0,0 +1,5 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<chapter id="security">
|
||||
<title>Securing the Wire</title>
|
||||
<para>To be written...</para>
|
||||
</chapter>
|
||||
@ -1,35 +0,0 @@
|
||||
<?xml version='1.0' encoding='UTF-8'?><chapter id="styles">
|
||||
<title>Maintaining the JBoss DocBook system</title>
|
||||
<para>The structure of the <literal>
|
||||
<ulink url="http://anonsvn.jboss.org/repos/jbossas/trunk/docbook-support/">docbook-support</ulink>
|
||||
</literal> project is
|
||||
illustrated in <xref linkend="docbook.fig"/>. The contents are as follows:</para>
|
||||
<figure id="docbook.fig">
|
||||
<title>The docbook-support project </title>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata align="center" fileref="image/docbook-dir.png"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
</figure>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>The <literal>docs</literal> directory contains the DocBook source for this guide to
|
||||
serve as a template for other projects. </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The <literal>jbossorg-documentation</literal> directory contains the maven plugin source for the parent POM that is referenced by each project's <literal>pom.xml</literal> file. The parent POM contains common configuration information so that it does not have to be duplicated across multiple JBoss.org projects.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The <literal>jbossorg-docbook-xslt</literal> directory contains the maven plugin source for the default JBoss.org XSL stylesheets. These stylesheets produce XHTML, PDF and Eclipse Help output.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The <literal>jbossorg-jdocbook-style</literal> directory contains the maven plugin source for the default JBoss.org CSS and image files. These provide the JBoss.org community-driven look & feel.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The <literal>styles</literal> and <literal>support</literal> directories together with the <literal>support.xml</literal> file are provided for backwards compatibility with projects that wish to continue using Ant instead of Maven. The <literal>styles</literal> directory contains XSL stylesheets together with CSS files to produce HTML and PDF outputs. The <literal>support</literal> directory contains the DocBook
|
||||
libraries and DTDs along with
|
||||
the standard XSL stylesheets. The <literal>support.xml</literal> file contains common Ant tasks to perform the build.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</chapter>
|
||||
5
src/docbook/module/template.xml
Normal file
5
src/docbook/module/template.xml
Normal file
@ -0,0 +1,5 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<chapter id="chapter-id">
|
||||
<title>Chapter title</title>
|
||||
<para>To be written...</para>
|
||||
</chapter>
|
||||
5
src/docbook/module/threading.xml
Normal file
5
src/docbook/module/threading.xml
Normal file
@ -0,0 +1,5 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<chapter id="threading">
|
||||
<title>Threading</title>
|
||||
<para>To be written...</para>
|
||||
</chapter>
|
||||
5
src/docbook/module/transport.xml
Normal file
5
src/docbook/module/transport.xml
Normal file
@ -0,0 +1,5 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<chapter id="transport">
|
||||
<title>Transports</title>
|
||||
<para>To be written...</para>
|
||||
</chapter>
|
||||
Loading…
Reference in New Issue
Block a user