Updated Branches: refs/heads/master ccf99beae -> a25e149f8
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/a25e149f Tree: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/tree/a25e149f Diff: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/diff/a25e149f Branch: refs/heads/master Commit: a25e149f8a9769cd7038f48a3e57a874abde8a03 Parents: ccf99be Author: Jessica Tomechak <[email protected]> Authored: Wed Aug 15 14:40:16 2012 -0700 Committer: Jessica Tomechak <[email protected]> Committed: Wed Aug 15 15:43:21 2012 -0700 ---------------------------------------------------------------------- docs/README.txt | 163 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 files changed, 162 insertions(+), 1 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/a25e149f/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.
