6:37 p.m.
Author: julien(a)jboss.com
Date: 2007-10-19 12:37:54 -0400 (Fri, 19 Oct 2007)
New Revision: 8719
Modified:
docs/template/user-guide/en/master.xml
docs/template/user-guide/en/modules/sample.xml
Log:
update the doc template to include what we should use to write well formated documentation
(not exhaustive of course)
Modified: docs/template/user-guide/en/master.xml
===================================================================
--- docs/template/user-guide/en/master.xml 2007-10-19 15:42:38 UTC (rev 8718)
+++ docs/template/user-guide/en/master.xml 2007-10-19 16:37:54 UTC (rev 8719)
@@ -10,9 +10,9 @@
<releaseinfo>Change Release Info in master.xml</releaseinfo>
<releaseinfo>Change Release Info Date in master.xml</releaseinfo>
<author>
- <firstname>Thomas</firstname>
- <surname>Heute</surname>
- <email>theute(a)jboss.org</email>
+ <firstname>Your first name</firstname>
+ <surname>Your last name</surname>
+ <email>your.email(a)your.domain.com</email>
</author>
</bookinfo>
<toc/>
Modified: docs/template/user-guide/en/modules/sample.xml
===================================================================
--- docs/template/user-guide/en/modules/sample.xml 2007-10-19 15:42:38 UTC (rev 8718)
+++ docs/template/user-guide/en/modules/sample.xml 2007-10-19 16:37:54 UTC (rev 8719)
@@ -1,58 +1,205 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="ajax">
+<chapter id="sample">
<chapterinfo>
<author>
- <firstname>Julien</firstname>
- <surname>Viet</surname>
- <email>julien.viet(a)jboss.com</email>
+ <firstname>Your first name</firstname>
+ <surname>Your last name</surname>
+ <email>your.email(a)your.domain.com</email>
</author>
</chapterinfo>
- <title>My title</title>
- <para>This section covers the ajax features provided by the
portal.</para>
+ <title>Sample chapter</title>
+ <para>This is the beginning of the sample chapter.</para>
<sect1>
- <title>Introduction</title>
- <para>Todo</para>
- </sect1>
- <sect1>
- <title>Ajaxified markup</title>
+ <title>sample section</title>
+ <para>This is the beginning of the sample section. It contains examples of
how docbook should be used in the context
+ of a documentation for a Java related product.</para>
+
<sect2>
- <title>Ajaxified layouts</title>
- <para>Part of the Ajax capabilities are implemented in the layout
framework which provide the structure for
- generating portal pages. The good news is that the existing layout only requires
a few modifications in
- order to be ajaxified.</para>
- <para>We will use as example an simplified version of the layout JSP
provided in JBoss Portal 2.6 and outline
- what are the required changes that makes it an ajaxified layout:
+ <title>Bullet points</title>
<programlisting><![CDATA[
-<%@ taglib uri="/WEB-INF/theme/portal-layout.tld" prefix="p"
%>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
- <meta http-equiv="Content-Type" content="text/html;"/>
- <!-- inject the theme, default to the Renaissance theme if
- nothing is selected for the portal or the page -->
- <p:theme themeName="renaissance"/>
- <!-- insert header content that was possibly set by portlets on the page -->
- <p:headerContent/>
-</head>
+<itemizedlist>
+ <listitem>Item1</listitem>
+ <listitem>Item2</listitem>
+ <listitem>Item3</listitem>
+</itemizedlist>
]]></programlisting>
+ <para>
<itemizedlist>
- <listitem><![CDATA[<p:theme
themeName="renaissance"/>]]> should be already present as it exists since
2.4 but is even more
- necessary as it will inject in the page the reference to the ajax
stylesheet.</listitem>
- <listitem><![CDATA[<p:region regionName='AJAXScripts'
regionID='AJAXScripts'/>]]> should be added before any other region
- in the markup of the layout.</listitem>
- <listitem><![CDATA[<p:region regionName='AJAXFooter'
regionID='AJAXFooter'/>]]> should be added after any other region
- in the markup of the layout.</listitem>
+ <listitem>Item1</listitem>
+ <listitem>Item2</listitem>
+ <listitem>Item3</listitem>
</itemizedlist>
</para>
- <mediaobject>
- <imageobject>
- <imagedata align="center"
fileref="images/sample/partial-refresh.png" format="png"/>
- </imageobject>
- <caption>
- <para>The portal providing partial refresh</para>
- </caption>
- </mediaobject>
</sect2>
+
+ <sect2>
+ <title>Interface or annotation reference</title>
+ <programlisting><![CDATA[
+<interfacename>mypackage.MyInterface</interfacename>
+<interfacename>@MyAnnotation</interfacename>
+]]></programlisting>
+ <para>
+ <interfacename>mypackage.MyInterface</interfacename>
+ <interfacename>@MyAnnotation</interfacename>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Class reference</title>
+ <programlisting><![CDATA[
+<classname>mypackage.MyClass</classname>
+]]></programlisting>
+ <para>
+ <classname>mypackage.MyClass</classname>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Parameter reference</title>
+ <programlisting><![CDATA[
+<parameter>MyParameter</parameter>
+]]></programlisting>
+ <para>
+ <parameter>MyParameter</parameter>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Method referece</title>
+ <programlisting><![CDATA[
+<methodname>myMethod()</methodname>
+]]></programlisting>
+ <para>
+ <methodname>myMethod()</methodname>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Exception reference</title>
+ <programlisting><![CDATA[
+<exceptionname>mypackage.MyException</exceptionname>
+]]></programlisting>
+ <para>
+ <exceptionname>mypackage.MyException</exceptionname>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>A variable name</title>
+ <programlisting><![CDATA[
+<varname>myVariable</varname>
+]]></programlisting>
+ <para>
+ <varname>myVariable</varname>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>File reference</title>
+ <programlisting><![CDATA[
+<filename>MyFile</filename>
+]]></programlisting>
+ <para>
+ <filename>MyFile</filename>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Literal reference</title>
+ <programlisting><![CDATA[
+<literal>null</literal>
+<literal>1</literal>
+<literal>"foo"</literal>
+]]></programlisting>
+ <para>
+ <literal>null</literal>
+ <literal>1</literal>
+ <literal>"foo"</literal>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>A constant</title>
+ <programlisting><![CDATA[
+<constant>MAX_VALUE</constant>
+]]></programlisting>
+ <para>
+ <constant>MAX_VALUE</constant>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Inline code</title>
+ <programlisting><![CDATA[
+<code>System.out.println()</code>
+]]></programlisting>
+ <para>
+ <code>System.out.println()</code>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Code or XML with a caption</title>
+ <programlisting>
+<example>
+ <programlisting><![CDATA[public class MyClass
+{
+}
+]]></programlisting>
+ <caption>This is the MyClass class</caption>
+</example>
+</programlisting>
+ <para>
+ <example>
+ <programlisting><![CDATA[public class MyClass
+{
+}
+]]></programlisting>
+ <caption>This is the MyClass class</caption>
+ </example>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>A database name</title>
+ <programlisting><![CDATA[
+<database>MyDatabase</database>
+]]></programlisting>
+ <para>
+ <database>MyDatabase</database>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>A shell command</title>
+ <programlisting><![CDATA[
+<command>ls -l</command>
+]]></programlisting>
+ <para>
+ <command>ls -l</command>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>A shell example</title>
+ <programlisting><![CDATA[
+<screen><![CDATA[julien-viets-computer:~/java/jboss-portal-template/user-guide
julien$ ls -l
+total 8
+drwxr-xr-x 3 julien julien 102 Oct 19 18:14 build
+-rwxr-xr-x 1 julien julien 923 Oct 19 17:40 build.xml
+drwxr-xr-x 6 julien julien 204 Oct 19 17:42 en
+]]></screen>
+]]></programlisting>
+ <para>
+
<screen><![CDATA[julien-viets-computer:~/java/jboss-portal-template/user-guide
julien$ ls -l
+total 8
+drwxr-xr-x 3 julien julien 102 Oct 19 18:14 build
+-rwxr-xr-x 1 julien julien 923 Oct 19 17:40 build.xml
+drwxr-xr-x 6 julien julien 204 Oct 19 17:42 en
+]]></screen>
+ </para>
+ </sect2>
+
</sect1>
+
</chapter>