incubator-cloudstack-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ahu...@apache.org
Subject [30/32] git commit: Add XML tags tutorial to README for doc contributors.
Date Thu, 16 Aug 2012 23:49:03 GMT
Add XML tags tutorial to README for doc contributors.


Project: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/commit/103057c8
Tree: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/tree/103057c8
Diff: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/diff/103057c8

Branch: refs/heads/4.0
Commit: 103057c85d61b7e0f2f30f12a9cd7cdf525b814d
Parents: a267a45
Author: Jessica Tomechak <jessica.tomechak@gmail.com>
Authored: Wed Aug 15 14:40:16 2012 -0700
Committer: Alex Huang <alex.huang@citrix.com>
Committed: Thu Aug 16 16:33:19 2012 -0700

----------------------------------------------------------------------
 docs/README.txt |  163 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 162 insertions(+), 1 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/103057c8/docs/README.txt
----------------------------------------------------------------------
diff --git a/docs/README.txt b/docs/README.txt
index b922bb8..f8b420f 100644
--- a/docs/README.txt
+++ b/docs/README.txt
@@ -37,6 +37,10 @@ VALID XML TAGS
 Certain tags are disallowed by Publican. Please consult their documentation for more details.
 http://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/
 
+Your best bet is to copy an existing XML file and fill in your own content between the tags.
+
+At the bottom of this README, there is a fill-in-the-blanks XML template that you can go
from. It shows the commonly used tags and explains a bit about how to use them.
+
 
 ----------------------------------
 
@@ -117,4 +121,161 @@ CONTRIBUTING
 
 ----------------------------------
 
-Contributors can create new section, chapter, book, publican.cfg, or localized .xml files
at any time. Submit them following the same patch approval procedure that is used for contributing
to CloudStack code. More information for contributors is available at https://cwiki.apache.org/confluence/display/CLOUDSTACK/Documentation+Team.
\ No newline at end of file
+Contributors can create new section, chapter, book, publican.cfg, or localized .xml files
at any time. Submit them following the same patch approval procedure that is used for contributing
to CloudStack code. More information for contributors is available at https://cwiki.apache.org/confluence/display/CLOUDSTACK/Documentation+Team.
+
+----------------------------------
+
+TAGS FOR A SECTION
+----------------------------------
+
+
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0.
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<!-- Please keep the doctype and license declarations above intact in each doc file. 
-->
+<!-- Make your modifications below this line.  -->
+
+<section id="INSERT A UNIQUE SECTION ID HERE, PROBABLY MATCHING THE TITLE BELOW. KEEP
THE QUOTE MARKS.">
+	<title>Text of the section title</title>
+    <para>Here�s the text of a paragraph in this section.</para>
+    <para>Always use &PRODUCT; rather than typing CloudStack or CloudPlatform.</para>
+    <para>Indent with 4 spaces, not with tab characters.</para>
+    <para>To hyperlink to a URL outside this document: <ulink url="http://external
URL here">Display text of the link here</ulink></para>
+    <para>To hyperlink to another section in this document: <xref linkend="SECTION
ID OF THE OTHER SECTION GOES HERE." />
+        The publication tools will automatically insert the display text of the link for
you.</para>
+    <note><para>Use this for all tips and asides. Don�t use other tags such
as tip.
+        Our publication tool (publican) prefers the note tag. The tool will 
+        automatically insert the text NOTE: for you, so please don�t type it.</para></note>
+    <warning><para>Use this for anything that is vital to avoid runtime errors.
Don�t use
+        other tags such as caution. Our publication tool (publican) prefers the warning tag.
The tool will
+        automatically insert the text WARNING: for you, so please don�t type it.</para></warning>
+    <para>Here�s how to do a bulleted list:</para>
+    <itemizedlist>
+        <listitem><para>Bulleted list item text.</para></listitem>
+    </itemizedlist>
+    <para>Here�s how to do a numbered list. These are used for step by step instructions

+        or to describe a sequence of events in time. For everything else, use a bulleted
list.</para>
+    <orderedlist>
+        <listitem><para>Text of the step</para></listitem>
+        <listitem><para>You might also want a sub-list within one of the list
items. Like this:</para>
+            <orderedlist numeration="loweralpha">
+                <listitem><para>Inner list item text.</para></listitem>
+            </orderedlist>
+        </listitem>
+    </orderedlist>
+    <para>Here�s how to insert an image. Put the graphic file in images/, a subdirectory
of the directory where this XML file is.
+        Refer to it using this tag. The tag is admittedly complex, but it�s the one we
need to use with publican:</para>
+    <mediaobject>
+        <imageobject>
+            <imagedata fileref="./images/YOUR_FILENAME_HERE.png" />
+        </imageobject>
+        <textobject><phrase>YOUR_FILENAME_HERE.png: Alt text describing this
image, such as 
+            �structure of a zone.� Required for accessibility.</phrase></textobject>
+    </mediaobject>
+    <para>A section can contain sub-sections. Please make each sub-section a separate
file to enable reuse.
+        Then include the sub-section like this:</para>
+    <xi:include href="SUBSECTION_FILE_NAME.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+</section>
+
+
+
+----------------------------------
+
+TAGS FOR A CHAPTER
+----------------------------------
+
+
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0.
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<!-- Please keep the doctype and license declarations above intact in each doc file. 
-->
+<!-- Make your modifications below this line.  -->
+
+<chapter id="INSERT A UNIQUE SECTION ID HERE, PROBABLY MATCHING THE TITLE BELOW. KEEP
THE QUOTE MARKS.">
+    <title>Text of the chapter title</title>
+    <xi:include href="SECTION_ONE_FILENAME.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+    <xi:include href="SECTION_TWO_FILENAME.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+</chapter>
+
+
+
+----------------------------------
+
+TAGS FOR A BOOK
+----------------------------------
+
+
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0.
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<!-- Please keep the doctype and license declarations above intact in each doc file. 
-->
+<!-- Make your modifications below this line.  -->
+
+<book>
+    <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+    <xi:include href="CHAPTER_ONE_FILENAME.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+    <xi:include href="CHAPTER_TWO_FILENAME.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+</book>
+
+----------------------------------
+
+BASIC RULES FOR INCLUDE STATEMENTS
+----------------------------------
+
+A book file must include chapter files.
+A chapter file must include section files.
+A section file can include other section files, but it doesn't have to.


Mime
View raw message