You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by dk...@apache.org on 2006/08/25 15:17:37 UTC
svn commit: r436785 [7/18] - in /incubator/cxf/trunk: ./ api/
api/src/main/java/org/apache/cxf/buslifecycle/
api/src/main/java/org/apache/cxf/databinding/
api/src/main/java/org/apache/cxf/endpoint/
api/src/main/java/org/apache/cxf/interceptor/ api/src/...
Modified: incubator/cxf/trunk/docs/src/docs/styleguide/links.xml
URL: http://svn.apache.org/viewvc/incubator/cxf/trunk/docs/src/docs/styleguide/links.xml?rev=436785&r1=436784&r2=436785&view=diff
==============================================================================
--- incubator/cxf/trunk/docs/src/docs/styleguide/links.xml (original)
+++ incubator/cxf/trunk/docs/src/docs/styleguide/links.xml Fri Aug 25 06:16:36 2006
@@ -1,134 +1,134 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<chapter>
- <title>Cross References and Links</title>
- <section>
- <title>Overview</title>
- <para>The CeliXfire documentation uses a subset of the linking elements defined by Docbook. The
- elements include:</para>
- <itemizedlist>
- <listitem>
- <para><link linkend="xref"><sgmltag class="element">xref</sgmltag></link></para>
- </listitem>
- <listitem>
- <para><link linkend="link"><sgmltag class="element">link</sgmltag></link></para>
- </listitem>
- <listitem>
- <para><link linkend="ulink"><sgmltag class="element">ulink</sgmltag></link></para>
- </listitem>
- <listitem><para><sgmltag class="element">anchor</sgmltag></para></listitem>
- </itemizedlist>
- <para>Using this set of elements, you can create cross references, internal links, and external
- links in your documents.</para>
- </section>
- <section>
- <title>Internal Links and Cross References</title>
- <para>Internal links are links whose anchor is in the same document. A cross reference is a
- special instance of an internal link. Where an internal link requires that you supply the
- text that is displayed, as with an HTML link, a cross reference's text is automatically
- determined by the link's target.</para>
- <section id="link">
- <title>Inserting an Internal Link</title>
- <para>Internal links are created using the <sgmltag class="element">link</sgmltag> element.
- The <sgmltag class="element">link</sgmltag> element has one required attribute
- <sgmltag class="attribute">linkend</sgmltag> whose value is the id of element
- anchoring the link. The anchoring element can be any valid Docbook element that uses
- the <sgmltag class="attribute">id</sgmltag> attribute. For example if you wanted to
- create a link to an image in your document, you could use the id of the
- <sgmltag class="element">figure</sgmltag> element that wraps the image.</para>
- <note>
- <para>You can also create anchor points in your text using the
- <sgmltag class="element">anchor</sgmltag> element. In this case, the value of the
- <sgmltag class="attribute">linkend</sgmltag> attribute would be the id of the
- <sgmltag class="element">anchor</sgmltag> element.</para>
- </note>
- <para>The text used for the link is the content of the
- <sgmltag class="element">link</sgmltag> element. <xref linkend="linkexample" /> shows
- the mark up for this <link linkend="link">link to the top</link> of this section.</para>
- <example id="linkexample">
- <title>Example of an Internal Link</title>
- <programlisting>this <link linkend="link">link to the top</link> of</programlisting>
- </example>
- </section>
- <section id="xref">
- <title>Inserting a Cross Reference</title>
- <para>Cross references are created using the <sgmltag class="element">xref</sgmltag> element.
- Like the <sgmltag class="element">link</sgmltag> element, the
- <sgmltag class="element">xref</sgmltag> element requires the use of the
- <sgmltag class="attribute">linkend</sgmltag> attribute to identify the element being
- referenced.</para>
- <para>Unlike the <sgmltag class="element">link</sgmltag> element, the
- <sgmltag class="element">xref</sgmltag> element does not have any contents. The text
- displayed for the generated link is generated based on the contents of the referenced
- element. If the referenced element has a <sgmltag class="element">title</sgmltag>
- element, such as a <sgmltag class="element">section</sgmltag> element or a
- <sgmltag class="element">example</sgmltag> element, the contents of the
- <sgmltag class="element">title</sgmltag> element is used as the link text.
- Alternatively, the value of the referenced element's
- <sgmltag class="attribute">xreflable</sgmltag> attribute will be used as the link
- text.</para>
- <note>
- <para>If the referenced element has both a <sgmltag class="element">title</sgmltag>
- element and a value specified in its <sgmltag class="attribute">xreflable</sgmltag>
- attribute, the value of the <sgmltag class="attribute">xreflable</sgmltag> attribute
- is used.</para>
- </note>
- <para><xref linkend="xrefexample1" /> shows an example of a cross reference whose text is
- derived from the <sgmltag class="element">title</sgmltag> element of the referenced
- element. The resulting link text would be <literal>the section called "Coco Crisps"
- shows</literal>.</para>
- <example id="xrefexample1">
- <title>Cross Reference to a Titled Element</title>
- <programlisting><para><xref linkend="topsect" /> shows ...</para>
-...
-<section id="topsect">
- <title>Coco Crisps</title>
-...
-</section></programlisting>
- </example>
- <para><xref linkend="xrefexample2" /> shows an example of a cross reference whose text is
- derived from the <sgmltag class="attribute">xreflable</sgmltag> attribute of the
- referenced element. The resulting link text would be <literal>short stop shows</literal>
- .</para>
- <example id="xrefexample2">
- <title>Cross Reference to an Element with an Xreflable</title>
- <programlisting><para><xref linkend="example1" /> shows ...</para>
-...
-<example id="example1" xlableref="short stop">
- <title>Catching Coco Crisp</title>
- ...
-</example></programlisting>
- </example>
- </section>
- </section>
- <section id="ulink">
- <title>External Links</title>
- <para>External links are links to resources that are not contianed in the same XML source
- document. They do not have to be links to other documents. They can be links to Web pages
- or any other resource that can be reached using a URL. Generally, they are transformed
- into HTML links when the document is published.</para>
- <para>External links are created using the <sgmltag class="element">ulink</sgmltag> element.
- You identify the linked resource using the required <sgmltag class="attribute">url</sgmltag>
- attribute. The value must be a valid URL.</para>
- <note>
- <para>Because the CeltiXfire documentation is built with Forrest, you can use the
- <filename>site:<replaceable>siteId</replaceable></filename> resource identifier to
- refer to pages that are listed in <filename>site.xml</filename>.</para>
- </note>
- <para>The link text can be specified in one of two ways. You can specified the desired link
- text as the value of the <sgmltag class="element">ulink</sgmltag> element. If you leave
- the <sgmltag class="element">ulink</sgmltag> element empty, the value of the
- <sgmltag class="attribute">url</sgmltag> attribute will be used as the link text.</para>
- <para><xref linkend="ulinkexample1"/> shows an example of an external link with supplied link
- text.</para>
- <example id="ulinkexample1">
- <title>External Link with Link Text</title>
- <programlisting><ulink url="http://celtixfire.org">CeltiXfire Home</ulink></programlisting>
- </example>
- <para><xref linkend="ulinkexample2"/> shows an example of an external link that uses the default
- link text.</para>
- <example id="ulinkexample2">
- <title>External Link Using Default Link Text</title>
- <programlisting><ulink url="http://celtixfire.org" /></programlisting>
- </example>
- </section>
+<?xml version='1.0' encoding='UTF-8'?>
+<chapter>
+ <title>Cross References and Links</title>
+ <section>
+ <title>Overview</title>
+ <para>The CeliXfire documentation uses a subset of the linking elements defined by Docbook. The
+ elements include:</para>
+ <itemizedlist>
+ <listitem>
+ <para><link linkend="xref"><sgmltag class="element">xref</sgmltag></link></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="link"><sgmltag class="element">link</sgmltag></link></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="ulink"><sgmltag class="element">ulink</sgmltag></link></para>
+ </listitem>
+ <listitem><para><sgmltag class="element">anchor</sgmltag></para></listitem>
+ </itemizedlist>
+ <para>Using this set of elements, you can create cross references, internal links, and external
+ links in your documents.</para>
+ </section>
+ <section>
+ <title>Internal Links and Cross References</title>
+ <para>Internal links are links whose anchor is in the same document. A cross reference is a
+ special instance of an internal link. Where an internal link requires that you supply the
+ text that is displayed, as with an HTML link, a cross reference's text is automatically
+ determined by the link's target.</para>
+ <section id="link">
+ <title>Inserting an Internal Link</title>
+ <para>Internal links are created using the <sgmltag class="element">link</sgmltag> element.
+ The <sgmltag class="element">link</sgmltag> element has one required attribute
+ <sgmltag class="attribute">linkend</sgmltag> whose value is the id of element
+ anchoring the link. The anchoring element can be any valid Docbook element that uses
+ the <sgmltag class="attribute">id</sgmltag> attribute. For example if you wanted to
+ create a link to an image in your document, you could use the id of the
+ <sgmltag class="element">figure</sgmltag> element that wraps the image.</para>
+ <note>
+ <para>You can also create anchor points in your text using the
+ <sgmltag class="element">anchor</sgmltag> element. In this case, the value of the
+ <sgmltag class="attribute">linkend</sgmltag> attribute would be the id of the
+ <sgmltag class="element">anchor</sgmltag> element.</para>
+ </note>
+ <para>The text used for the link is the content of the
+ <sgmltag class="element">link</sgmltag> element. <xref linkend="linkexample" /> shows
+ the mark up for this <link linkend="link">link to the top</link> of this section.</para>
+ <example id="linkexample">
+ <title>Example of an Internal Link</title>
+ <programlisting>this <link linkend="link">link to the top</link> of</programlisting>
+ </example>
+ </section>
+ <section id="xref">
+ <title>Inserting a Cross Reference</title>
+ <para>Cross references are created using the <sgmltag class="element">xref</sgmltag> element.
+ Like the <sgmltag class="element">link</sgmltag> element, the
+ <sgmltag class="element">xref</sgmltag> element requires the use of the
+ <sgmltag class="attribute">linkend</sgmltag> attribute to identify the element being
+ referenced.</para>
+ <para>Unlike the <sgmltag class="element">link</sgmltag> element, the
+ <sgmltag class="element">xref</sgmltag> element does not have any contents. The text
+ displayed for the generated link is generated based on the contents of the referenced
+ element. If the referenced element has a <sgmltag class="element">title</sgmltag>
+ element, such as a <sgmltag class="element">section</sgmltag> element or a
+ <sgmltag class="element">example</sgmltag> element, the contents of the
+ <sgmltag class="element">title</sgmltag> element is used as the link text.
+ Alternatively, the value of the referenced element's
+ <sgmltag class="attribute">xreflable</sgmltag> attribute will be used as the link
+ text.</para>
+ <note>
+ <para>If the referenced element has both a <sgmltag class="element">title</sgmltag>
+ element and a value specified in its <sgmltag class="attribute">xreflable</sgmltag>
+ attribute, the value of the <sgmltag class="attribute">xreflable</sgmltag> attribute
+ is used.</para>
+ </note>
+ <para><xref linkend="xrefexample1" /> shows an example of a cross reference whose text is
+ derived from the <sgmltag class="element">title</sgmltag> element of the referenced
+ element. The resulting link text would be <literal>the section called "Coco Crisps"
+ shows</literal>.</para>
+ <example id="xrefexample1">
+ <title>Cross Reference to a Titled Element</title>
+ <programlisting><para><xref linkend="topsect" /> shows ...</para>
+...
+<section id="topsect">
+ <title>Coco Crisps</title>
+...
+</section></programlisting>
+ </example>
+ <para><xref linkend="xrefexample2" /> shows an example of a cross reference whose text is
+ derived from the <sgmltag class="attribute">xreflable</sgmltag> attribute of the
+ referenced element. The resulting link text would be <literal>short stop shows</literal>
+ .</para>
+ <example id="xrefexample2">
+ <title>Cross Reference to an Element with an Xreflable</title>
+ <programlisting><para><xref linkend="example1" /> shows ...</para>
+...
+<example id="example1" xlableref="short stop">
+ <title>Catching Coco Crisp</title>
+ ...
+</example></programlisting>
+ </example>
+ </section>
+ </section>
+ <section id="ulink">
+ <title>External Links</title>
+ <para>External links are links to resources that are not contianed in the same XML source
+ document. They do not have to be links to other documents. They can be links to Web pages
+ or any other resource that can be reached using a URL. Generally, they are transformed
+ into HTML links when the document is published.</para>
+ <para>External links are created using the <sgmltag class="element">ulink</sgmltag> element.
+ You identify the linked resource using the required <sgmltag class="attribute">url</sgmltag>
+ attribute. The value must be a valid URL.</para>
+ <note>
+ <para>Because the CeltiXfire documentation is built with Forrest, you can use the
+ <filename>site:<replaceable>siteId</replaceable></filename> resource identifier to
+ refer to pages that are listed in <filename>site.xml</filename>.</para>
+ </note>
+ <para>The link text can be specified in one of two ways. You can specified the desired link
+ text as the value of the <sgmltag class="element">ulink</sgmltag> element. If you leave
+ the <sgmltag class="element">ulink</sgmltag> element empty, the value of the
+ <sgmltag class="attribute">url</sgmltag> attribute will be used as the link text.</para>
+ <para><xref linkend="ulinkexample1"/> shows an example of an external link with supplied link
+ text.</para>
+ <example id="ulinkexample1">
+ <title>External Link with Link Text</title>
+ <programlisting><ulink url="http://celtixfire.org">CeltiXfire Home</ulink></programlisting>
+ </example>
+ <para><xref linkend="ulinkexample2"/> shows an example of an external link that uses the default
+ link text.</para>
+ <example id="ulinkexample2">
+ <title>External Link Using Default Link Text</title>
+ <programlisting><ulink url="http://celtixfire.org" /></programlisting>
+ </example>
+ </section>
</chapter>
Propchange: incubator/cxf/trunk/docs/src/docs/styleguide/links.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: incubator/cxf/trunk/docs/src/docs/styleguide/links.xml
------------------------------------------------------------------------------
svn:keywords = Rev Date
Propchange: incubator/cxf/trunk/docs/src/docs/styleguide/links.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Modified: incubator/cxf/trunk/docs/src/docs/styleguide/lists.xml
URL: http://svn.apache.org/viewvc/incubator/cxf/trunk/docs/src/docs/styleguide/lists.xml?rev=436785&r1=436784&r2=436785&view=diff
==============================================================================
--- incubator/cxf/trunk/docs/src/docs/styleguide/lists.xml (original)
+++ incubator/cxf/trunk/docs/src/docs/styleguide/lists.xml Fri Aug 25 06:16:36 2006
@@ -1,346 +1,346 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<chapter>
- <title>Lists</title>
- <section>
- <title>Simple Lists</title>
- <para>Simple lists are like a grocery list. They are a simple list of
- words or phrases without any delimiter. Their elements can only consist of
- simple, in-line tags. Therefore they cannot contain sublists, examples,
- code listings or multiple paragraphs. They are rarely used in CeltiXfire(CXF)
- documentation.</para>
- <section>
- <title>Specifying a simple list</title>
- <para>A simple list is specified by a <sgmltag class="element">simplelist</sgmltag> element.
- <sgmltag class="element">simplelist</sgmltag> has two optional attributes:</para>
- <table>
- <title>Attributes of the <sgmltag class="element">simplelist</sgmltag> Element</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Values</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <sgmltag class="attribute">type</sgmltag>
- </entry>
- <entry><sgmltag class="attvalue">inline</sgmltag>, <sgmltag class="attvalue">horiz</sgmltag>, <sgmltag class="attvalue">vert</sgmltag>(default)</entry>
- <entry>Specifies how the items in the list are to be listed.</entry>
- </row>
- <row>
- <entry>
- <sgmltag class="attribute">columns</sgmltag>
- </entry>
- <entry>>=1</entry>
- <entry>Specifies the number of columns to use when <sgmltag class="attribute">type</sgmltag> is set to <sgmltag class="attvalue">horiz</sgmltag> or <sgmltag class="attvalue">vert</sgmltag>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>The elements of a simple list are specified using a <sgmltag class="element">member</sgmltag> element. The contents of each<sgmltag>member</sgmltag> element can only contain character data and
- inline elements.</para>
- </section>
- <section>
- <title>Example</title>
- <para><xref linkend="simpmarkup"/> shows the markup for a simple
- list.</para>
- <example id="simpmarkup" xreflabel="Example 1">
- <title>Simple List Markup</title>
- <programlisting><simplelist>
- <member>Swedish Fish</member>
- <member>Mike & Ike</member>
- <member>Sour Patch Kids</member>
- <member>Gummy Bears</member>
-</simplelist></programlisting>
- </example>
- </section>
- </section>
- <section>
- <title>Itemized Lists</title>
- <para>An itemized list is used for lists where the order of the items in
- the list does not matter. They are like bulleted lists or the lists that
- are created by the <sgmltag class="element">ul</sgmltag> tag in
- HTML.</para>
- <section>
- <title>Specifying an Itemized List</title>
- <para>An itemized list is specified by an <sgmltag class="element">itemizedlist</sgmltag> element. You can specify an
- <sgmltag class="attribute">id</sgmltag> attribute for itemized lists. If
- the list is going to referenced by an <sgmltag class="element">xref</sgmltag> element, you should also specify a value
- for the <sgmltag class="attribute">xreflabel</sgmltag> attribute.</para>
- <para>Each item in an itemized list is specified by a <sgmltag class="element">listitem</sgmltag> element. The <sgmltag class="element">listitem</sgmltag> element is a wrapper element and can
- contain any container elements such as a <sgmltag class="element">para</sgmltag> element. All content within a <sgmltag class="element">listitem</sgmltag> element will be indented to the same
- level. You can also specify sub-lists within a <sgmltag class="element">listitem</sgmltag> element.</para>
- </section>
- <section>
- <title>Example</title>
- <para><xref linkend="itemmarkup"/> shows the markup for an itemized
- list.</para>
- <example id="itemmarkup" xreflabel="Example 2">
- <title>Itemized List Markup</title>
- <programlisting><itemizedlist>
- <listitem>
- <para>This is the first item in my list</para>
- </listitem>
- <listitem>
- <para>This is the second item in my list.</para>
- <para>It has two paragraphs.</para>
- </listitem>
- <listitem>
- <para>This item has a sublist.</para>
- <itemizedlist>
- <listitem><para>first</para></listitem>
- <listitem><para>second</para></listitem>
- </itemizedlist>
- </listitem>
-</itemizedlist></programlisting>
- </example>
- </section>
- </section>
- <section>
- <title>Ordered List</title>
- <para>An ordered list is a list where the order of the elements is
- important and made explicit. They are like numbered lists and lists that
- are created using the <sgmltag class="element">ol</sgmltag> tag in
- HTML.</para>
- <section>
- <title>Specifying an Ordered List</title>
- <para>Ordered lists are specified by an <sgmltag class="element">orderedlist</sgmltag> element. In addition to the
- <sgmltag class="attribute">id</sgmltag> attribute and <sgmltag class="attribute">xreflable</sgmltag> attribute, <sgmltag class="element">orderedlist</sgmltag> elements have three optional
- elements.</para>
- <table>
- <title>Attributes of the <sgmltag class="element">orderedlist</sgmltag> Element</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Values</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <sgmltag class="attribute">continuation</sgmltag>
- </entry>
- <entry><sgmltag class="attvalue">continues</sgmltag>, <sgmltag class="attvalue">restarts</sgmltag>(default)</entry>
- <entry>Specifies if the item numbering should restart at one or continue from the previous ordered list.</entry>
- </row>
- <row>
- <entry>
- <sgmltag class="attribute">inheritnum</sgmltag>
- </entry>
- <entry><sgmltag class="attvalue">inherit</sgmltag>, <sgmltag class="attvalue">ignore</sgmltag>(default)</entry>
- <entry>Valid only for nested lists. Specifies if the items in the nested list contain a reference to the item of the parent list.</entry>
- </row>
- <row>
- <entry>
- <sgmltag class="attribute">numeration</sgmltag>
- </entry>
- <entry><sgmltag class="attvalue">arabic</sgmltag>, <sgmltag class="attvalue">loweralpha</sgmltag>, <sgmltag class="attvalue">lowerroman</sgmltag>, <sgmltag class="attvalue">upperalpha</sgmltag>, <sgmltag class="attvalue">upperroman</sgmltag></entry>
- <entry>Specifies the numbering style to use for the list.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>Items in an ordered list are specified using a <sgmltag class="element">listitem</sgmltag> element. The <sgmltag class="element">listitem</sgmltag> element is a wrapper element and can
- contain any container elements such as a <sgmltag class="element">para</sgmltag> element. All content within a <sgmltag class="element">listitem</sgmltag> element will be indented to the same
- level. You can also specify sub-lists within a <sgmltag class="element">listitem</sgmltag> element.</para>
- </section>
- </section>
- <section>
- <title>Segmented Lists</title>
- <para>Segmented lists are a special type of list where the items consist
- of a group of labeled elements. They are not used in the CXF documentation.</para>
- </section>
- <section>
- <title>Variable Lists</title>
- <para>A variable list looks similar to a glossary. It consists of a word,
- or phrase, and some text describing the word, or phrase. <xref linkend="varexample"/> shows a variable list.</para>
- <variablelist id="varexample">
- <title>List of Rooms</title>
- <varlistentry>
- <term>Kitchen</term>
- <listitem>
- <para>The room where food is stored and prepared.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Garage</term>
- <listitem>
- <para>Where the cars are parked.</para>
- <note>
- <para>Bikes are also here.</para>
- </note>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Living room</term>
- <term>Family room</term>
- <listitem>
- <para>This is where we watch TV.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <section>
- <title>Specifying a Variable List</title>
- <para>Variable lists are specified by a <sgmltag class="element">variablelist</sgmltag> element. The <sgmltag class="element">variablelist</sgmltag> element can have the optional
- <sgmltag class="attribute">id</sgmltag> attribute and <sgmltag class="attribute">xreflable</sgmltag> attribute specified. You can also
- supply a title for a variable list by adding a <sgmltag class="element">title</sgmltag> element as the <sgmltag class="element">variablelist</sgmltag> element's first child.</para>
- <para>The items in a variable list are specified using a <sgmltag class="element">varlistentry</sgmltag> element. The <sgmltag class="element">varlistentry</sgmltag> element has two children elements
- that specify the contents of the item: <sgmltag class="element">term</sgmltag> and <sgmltag class="element">listitem</sgmltag>.</para>
- <section>
- <title>Specifying terms</title>
- <para>You can specify one or more <sgmltag class="element">term</sgmltag> elements in a <sgmltag class="element">varlistentry</sgmltag> element. Each <sgmltag class="element">term</sgmltag> element can contain text and inline
- markup elements. Each <sgmltag class="element">term</sgmltag> element
- should contain a single term or phrase that the list item
- describes.</para>
- </section>
- <section>
- <title>Describing a term</title>
- <para>You describe the term, or terms, defined by the <sgmltag class="element">term</sgmltag> elements using a single <sgmltag class="element">listitem</sgmltag> element. The <sgmltag class="element">listitem</sgmltag> element is a wrapper element and
- can contain any container elements such as a <sgmltag class="element">para</sgmltag> element. All content within a <sgmltag class="element">listitem</sgmltag> element will be indented to the
- same level. You can also specify sub-lists within a <sgmltag class="element">listitem</sgmltag> element.</para>
- </section>
- </section>
- <section>
- <title>Example</title>
- <para><xref linkend="varmarkup"/> shows the markup representing <xref linkend="varexample"/>.</para>
- <example id="varmarkup" xreflabel="Example 3">
- <title>Variable List Markup</title>
- <programlisting><variablelist id="varexample">
- <title>List of Rooms</title>
- <varlistentry>
- <term>Kitchen</term>
- <listitem>
- <para>The room where food is stored and prepared.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Garage</term>
- <listitem>
- <para>Where the cars are parked.</para>
- <note>
- <para>Bikes are also here.</para>
- </note>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Living room</term>
- <term>Family room</term>
- <listitem>
- <para>This is where we watch TV.</para>
- </listitem>
- </varlistentry>
-</variablelist></programlisting>
- </example>
- </section>
- </section>
- <section>
- <title>Glossary Lists</title>
- <para>A glossary list is a special case of a variable list. It is used
- specifically for lists that define terms and where you may want to refer
- the reader back to the definition of a specific term. <xref linkend="glossexample"/> shows a use of a glossary list.</para>
- <glosslist id="glossexample" xreflabel="List of terms">
- <glossentry>
- <glossterm id="consumerdef">consumer</glossterm>
- <glossdef>
- <para>The end user of a service, also called a client for that
- service.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm id="endptdef">endpoint</glossterm>
- <glossdef>
- <para>The point of contact that a <glossterm linkend="servicedef">service</glossterm> provides for its <glossterm linkend="consumerdef">consumers</glossterm>.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm id="servicedef">service</glossterm>
- <glossdef>
- <para>A collection of operations that perform a useful set of
- functions in a network, access to which is implemented as an
- <glossterm linkend="endptdef">endpoint</glossterm>. In a
- service-oriented network, services are defined by a service
- contract.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm>service consumer</glossterm>
- <glosssee otherterm="consumerdef"/>
- </glossentry>
- </glosslist>
- <section>
- <title>Specifying a Glossary List</title>
- <para>A glossary list is specified using the <sgmltag class="element">glosslist</sgmltag> element. If you want to refer back
- to a glossary list, you can provide values for the <sgmltag class="attribute">id</sgmltag> attribute and the <sgmltag class="attribute">xreflable</sgmltag> attribute. Unlike variable lists,
- glossary lists cannot have titles.</para>
- <para>The entries in a glossary list are specified using a <sgmltag class="element">glossentry</sgmltag> element. The <sgmltag class="element">glossentry</sgmltag> element typically has two children:
- <sgmltag class="element">glossterm</sgmltag> and <sgmltag class="element">glossdef</sgmltag>. You can also use the <sgmltag class="element">glosssee</sgmltag> element to xref with other
- definitions.</para>
- <section>
- <title>Specifying a Term</title>
- <para>A <sgmltag class="element">glossentry</sgmltag> element can have
- only one <sgmltag class="element">glossterm</sgmltag> element. This
- element specifies the term being defined by this entry. If you are
- going to refer back to this term, you can supply a value for the
- <sgmltag class="attribute">id</sgmltag> attribute.</para>
- <note>
- <para>The <sgmltag class="element">glossterm</sgmltag> element can
- also be used in text entries to refer to terms defined in a glossary
- entry. When used in this manner, you supply a value for the <sgmltag class="attribute">linkend</sgmltag> attribute.</para>
- </note>
- </section>
- <section>
- <title>Defining a Term</title>
- <para>You define a term using either one or more <sgmltag class="element">glossdef</sgmltag> elements or a <sgmltag class="element">glosssee</sgmltag> element. The <sgmltag class="element">glossdef</sgmltag> element is a content element that
- contains markup specifying a definition. If you use more than one
- <sgmltag class="element">glossdef</sgmltag> element, they are treated
- as separate definitions for the same term.</para>
- <para>The <sgmltag class="element">glosssee</sgmltag> element
- redirects the reader to a term with the same meaning. It acts like a
- "See" entry in a dictionary. It has one attribute, <sgmltag class="attribute">otherterm</sgmltag>, whose value is the id of the
- term to which the reader is redirected.</para>
- </section>
- </section>
- <section>
- <title>Example</title>
- <para><xref linkend="glossmarkup"/> shows the markup for <xref linkend="glossexample"/></para>
- <example id="glossmarkup" xreflabel="Example 4">
- <title>Glossary List Markup</title>
- <programlisting><glosslist id="glossexample" xreflabel="List of terms">
- <glossentry>
- <glossterm id="consumerdef">consumer</glossterm>
- <glossdef>
- <para>The end user of a service, also called a client for that service.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm id="endptdef">endpoint</glossterm>
- <glossdef>
- <para>The point of contact that a <glossterm
- linkend="servicedef">service</glossterm> provides for its <glossterm
- linkend="consumerdef">consumers</glossterm>.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm id="servicedef">service</glossterm>
- <glossdef>
- <para>A collection of operations that perform a useful set of
- functions in a network, access to which is implemented as an
- <glossterm linkend="endptdef">endpoint</glossterm>. In a
- service-oriented network, services are defined by a service
- contract.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm>service consumer</glossterm>
- <glosssee otherterm="consumerdef" />
- </glossentry>
-</glosslist></programlisting>
- </example>
- </section>
- </section>
+<?xml version='1.0' encoding='UTF-8'?>
+<chapter>
+ <title>Lists</title>
+ <section>
+ <title>Simple Lists</title>
+ <para>Simple lists are like a grocery list. They are a simple list of
+ words or phrases without any delimiter. Their elements can only consist of
+ simple, in-line tags. Therefore they cannot contain sublists, examples,
+ code listings or multiple paragraphs. They are rarely used in CeltiXfire(CXF)
+ documentation.</para>
+ <section>
+ <title>Specifying a simple list</title>
+ <para>A simple list is specified by a <sgmltag class="element">simplelist</sgmltag> element.
+ <sgmltag class="element">simplelist</sgmltag> has two optional attributes:</para>
+ <table>
+ <title>Attributes of the <sgmltag class="element">simplelist</sgmltag> Element</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+ <entry>Values</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <sgmltag class="attribute">type</sgmltag>
+ </entry>
+ <entry><sgmltag class="attvalue">inline</sgmltag>, <sgmltag class="attvalue">horiz</sgmltag>, <sgmltag class="attvalue">vert</sgmltag>(default)</entry>
+ <entry>Specifies how the items in the list are to be listed.</entry>
+ </row>
+ <row>
+ <entry>
+ <sgmltag class="attribute">columns</sgmltag>
+ </entry>
+ <entry>>=1</entry>
+ <entry>Specifies the number of columns to use when <sgmltag class="attribute">type</sgmltag> is set to <sgmltag class="attvalue">horiz</sgmltag> or <sgmltag class="attvalue">vert</sgmltag>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>The elements of a simple list are specified using a <sgmltag class="element">member</sgmltag> element. The contents of each<sgmltag>member</sgmltag> element can only contain character data and
+ inline elements.</para>
+ </section>
+ <section>
+ <title>Example</title>
+ <para><xref linkend="simpmarkup"/> shows the markup for a simple
+ list.</para>
+ <example id="simpmarkup" xreflabel="Example 1">
+ <title>Simple List Markup</title>
+ <programlisting><simplelist>
+ <member>Swedish Fish</member>
+ <member>Mike & Ike</member>
+ <member>Sour Patch Kids</member>
+ <member>Gummy Bears</member>
+</simplelist></programlisting>
+ </example>
+ </section>
+ </section>
+ <section>
+ <title>Itemized Lists</title>
+ <para>An itemized list is used for lists where the order of the items in
+ the list does not matter. They are like bulleted lists or the lists that
+ are created by the <sgmltag class="element">ul</sgmltag> tag in
+ HTML.</para>
+ <section>
+ <title>Specifying an Itemized List</title>
+ <para>An itemized list is specified by an <sgmltag class="element">itemizedlist</sgmltag> element. You can specify an
+ <sgmltag class="attribute">id</sgmltag> attribute for itemized lists. If
+ the list is going to referenced by an <sgmltag class="element">xref</sgmltag> element, you should also specify a value
+ for the <sgmltag class="attribute">xreflabel</sgmltag> attribute.</para>
+ <para>Each item in an itemized list is specified by a <sgmltag class="element">listitem</sgmltag> element. The <sgmltag class="element">listitem</sgmltag> element is a wrapper element and can
+ contain any container elements such as a <sgmltag class="element">para</sgmltag> element. All content within a <sgmltag class="element">listitem</sgmltag> element will be indented to the same
+ level. You can also specify sub-lists within a <sgmltag class="element">listitem</sgmltag> element.</para>
+ </section>
+ <section>
+ <title>Example</title>
+ <para><xref linkend="itemmarkup"/> shows the markup for an itemized
+ list.</para>
+ <example id="itemmarkup" xreflabel="Example 2">
+ <title>Itemized List Markup</title>
+ <programlisting><itemizedlist>
+ <listitem>
+ <para>This is the first item in my list</para>
+ </listitem>
+ <listitem>
+ <para>This is the second item in my list.</para>
+ <para>It has two paragraphs.</para>
+ </listitem>
+ <listitem>
+ <para>This item has a sublist.</para>
+ <itemizedlist>
+ <listitem><para>first</para></listitem>
+ <listitem><para>second</para></listitem>
+ </itemizedlist>
+ </listitem>
+</itemizedlist></programlisting>
+ </example>
+ </section>
+ </section>
+ <section>
+ <title>Ordered List</title>
+ <para>An ordered list is a list where the order of the elements is
+ important and made explicit. They are like numbered lists and lists that
+ are created using the <sgmltag class="element">ol</sgmltag> tag in
+ HTML.</para>
+ <section>
+ <title>Specifying an Ordered List</title>
+ <para>Ordered lists are specified by an <sgmltag class="element">orderedlist</sgmltag> element. In addition to the
+ <sgmltag class="attribute">id</sgmltag> attribute and <sgmltag class="attribute">xreflable</sgmltag> attribute, <sgmltag class="element">orderedlist</sgmltag> elements have three optional
+ elements.</para>
+ <table>
+ <title>Attributes of the <sgmltag class="element">orderedlist</sgmltag> Element</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+ <entry>Values</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <sgmltag class="attribute">continuation</sgmltag>
+ </entry>
+ <entry><sgmltag class="attvalue">continues</sgmltag>, <sgmltag class="attvalue">restarts</sgmltag>(default)</entry>
+ <entry>Specifies if the item numbering should restart at one or continue from the previous ordered list.</entry>
+ </row>
+ <row>
+ <entry>
+ <sgmltag class="attribute">inheritnum</sgmltag>
+ </entry>
+ <entry><sgmltag class="attvalue">inherit</sgmltag>, <sgmltag class="attvalue">ignore</sgmltag>(default)</entry>
+ <entry>Valid only for nested lists. Specifies if the items in the nested list contain a reference to the item of the parent list.</entry>
+ </row>
+ <row>
+ <entry>
+ <sgmltag class="attribute">numeration</sgmltag>
+ </entry>
+ <entry><sgmltag class="attvalue">arabic</sgmltag>, <sgmltag class="attvalue">loweralpha</sgmltag>, <sgmltag class="attvalue">lowerroman</sgmltag>, <sgmltag class="attvalue">upperalpha</sgmltag>, <sgmltag class="attvalue">upperroman</sgmltag></entry>
+ <entry>Specifies the numbering style to use for the list.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Items in an ordered list are specified using a <sgmltag class="element">listitem</sgmltag> element. The <sgmltag class="element">listitem</sgmltag> element is a wrapper element and can
+ contain any container elements such as a <sgmltag class="element">para</sgmltag> element. All content within a <sgmltag class="element">listitem</sgmltag> element will be indented to the same
+ level. You can also specify sub-lists within a <sgmltag class="element">listitem</sgmltag> element.</para>
+ </section>
+ </section>
+ <section>
+ <title>Segmented Lists</title>
+ <para>Segmented lists are a special type of list where the items consist
+ of a group of labeled elements. They are not used in the CXF documentation.</para>
+ </section>
+ <section>
+ <title>Variable Lists</title>
+ <para>A variable list looks similar to a glossary. It consists of a word,
+ or phrase, and some text describing the word, or phrase. <xref linkend="varexample"/> shows a variable list.</para>
+ <variablelist id="varexample">
+ <title>List of Rooms</title>
+ <varlistentry>
+ <term>Kitchen</term>
+ <listitem>
+ <para>The room where food is stored and prepared.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Garage</term>
+ <listitem>
+ <para>Where the cars are parked.</para>
+ <note>
+ <para>Bikes are also here.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Living room</term>
+ <term>Family room</term>
+ <listitem>
+ <para>This is where we watch TV.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <section>
+ <title>Specifying a Variable List</title>
+ <para>Variable lists are specified by a <sgmltag class="element">variablelist</sgmltag> element. The <sgmltag class="element">variablelist</sgmltag> element can have the optional
+ <sgmltag class="attribute">id</sgmltag> attribute and <sgmltag class="attribute">xreflable</sgmltag> attribute specified. You can also
+ supply a title for a variable list by adding a <sgmltag class="element">title</sgmltag> element as the <sgmltag class="element">variablelist</sgmltag> element's first child.</para>
+ <para>The items in a variable list are specified using a <sgmltag class="element">varlistentry</sgmltag> element. The <sgmltag class="element">varlistentry</sgmltag> element has two children elements
+ that specify the contents of the item: <sgmltag class="element">term</sgmltag> and <sgmltag class="element">listitem</sgmltag>.</para>
+ <section>
+ <title>Specifying terms</title>
+ <para>You can specify one or more <sgmltag class="element">term</sgmltag> elements in a <sgmltag class="element">varlistentry</sgmltag> element. Each <sgmltag class="element">term</sgmltag> element can contain text and inline
+ markup elements. Each <sgmltag class="element">term</sgmltag> element
+ should contain a single term or phrase that the list item
+ describes.</para>
+ </section>
+ <section>
+ <title>Describing a term</title>
+ <para>You describe the term, or terms, defined by the <sgmltag class="element">term</sgmltag> elements using a single <sgmltag class="element">listitem</sgmltag> element. The <sgmltag class="element">listitem</sgmltag> element is a wrapper element and
+ can contain any container elements such as a <sgmltag class="element">para</sgmltag> element. All content within a <sgmltag class="element">listitem</sgmltag> element will be indented to the
+ same level. You can also specify sub-lists within a <sgmltag class="element">listitem</sgmltag> element.</para>
+ </section>
+ </section>
+ <section>
+ <title>Example</title>
+ <para><xref linkend="varmarkup"/> shows the markup representing <xref linkend="varexample"/>.</para>
+ <example id="varmarkup" xreflabel="Example 3">
+ <title>Variable List Markup</title>
+ <programlisting><variablelist id="varexample">
+ <title>List of Rooms</title>
+ <varlistentry>
+ <term>Kitchen</term>
+ <listitem>
+ <para>The room where food is stored and prepared.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Garage</term>
+ <listitem>
+ <para>Where the cars are parked.</para>
+ <note>
+ <para>Bikes are also here.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Living room</term>
+ <term>Family room</term>
+ <listitem>
+ <para>This is where we watch TV.</para>
+ </listitem>
+ </varlistentry>
+</variablelist></programlisting>
+ </example>
+ </section>
+ </section>
+ <section>
+ <title>Glossary Lists</title>
+ <para>A glossary list is a special case of a variable list. It is used
+ specifically for lists that define terms and where you may want to refer
+ the reader back to the definition of a specific term. <xref linkend="glossexample"/> shows a use of a glossary list.</para>
+ <glosslist id="glossexample" xreflabel="List of terms">
+ <glossentry>
+ <glossterm id="consumerdef">consumer</glossterm>
+ <glossdef>
+ <para>The end user of a service, also called a client for that
+ service.</para>
+ </glossdef>
+ </glossentry>
+ <glossentry>
+ <glossterm id="endptdef">endpoint</glossterm>
+ <glossdef>
+ <para>The point of contact that a <glossterm linkend="servicedef">service</glossterm> provides for its <glossterm linkend="consumerdef">consumers</glossterm>.</para>
+ </glossdef>
+ </glossentry>
+ <glossentry>
+ <glossterm id="servicedef">service</glossterm>
+ <glossdef>
+ <para>A collection of operations that perform a useful set of
+ functions in a network, access to which is implemented as an
+ <glossterm linkend="endptdef">endpoint</glossterm>. In a
+ service-oriented network, services are defined by a service
+ contract.</para>
+ </glossdef>
+ </glossentry>
+ <glossentry>
+ <glossterm>service consumer</glossterm>
+ <glosssee otherterm="consumerdef"/>
+ </glossentry>
+ </glosslist>
+ <section>
+ <title>Specifying a Glossary List</title>
+ <para>A glossary list is specified using the <sgmltag class="element">glosslist</sgmltag> element. If you want to refer back
+ to a glossary list, you can provide values for the <sgmltag class="attribute">id</sgmltag> attribute and the <sgmltag class="attribute">xreflable</sgmltag> attribute. Unlike variable lists,
+ glossary lists cannot have titles.</para>
+ <para>The entries in a glossary list are specified using a <sgmltag class="element">glossentry</sgmltag> element. The <sgmltag class="element">glossentry</sgmltag> element typically has two children:
+ <sgmltag class="element">glossterm</sgmltag> and <sgmltag class="element">glossdef</sgmltag>. You can also use the <sgmltag class="element">glosssee</sgmltag> element to xref with other
+ definitions.</para>
+ <section>
+ <title>Specifying a Term</title>
+ <para>A <sgmltag class="element">glossentry</sgmltag> element can have
+ only one <sgmltag class="element">glossterm</sgmltag> element. This
+ element specifies the term being defined by this entry. If you are
+ going to refer back to this term, you can supply a value for the
+ <sgmltag class="attribute">id</sgmltag> attribute.</para>
+ <note>
+ <para>The <sgmltag class="element">glossterm</sgmltag> element can
+ also be used in text entries to refer to terms defined in a glossary
+ entry. When used in this manner, you supply a value for the <sgmltag class="attribute">linkend</sgmltag> attribute.</para>
+ </note>
+ </section>
+ <section>
+ <title>Defining a Term</title>
+ <para>You define a term using either one or more <sgmltag class="element">glossdef</sgmltag> elements or a <sgmltag class="element">glosssee</sgmltag> element. The <sgmltag class="element">glossdef</sgmltag> element is a content element that
+ contains markup specifying a definition. If you use more than one
+ <sgmltag class="element">glossdef</sgmltag> element, they are treated
+ as separate definitions for the same term.</para>
+ <para>The <sgmltag class="element">glosssee</sgmltag> element
+ redirects the reader to a term with the same meaning. It acts like a
+ "See" entry in a dictionary. It has one attribute, <sgmltag class="attribute">otherterm</sgmltag>, whose value is the id of the
+ term to which the reader is redirected.</para>
+ </section>
+ </section>
+ <section>
+ <title>Example</title>
+ <para><xref linkend="glossmarkup"/> shows the markup for <xref linkend="glossexample"/></para>
+ <example id="glossmarkup" xreflabel="Example 4">
+ <title>Glossary List Markup</title>
+ <programlisting><glosslist id="glossexample" xreflabel="List of terms">
+ <glossentry>
+ <glossterm id="consumerdef">consumer</glossterm>
+ <glossdef>
+ <para>The end user of a service, also called a client for that service.</para>
+ </glossdef>
+ </glossentry>
+ <glossentry>
+ <glossterm id="endptdef">endpoint</glossterm>
+ <glossdef>
+ <para>The point of contact that a <glossterm
+ linkend="servicedef">service</glossterm> provides for its <glossterm
+ linkend="consumerdef">consumers</glossterm>.</para>
+ </glossdef>
+ </glossentry>
+ <glossentry>
+ <glossterm id="servicedef">service</glossterm>
+ <glossdef>
+ <para>A collection of operations that perform a useful set of
+ functions in a network, access to which is implemented as an
+ <glossterm linkend="endptdef">endpoint</glossterm>. In a
+ service-oriented network, services are defined by a service
+ contract.</para>
+ </glossdef>
+ </glossentry>
+ <glossentry>
+ <glossterm>service consumer</glossterm>
+ <glosssee otherterm="consumerdef" />
+ </glossentry>
+</glosslist></programlisting>
+ </example>
+ </section>
+ </section>
</chapter>
Propchange: incubator/cxf/trunk/docs/src/docs/styleguide/lists.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: incubator/cxf/trunk/docs/src/docs/styleguide/lists.xml
------------------------------------------------------------------------------
svn:keywords = Rev Date
Propchange: incubator/cxf/trunk/docs/src/docs/styleguide/lists.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Modified: incubator/cxf/trunk/docs/src/docs/styleguide/overview.xml
URL: http://svn.apache.org/viewvc/incubator/cxf/trunk/docs/src/docs/styleguide/overview.xml?rev=436785&r1=436784&r2=436785&view=diff
==============================================================================
--- incubator/cxf/trunk/docs/src/docs/styleguide/overview.xml (original)
+++ incubator/cxf/trunk/docs/src/docs/styleguide/overview.xml Fri Aug 25 06:16:36 2006
@@ -1,130 +1,130 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<chapter>
- <title>Writing Documentation for CeltiXfire(CXF)</title>
- <section>
- <title>Why XML Based Documents?</title>
- <para>The easy answer is because XML is cool!! However, it does have some
- distinct advantages over other means of sourcing documentation:</para>
- <itemizedlist>
- <listitem>
- <para>It is stored as text files.</para>
- </listitem>
- <listitem>
- <para>It provides structure to a document.</para>
- </listitem>
- <listitem>
- <para>It is an easy way to single source documentation.</para>
- </listitem>
- </itemizedlist>
- <section>
- <title>Text vs. Binary</title>
- <para>Text files have a number of advantages over binary formats:</para>
- <itemizedlist>
- <listitem>
- <para>They tend to take up less space.</para>
- </listitem>
- <listitem>
- <para>They can be edited by a slew of freely available tools.</para>
- </listitem>
- <listitem>
- <para>They can be easily diffed when being commited to a
- repository.</para>
- </listitem>
- <listitem>
- <para>They are readable by both humans and machines.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Structure</title>
- <para>Writing documentation with a markup language may give writers
- visions of troff and LaTex. Unlike those markups, the XML tags used by
- both XDOC and Docbook are used to describe the structure of a document.
- It also provides tags to help identify different types of content with
- in your document.</para>
- <para>This means that it It makes no assumptions about the presentation
- of the content. Using a structured markup allows you to worry about
- creating and structuring your content.</para>
- </section>
- <section>
- <title>Single Source, Multiple Outputs</title>
- <para>Formating is handled by back end processing tools. CeltiXfire(CXF) uses
- Apache Forrest to generate HTML and PDF versions of its content. There
- are also a number of other tools, both open source and commercial, that
- generate documentation from XML source. This means that all of the
- writers can work on a consistent framework no matter what the eventual
- output medium is going to be.</para>
- <para>Using these tools, you can completely customize the look of your
- documentation without needing to change the documentation source. If at
- some point in the future you decide to update the look and feel of your
- documentation, you simply update the stylesheets used to process the
- XML. The source content never needs to change.</para>
- </section>
- </section>
- <section>
- <title>General Guidelines</title>
- <section>
- <title>Types of XML Used</title>
- <para>Depending on the type of document you are writing you will use one
- of two types of XML:</para>
- <itemizedlist>
- <listitem>
- <para><ulink url="#FAQ">FAQs in XDOC</ulink></para>
- </listitem>
- <listitem>
- <para><ulink url="#the_rest">Everything else in Docbook</ulink></para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Formating the XML</title>
- <para>To make the source as readable as possible there are a few general
- guidelines to follow when writing CXF documentation:</para>
- <itemizedlist>
- <listitem>
- <para>Keep lines under 100 characters long so that they can be read
- easily.</para>
- </listitem>
- <listitem>
- <para>Don't leave white space between elements.</para>
- </listitem>
- <listitem>
- <para>Use indenting to show the hierarchy.</para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- <section id="FAQ">
- <title>Writing FAQs</title>
- <para>FAQs are written using Apache's xdoc format. This format was chosen
- for its simplicity. You can find more information on the xdoc format used
- for FAQs <ulink url="http://forrest.apache.org/dtdx/faq-v20.dtdx.html">here</ulink>.</para>
- <para>Depending on the complexity of the FAQ topic, you can include FAQ
- sections inside of an FAQ document. Typically, however, an FAQ should have
- fewer than 20 questions.</para>
- <para>When naming an FAQ you need to append <filename>-faq</filename> to
- the name of the file. For example, an FAQ about the CXF JAX-WS
- implementation could be called <filename>jaxws-faq.xml</filename>.</para>
- </section>
- <section id="the_rest">
- <title>Writing General Documentation</title>
- <para>All other types of documentation are written using Docbook 4.2. Docbook 4.2
- provides a structured, XML based grammar for writing complex technical
- documentation. It is also an OASIS standard. This makes it a natural fit
- for writing open source documentation.</para>
- <para>The remainder of this style guide discusses how the CXF
- project uses Docbook. For more general references and some help getting
- familiar with Docbook, see the following:</para>
- <itemizedlist>
- <listitem>
- <para><ulink url="http://docbook.org/">Docbook.org</ulink></para>
- </listitem>
- <listitem>
- <para><ulink url="http://opensource.bureau-cornavin.com/crash-course/">The Crash Course to Docbook</ulink></para>
- </listitem>
- <listitem>
- <para><ulink url="http://nwalsh.com/docbook/">Norman Walsh's Docbook page</ulink></para>
- </listitem>
- </itemizedlist>
- </section>
+<?xml version='1.0' encoding='UTF-8'?>
+<chapter>
+ <title>Writing Documentation for CeltiXfire(CXF)</title>
+ <section>
+ <title>Why XML Based Documents?</title>
+ <para>The easy answer is because XML is cool!! However, it does have some
+ distinct advantages over other means of sourcing documentation:</para>
+ <itemizedlist>
+ <listitem>
+ <para>It is stored as text files.</para>
+ </listitem>
+ <listitem>
+ <para>It provides structure to a document.</para>
+ </listitem>
+ <listitem>
+ <para>It is an easy way to single source documentation.</para>
+ </listitem>
+ </itemizedlist>
+ <section>
+ <title>Text vs. Binary</title>
+ <para>Text files have a number of advantages over binary formats:</para>
+ <itemizedlist>
+ <listitem>
+ <para>They tend to take up less space.</para>
+ </listitem>
+ <listitem>
+ <para>They can be edited by a slew of freely available tools.</para>
+ </listitem>
+ <listitem>
+ <para>They can be easily diffed when being commited to a
+ repository.</para>
+ </listitem>
+ <listitem>
+ <para>They are readable by both humans and machines.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Structure</title>
+ <para>Writing documentation with a markup language may give writers
+ visions of troff and LaTex. Unlike those markups, the XML tags used by
+ both XDOC and Docbook are used to describe the structure of a document.
+ It also provides tags to help identify different types of content with
+ in your document.</para>
+ <para>This means that it It makes no assumptions about the presentation
+ of the content. Using a structured markup allows you to worry about
+ creating and structuring your content.</para>
+ </section>
+ <section>
+ <title>Single Source, Multiple Outputs</title>
+ <para>Formating is handled by back end processing tools. CeltiXfire(CXF) uses
+ Apache Forrest to generate HTML and PDF versions of its content. There
+ are also a number of other tools, both open source and commercial, that
+ generate documentation from XML source. This means that all of the
+ writers can work on a consistent framework no matter what the eventual
+ output medium is going to be.</para>
+ <para>Using these tools, you can completely customize the look of your
+ documentation without needing to change the documentation source. If at
+ some point in the future you decide to update the look and feel of your
+ documentation, you simply update the stylesheets used to process the
+ XML. The source content never needs to change.</para>
+ </section>
+ </section>
+ <section>
+ <title>General Guidelines</title>
+ <section>
+ <title>Types of XML Used</title>
+ <para>Depending on the type of document you are writing you will use one
+ of two types of XML:</para>
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="#FAQ">FAQs in XDOC</ulink></para>
+ </listitem>
+ <listitem>
+ <para><ulink url="#the_rest">Everything else in Docbook</ulink></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Formating the XML</title>
+ <para>To make the source as readable as possible there are a few general
+ guidelines to follow when writing CXF documentation:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Keep lines under 100 characters long so that they can be read
+ easily.</para>
+ </listitem>
+ <listitem>
+ <para>Don't leave white space between elements.</para>
+ </listitem>
+ <listitem>
+ <para>Use indenting to show the hierarchy.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ <section id="FAQ">
+ <title>Writing FAQs</title>
+ <para>FAQs are written using Apache's xdoc format. This format was chosen
+ for its simplicity. You can find more information on the xdoc format used
+ for FAQs <ulink url="http://forrest.apache.org/dtdx/faq-v20.dtdx.html">here</ulink>.</para>
+ <para>Depending on the complexity of the FAQ topic, you can include FAQ
+ sections inside of an FAQ document. Typically, however, an FAQ should have
+ fewer than 20 questions.</para>
+ <para>When naming an FAQ you need to append <filename>-faq</filename> to
+ the name of the file. For example, an FAQ about the CXF JAX-WS
+ implementation could be called <filename>jaxws-faq.xml</filename>.</para>
+ </section>
+ <section id="the_rest">
+ <title>Writing General Documentation</title>
+ <para>All other types of documentation are written using Docbook 4.2. Docbook 4.2
+ provides a structured, XML based grammar for writing complex technical
+ documentation. It is also an OASIS standard. This makes it a natural fit
+ for writing open source documentation.</para>
+ <para>The remainder of this style guide discusses how the CXF
+ project uses Docbook. For more general references and some help getting
+ familiar with Docbook, see the following:</para>
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://docbook.org/">Docbook.org</ulink></para>
+ </listitem>
+ <listitem>
+ <para><ulink url="http://opensource.bureau-cornavin.com/crash-course/">The Crash Course to Docbook</ulink></para>
+ </listitem>
+ <listitem>
+ <para><ulink url="http://nwalsh.com/docbook/">Norman Walsh's Docbook page</ulink></para>
+ </listitem>
+ </itemizedlist>
+ </section>
</chapter>
Propchange: incubator/cxf/trunk/docs/src/docs/styleguide/overview.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: incubator/cxf/trunk/docs/src/docs/styleguide/overview.xml
------------------------------------------------------------------------------
svn:keywords = Rev Date
Propchange: incubator/cxf/trunk/docs/src/docs/styleguide/overview.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml