commit: 4e21f95eba403dfb17619a6eff9e673c8e6575da Author: Brian Evans <grknight <AT> gentoo <DOT> org> AuthorDate: Tue Mar 19 17:10:14 2019 +0000 Commit: Brian Evans <grknight <AT> gentoo <DOT> org> CommitDate: Tue Mar 19 17:10:14 2019 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=4e21f95e
Fix missing GuideXML instructions Include the CVS copy in this repo Closes: https://bugs.gentoo.org/615366 Signed-off-by: Brian Evans <grknight <AT> gentoo.org> appendices/contributing/devbook/text.xml | 1213 ++++++++++++++++++++++++++++++ appendices/contributing/text.xml | 10 +- 2 files changed, 1221 insertions(+), 2 deletions(-) diff --git a/appendices/contributing/devbook/text.xml b/appendices/contributing/devbook/text.xml new file mode 100644 index 0000000..f1a5d57 --- /dev/null +++ b/appendices/contributing/devbook/text.xml @@ -0,0 +1,1213 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="appendices/contributing/devbook/"> +<title>Gentoo GuideXML Guide</title> + +<author title="Author"> + <mail link="neysx"/> +</author> +<author title="Author"> + <mail link="drobb...@gentoo.org">Daniel Robbins</mail> +</author> +<author title="Author"><!-- z...@gentoo.org --> + John P. Davis +</author> +<author title="Editor"> + <mail link="pe...@gentoo.org">Jorge Paulo</mail> +</author> +<author title="Editor"> + <mail link="sw...@gentoo.org">Sven Vermeulen</mail> +</author> +<author title="Editor"> + <mail link="nightmorph"/> +</author> + +<abstract> +This guide shows you how to compose web documentation using the new lightweight +Gentoo GuideXML syntax. This syntax is the official format for Gentoo +documentation, and this document itself was created using GuideXML. This guide +assumes a basic working knowledge of XML and HTML. +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See https://creativecommons.org/licenses/by-sa/2.5 --> +<license/> + +<version>13</version> +<date>2012-10-07</date> + +<chapter> +<title>GuideXML basics</title> +<section> +<title>GuideXML design goals</title> +<body> + +<p> +The guideXML syntax is lightweight yet expressive, so that it is easy to +learn yet also provides all the features we need for the creation of web +documentation. The number of tags is kept to a minimum -- just those we need. +This makes it easy to transform guide into other formats, such as DocBook +XML/SGML or web-ready HTML. +</p> + +<p> +The goal is to make it easy to <e>create</e> and <e>transform</e> guideXML +documents. +</p> + +</body> +</section> +<section> +<title>Further Resources</title> +<body> + +<p> +You may want to look at the <uri link="text.xml">XML source</uri> of this +document while you read it. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>GuideXML</title> +<section> +<title>Basic structure</title> +<body> + +<p> +Let's start learning the GuideXML syntax. We'll start with the the initial +tags used in a GuideXML document: +</p> + +<pre caption="The initial part of a guide XML document"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<!-- $Header$ --> + +<guide lang="<i>en</i>"> +<title><i>Gentoo Documentation Guide</i></title> + +<author title="<i>Author</i>"> + <mail link="<i>yourn...@gentoo.org</i>"><i>Your Name</i></mail> +</author> + +<abstract> +<i>This guide shows you how to compose web documentation using +our new lightweight Gentoo GuideXML syntax. This syntax is the official +format for Gentoo web documentation, and this document itself was created +using GuideXML.</i> +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See https://creativecommons.org/licenses/by-sa/3.0 --> +<license version="3.0"/> + +<version><i>1</i></version> +<date><i>2011-11-29</i></date> +</pre> + +<p> +On the first lines, we see the requisite tag that identifies this as an XML +document and specifies its DTD. The <c><!-- $Header$ --></c> line +will be automatically modified by the CVS server and helps to track revisions. +Next, there's a <c><guide></c> tag -- the entire guide document is +enclosed within a <c><guide> </guide></c> pair. +<br/> +The <c>lang</c> attribute should be used to specify the language code of your +document. It is used to format the date and insert strings like "<e>Note</e>", +"<e>Content</e>", etc. in the specified language. The default is English. +</p> + +<p> +Next, there's a <c><title></c> tag, used to set the title for the entire +guide document. +</p> + +<p> +Then, we come to the <c><author></c> tags, which contain information +about the various authors of the document. Each <c><author></c> tag +allows for an optional <c>title</c> element, used to specify the author's +relationship to the document (author, co-author, editor, etc.). In this +particular example, the authors' names are enclosed in another tag -- a +<c><mail></c> tag, used to specify an email address for this particular +person. The <c><mail></c> tag is optional and can be omitted, and at +least one <c><author></c> element is required per guide document. +</p> + +<p> +Next, we come to the <c><abstract></c>, <c><version></c> and +<c><date></c> tags, used to specify a summary of the document, the +current version number, and the current version date (in YYYY-MM-DD format) +respectively. Dates that are invalid or not in the YYYY-MM-DD format will +appear verbatim in the rendered document. +</p> + +<p> +This sums up the tags that should appear at the beginning of a guide document. +Besides the <c><title></c> and <c><mail></c> tags, these tags +shouldn't appear anywhere else except immediately inside the +<c><guide></c> tag, and for consistency it's recommended (but not +required) that these tags appear before the content of the document. +</p> + +<p> +Finally we have the <c><license version="3.0"/></c> tag, used to publish +the document under the <uri link="https://creativecommons.org/licenses/by-sa/3.0/";>Creative +Commons - Attribution / Share Alike</uri> license as required by the <uri +link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>. Historically, +the tag <c><license /></c> was used, which denoted the 2.5 version of the +license. This is still accepted/allowed. +</p> + +</body> +</section> +<section> +<title>Chapters and sections</title> +<body> + +<p> +Once the initial tags have been specified, you're ready to start adding the +structural elements of the document. Guide documents are divided into +chapters, and each chapter can hold one or more sections. Every chapter and +section has a title. Here's an example chapter with a single section, +consisting of a paragraph. If you append this XML to the XML in the <uri +link="#doc_chap2_pre1">previous excerpt</uri> and append a +<c></guide></c> to the end of the file, you'll have a valid (if minimal) +guide document: +</p> + +<pre caption="Minimal guide example"> +<chapter> +<title><i>This is my chapter</i></title> +<section> +<title><i>This is section one of my chapter</i></title> +<body> + +<p> +<i>This is the actual text content of my section.</i> +</p> + +</body> +</section> +</chapter> +</pre> + +<p> +Above, I set the chapter title by adding a child <c><title></c> +element to the <c><chapter></c> element. Then, I created a section by +adding a <c><section></c> element. If you look inside the +<c><section></c> element, you'll see that it has two child elements -- a +<c><title></c> and a <c><body></c>. While the <c><title></c> +is nothing new, the <c><body></c> is -- it contains the actual text +content of this particular section. We'll look at the tags that are allowed +inside a <c><body></c> element in a bit. +</p> + +<note> +A <c><guide></c> element must contain at least one <c><chapter></c> +elements, a <c><chapter></c> must contain at least one +<c><section></c> elements and a <c><section></c> element must +contain at least one <c><body></c> element. +</note> + +</body> +</section> +<section> +<title>An example <body></title> +<body> + +<p> +Now, it's time to learn how to mark up actual content. Here's the XML code for +an example <c><body></c> element: +</p> + +<pre caption="Example of a body element"> +<p> +This is a paragraph. <path>/etc/passwd</path> is a file. +<uri>https://forums.gentoo.org</uri> is my favorite website. +Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. +</p> + +<pre caption="Code Sample"> +This is text output or code. +# <i>this is user input</i> + +Make HTML/XML easier to read by using selective emphasis: +<foo><i>bar</i></foo> + +<comment>(This is how to insert a comment into a code block)</comment> +</pre> + +<note> +This is a note. +</note> + +<warn> +This is a warning. +</warn> + +<impo> +This is important. +</impo> +</pre> + +<p> +Now, here's how the <c><body></c> element above is rendered: +</p> + +<p> +This is a paragraph. <path>/etc/passwd</path> is a file. +<uri>https://forums.gentoo.org</uri> is my favorite web site. +Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. +</p> + +<pre caption="Code Sample"> +This is text output or code. +# <i>this is user input</i> + +Make HTML/XML easier to read by using selective emphasis: +<foo><i>bar</i></foo> + +<comment>(This is how to insert a comment into a code block)</comment> +</pre> + +<note> +This is a note. +</note> + +<warn> +This is a warning. +</warn> + +<impo> +This is important. +</impo> + +</body> +</section> +<section> +<title>The <body> tags</title> +<body> + +<p> +We introduced a lot of new tags in the previous section -- here's what you need +to know. The <c><p></c> (paragraph), <c><pre></c> (code block), +<c><note></c>, <c><warn></c> (warning) and <c><impo></c> +(important) tags all can contain one or more lines of text. Besides the +<c><table></c>, <c><ul></c>, <c><ol></c> and +<c><dl></c> elements (which we'll cover in just a bit), these are the +only tags that should appear immediately inside a <c><body></c> element. +Another thing -- these tags <e>should not</e> be stacked -- in other words, +don't put a <c><note></c> element inside a <c><p></c> element. As +you might guess, the <c><pre></c> element preserves its whitespace +exactly, making it well-suited for code excerpts. You must name the +<c><pre></c> tag with a <c>caption</c> attribute: +</p> + +<pre caption="Named <pre>"> +<pre caption="Output of uptime"> +# <i>uptime</i> +16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 +</pre> +</pre> + +</body> +</section> +<section> +<title>Epigraphs</title> +<body> + +<p by="Anonymous student"> +Delegates from the original 13 states formed the Contented Congress. Thomas +Jefferson, a Virgin, and Benjamin Franklin were two singers of the Declaration +of Independence. Franklin discovered electricity by rubbing two cats backwards +and declared, "A horse divided against itself cannot stand." Franklin died in +1790 and is still dead. +</p> + +<p> +Epigraphs are sometimes used at the beginning of chapters to illustrate what is +to follow. It is simply a paragraph with a <c>by</c> attribute that contains +the signature. +</p> + +<pre caption="Short epigraph"> +<p by="Anonymous student"> +Delegates from the original 13 states formed the... +</p> +</pre> + +</body> +</section> +<section> +<title> + <path>, <c>, <b>, <e>, <sub> and <sup> +</title> +<body> + +<p> +The <c><path></c>, <c><c></c>, <c><b></c>, <c><e></c>, +<c><sub></c> and <c><sup></c> elements can be used inside any child +<c><body></c> tag, except for <c><pre></c>. +</p> + +<p> +The <c><path></c> element is used to mark text that refers to an +<e>on-disk file</e> -- either an <e>absolute or relative path</e>, or a +<e>simple filename</e>. This element is generally rendered with a mono spaced +font to offset it from the standard paragraph type. +</p> + +<p> +The <c><c></c> element is used to mark up a <e>command</e> or <e>user +input</e>. Think of <c><c></c> as a way to alert the reader to something +that they can type in that will perform some kind of action. For example, all +the XML tags displayed in this document are enclosed in a <c><c></c> +element because they represent something that the user could type in that is +not a path. By using <c><c></c> elements, you'll help your readers +quickly identify commands that they need to type in. Also, because +<c><c></c> elements are already offset from regular text, <e>it is rarely +necessary to surround user input with double-quotes</e>. For example, don't +refer to a "<c><c></c>" element like I did in this sentence. Avoiding +the use of unnecessary double-quotes makes a document more readable -- and +adorable! +</p> + +<p> +As you might have guessed, <c><b></c> is used to <b>boldface</b> some +text. +</p> + +<p> +<c><e></c> is used to apply emphasis to a word or phrase; for example: +I <e>really</e> should use semicolons more often. As you can see, this text is +offset from the regular paragraph type for emphasis. This helps to give your +prose more <e>punch</e>! +</p> + +<p> +The <c><sub></c> and <c><sup></c> elements are used to specify +<sub>subscript</sub> and <sup>superscript</sup>. +</p> + +</body> +</section> +<section> +<title>Code samples and colour-coding</title> +<body> + +<p> +To improve the readability of code samples, the following tags are allowed +inside <c><pre></c> blocks: +</p> + +<dl> + <dt><c><i></c></dt> + <dd>Distinguishes user input from displayed text</dd> + <dt><c><comment></c></dt> + <dd>Comments relevant to the action(s) that appear after the comment</dd> + <dt><c><keyword></c></dt> + <dd>Denotes a keyword in the language used in the code sample + </dd> + <dt><c><ident></c></dt> + <dd>Used for an identifier + </dd> + <dt><c><const></c></dt> + <dd>Used for a constant + </dd> + <dt><c><stmt></c></dt> + <dd>Used for a statement + </dd> + <dt><c><var></c></dt> + <dd>Used for a variable + </dd> +</dl> + +<note> +Remember that all leading and trailing spaces, and line breaks in +<c><pre></c> blocks will appear in the displayed html page. +</note> + +<p> +Sample colour-coded <c><pre></c> block: +</p> + +<pre caption="My first ebuild"> +<comment># Copyright 1999-2009 <b>Gentoo Foundation</b> +# Distributed under the terms of the GNU General Public License v2 +# $Header: $</comment> + +<ident>DESCRIPTION</ident>=<const>"Exuberant ctags generates tags files for quick source navigation"</const> +<ident>HOMEPAGE</ident>=<const>"https://ctags.sourceforge.net";</const> +<ident>SRC_URI</ident>=<const>"mirror://sourceforge/ctags/<var>${P}</var>.tar.gz"</const> + +<ident>LICENSE</ident>=<const>"GPL-2"</const> +<ident>SLOT</ident>=<const>"0"</const> +<ident>KEYWORDS</ident>=<const>"~mips ~sparc ~x86"</const> +<ident>IUSE</ident>=<const>""</const> + +<stmt>src_compile()</stmt> { + <keyword>econf</keyword> --with-posix-regex + <keyword>emake</keyword> || <keyword>die</keyword> <const>"emake failed"</const> +} + +<stmt>src_install()</stmt> { + <keyword>make</keyword> <ident>DESTDIR</ident>="<var>${D}</var>" install || <keyword>die</keyword> <const>"install failed"</const> + + <keyword>dodoc</keyword> FAQ NEWS README + <keyword>dohtml</keyword> EXTENDING.html ctags.html +} +</pre> + +</body> +</section> +<section> +<title><mail> and <uri></title> +<body> + +<p> +We've taken a look at the <c><mail></c> tag earlier; it's used to link +some text with a particular email address, and takes the form <c><mail +link="foo....@example.com">Mr. Foo Bar</mail></c>. If you want to display the +email address, you can use <c><mail>foo....@example.com</mail></c>, this +would be displayed as <mail>foo....@example.com</mail>. +</p> + +<p> +Shorter forms make it easier to use names and emails of Gentoo developers. Both +<c><mail>neysx</mail></c> and <c><mail link="neysx"/></c> +would appear as <mail>neysx</mail>. If you want to use a Gentoo dev's email +with a different content than his full name, use the second form with some +content. For instance, use a dev's first name: <c><mail +link="neysx">Xavier</mail></c> appears as <mail +link="neysx">Xavier</mail>. +<br/> +This is particularly useful when you want to name a developer whose name +contains "funny" characters that you can't type. +</p> + +<p> +The <c><uri></c> tag is used to point to files/locations on the Internet. +It has two forms -- the first can be used when you want to have the actual URI +displayed in the body text, such as this link to +<uri>https://forums.gentoo.org/</uri>. To create this link, I typed +<c><uri>https://forums.gentoo.org/</uri></c>. The alternate form is +when you want to associate a URI with some other text -- for example, <uri +link="https://forums.gentoo.org/";>the Gentoo Forums</uri>. To create +<e>this</e> link, I typed <c><uri link="https://forums.gentoo.org/">the +Gentoo Forums</uri></c>. You don't need to write +<c>https://www.gentoo.org/</c> to link to other parts of the Gentoo web site. +For instance, a link to the <uri link="/get-started/about/">about page</uri> +should be simply <c><uri link="/get-started/about/">documentation main +index</uri></c>. Leaving the trailing slash saves an extra HTTP request. +</p> + +<p> +You should not use a <c><uri></c> tag with a <c>link</c> attribute that +starts with <c>mailto:</c>. In this case, use a <c><mail></c> tag. +</p> + +<p> +Please avoid the <uri link="https://en.wikipedia.org/wiki/Click_here";>click here +syndrome</uri> as recommended by the <uri +link="https://www.w3.org/QA/Tips/noClickHere";>W3C</uri>. +</p> + +</body> +</section> +<section> +<title>Figures</title> +<body> + +<p> +Here's how to insert a figure into a document -- <c><figure +link="mygfx.png" short="my picture" caption="my favorite picture of all +time"/></c>. The <c>link</c> attribute points to the actual graphic image, +the <c>short</c> attribute specifies a short description (currently used for +the image's HTML <c>alt</c> attribute), and a caption. Not too difficult +:) We also support the standard HTML-style <img src="foo.gif"/> tag +for adding images without captions, borders, etc. +</p> + +</body> +</section> +<section> +<title>Tables</title> +<body> + +<p> +GuideXML supports a simplified table syntax similar to that of HTML. To start a +table, use a <c><table></c> tag. Start a row with a <c><tr></c> +tag. However, for inserting actual table data, we <e>don't</e> support the HTML +<td> tag; instead, use the <c><th></c> if you are inserting a +header, and <c><ti></c> if you are inserting a normal informational +block. You can use a <c><th></c> anywhere you can use a <c><ti></c> +-- there's no requirement that <c><th></c> elements appear only in the +first row. +</p> + +<p> +Besides, both table headers (<c><th></c>) and table items +(<c><ti></c>) accept the <c>colspan</c> and <c>rowspan</c> attributes to +span their content across rows, columns or both. +</p> + +<p> +Furthermore, table cells (<c><ti></c> & <c><th></c>) can be +right-aligned, left-aligned or centered with the <c>align</c> attribute. +</p> + +<table> + <tr> + <th align="center" colspan="4">This title spans 4 columns</th> + </tr> + <tr> + <th rowspan="6">This title spans 6 rows</th> + <ti>Item A1</ti> + <ti>Item A2</ti> + <ti>Item A3</ti> + </tr> + <tr> + <ti align="center">Item B1</ti> + <th colspan="2" rowspan="2" align="right">Blocky 2x2 title</th> + </tr> + <tr> + <ti align="right">Item C1</ti> + </tr> + <tr> + <ti colspan="3" align="center">Item D1..D3</ti> + </tr> + <tr> + <ti rowspan="2">Item E1..F1</ti> + <ti colspan="2" align="right">Item E2..E3</ti> + </tr> + <tr> + <ti colspan="2" align="right">Item F2..F3</ti> + </tr> +</table> + +</body> +</section> +<section> +<title>Lists</title> +<body> + +<p> +To create ordered or unordered lists, simply use the XHTML-style +<c><ol></c>, <c><ul></c> and <c><li></c> tags. Lists may only +appear inside the <c><body></c> and <c><li></c> tags which means +that you can have lists inside lists. Don't forget that you are writing XML and +that you must close all tags including list items unlike in HTML. +</p> + +<p> +Definition lists (<c><dl></c>) are also supported. Please note that +neither the definition term tag (<c><dt></c>) nor the definition data tag +(<c><dd></c>) accept any other block level tag such as paragraphs or +admonitions. A definition list comprises: +</p> + +<dl> + <dt><c><dl></c></dt> + <dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd> + <dt><c><dt></c></dt> + <dd>Pairs of <b>D</b>efinition <b>T</b>erm Tags</dd> + <dt><c><dd></c></dt> + <dd>and <b>D</b>efinition <b>D</b>ata Tags</dd> +</dl> + +<p> +The following list copied from <uri +link="https://www.w3.org/TR/REC-html40/struct/lists.html";>w3.org</uri> shows +that a definition list can contain ordered and unordered lists. It may not +contain another definition list though. +</p> + +<dl> + <dt><b>The ingredients:</b></dt> + <dd> + <ul> + <li>100 g. flour</li> + <li>10 g. sugar</li> + <li>1 cup water</li> + <li>2 eggs</li> + <li>salt, pepper</li> + </ul> + </dd> + <dt><b>The procedure:</b></dt> + <dd> + <ol> + <li>Mix dry ingredients thoroughly</li> + <li>Pour in wet ingredients</li> + <li>Mix for 10 minutes</li> + <li>Bake for one hour at 300 degrees</li> + </ol> + </dd> + <dt><b>Notes:</b></dt> + <dd>The recipe may be improved by adding raisins</dd> +</dl> + +</body> +</section> +<section> +<title>Intra-document references</title> +<body> + +<p> +GuideXML makes it really easy to reference other parts of the document using +hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter +One</uri> by typing <c><uri link="#doc_chap1">Chapter +One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of +Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of +Chapter One</uri></c>. To refer to figure 3 in chapter 1, type +<c><uri link="#doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer +to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type +<c><uri link="#doc_chap2_pre2">code listing 2.2</uri></c>. +</p> + +<p> +However, some guides change often and using such "counting" can lead to broken +links. In order to cope with this, you can define a name for a +<c><chapter></c>, <c><section></c> or a <c><tr></c> by using +the <c>id</c> attribute, and then point to that attribute, like this: +</p> + +<pre caption="Using the id attribute"> +<chapter id="foo"> +<title>This is foo!</title> +... +<p> +More information can be found in the <uri link="#foo">foo chapter</uri> +</p> +</pre> + +</body> +</section> +<section> +<title>Disclaimers and obsolete documents</title> +<body> + +<p> +A <c>disclaimer</c> attribute can be applied to guides and handbooks to display +a predefined disclaimer at the top of the document. The available disclaimers +are: +</p> + +<ul> + <li> + <b>articles</b> is used for <uri link="/doc/en/articles/">republished + articles</uri> + </li> + <li> + <b>draft</b> is used to indicate a document is still being worked on and + should not be considered official + </li> + <li> + <b>oldbook</b> is used on old handbooks to indicate they are not maintained + anymore + </li> + <li><b>obsolete</b> is used to mark a document as obsolete.</li> +</ul> + +<p> +When marking a document as obsolete, you might want to add a link to a new +version. The <c>redirect</c> attribute does just that. The user might be +automatically redirected to the new page but you should not rely on that +behaviour. +</p> + +<pre caption="Disclaimer sample"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<!-- $Header$ --> + +<guide disclaimer="obsolete" redirect="https://wiki.gentoo.org/wiki/Handbook:X86"> +<title>Gentoo x86 Installation Guide</title> + +<author title="Author"> +... +</pre> + +</body> +</section> +<section> +<title>FAQs</title> +<body> + +<p> +FAQ documents need to start with a list of questions with links to their +answers. Creating such a list is both time-consuming and error-prone. The list +can be created automatically if you use a <c>faqindex</c> element as the first +chapter of your document. This element has the same structure as a +<c>chapter</c> to allow some introductory text. The structure of the document +is expected to be split into chapters (at least one chapter) containing +sections, each section containing one question specified in its <c>title</c> +element with the answer in its <c>body</c>. The FAQ index will appear as one +section per chapter and one link per question. +</p> + +<p> +A quick look at a <uri link="/doc/en/faq.xml">FAQ</uri> and <uri +link="/doc/en/faq.xml?passthru=1">its source</uri> should make the above +obvious. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Handbook Format</title> +<section> +<title>Guide vs Book</title> +<body> + +<p> +For high-volume documentation, a +broader format was needed. We designed a GuideXML-compatible enhancement that +allows us to write modular and multi-page documentation. +</p> + +</body> +</section> +<section> +<title>Main File</title> +<body> + +<p> +The first change is the need for a "master" document. This document contains no +real content, but links to the individual documentation modules. The syntax +doesn't differ much from GuideXML: +</p> + +<pre caption="Example book usage"> +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE book SYSTEM "/dtd/book.dtd"> +<!-- $Header$ --> + +<<i>book</i>> +<title>Example Book Usage</title> + +<author...> + ... +</author> + +<abstract> + ... +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See https://creativecommons.org/licenses/by-sa/3.0 --> +<license version="3.0"/> + +<version>...</version> +<date>...</date> +</pre> + +<p> +So far no real differences (except for the <c><book></c> instead of +<c><guide></c> tag). Instead of starting with the individual +<c><chapter></c>s, you define a <c><part></c>, which is the +equivalent of a separate part in a book: +</p> + +<pre caption="Defining a part"> +<part> +<title>Part One</title> +<abstract> + ... +</abstract> + +<comment>(Defining the several chapters)</comment> +</part> +</pre> + +<p> +Each part is accompanied by a <c><title></c> and an +<c><abstract></c> which gives a small introduction to the part. +</p> + +<p> +Inside each part, you define the individual <c><chapter></c>s. Each +chapter <e>must</e> be a separate document. As a result it is no surprise that +a special tag (<c><include></c>) is added to allow including the separate +document. +</p> + +<pre caption="Defining a chapter"> +<chapter> +<title>Chapter One</title> + + <include href="path/to/chapter-one.xml"/> + +</chapter> +</pre> + +</body> +</section> +<section> +<title>Designing the Individual Chapters</title> +<body> + +<p> +The content of an individual chapter is structured as follows: +</p> + +<pre caption="Chapter Syntax"> +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> +<!-- $Header$ --> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See https://creativecommons.org/licenses/by-sa/3.0 --> + +<sections> + +<abstract> + This is a small explanation on chapter one. +</abstract> + +<version>...</version> +<date>...</date> + +<comment>(Define the several <section> and <subsection>)</comment> + +</sections> +</pre> + +<p> +Inside each chapter you can define <c><section></c>s (equivalent of +<c><chapter></c> in a Guide) and <c><subsection></c>s (equivalent +of <c><section></c> in a Guide). +</p> + +<p> +Each individual chapter should have its own date and version elements. The +latest date of all chapters and master document will be displayed when a user +browses through all parts of the book. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Advanced Handbook Features</title> +<section> +<title>Global Values</title> +<body> + +<p> +Sometimes, the same values are repeated many times in several parts of a +handbook. Global search and replace operations tend to forget some or introduce +unwanted changes. Besides, it can be useful to define different values to be +used in shared chapters depending on which handbook includes the chapter. +</p> + +<p> +Global values can be defined in a handbook master file and used in all included +chapters. +</p> + +<p> +To define global values, add a <c><values></c> element to the handbook +master file. Each value is then defined in a <c><key></c> element whose +<c>id</c> attribute identifies the value, i.e. it is the name of your variable. +The content of the <c><key></c> is its value. +</p> + +<p> +The following example defines three values in a handbook master file: +</p> + +<pre caption="Define values in a handbook"> +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE book SYSTEM "/dtd/book.dtd"> +<!-- $Header$ --> + +<book> +<title>Example Book Usage</title> + +<i><values> + <key id="arch">x86</key> + <key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key> + <key id="min-cd-size">57</key> +</values></i> + +<author...> + ... +</author> + +... +</pre> + +<p> +The defined values can then be used throughout the handbook with the in-line +<c><keyval id="key_id"/></c> element. Specify the name of the key in its +<c>id</c> attribute, e.g. <keyval id="min-cd-name"/> would be replaced by +"install-x86-minimal-2007.0-r1.iso" in our example. +</p> + +<pre caption="Using defined values"> +<p> +The Minimal Installation CD is called <c><i><keyval id="min-cd-name"/></i></c> +and takes up only <i><keyval id="min-cd-size"/></i> MB of diskspace. You can use this +Installation CD to install Gentoo, but <e>only</e> with a working Internet +connection. +</p> +</pre> + +<p> +To make life easier on our translators, only use actual values, i.e. content +that does not need to be translated. For instance, we defined the +<c>min-cd-size</c> value to <c>57</c> and not <c>57 MB</c>. +</p> + +</body> +</section> +<section> +<title>Conditional Elements</title> +<body> + +<p> +Chapters that are shared by several handbooks such as our <uri +link="/doc/en/handbook/">Installation Handbooks</uri> often have small +differences depending on which handbook includes them. Instead of adding +content that is irrelevant to some handbooks, authors can add a condition to +the following elements: <c><section></c>, <c><subsection></c>, +<c><body></c>, <c><note></c>, <c><impo></c>, +<c><warn></c>, <c><pre></c>, <c><p></c>, +<c><table></c>, <c><tr></c>, <c><ul></c>, <c><ol></c> +and <c><li></c>. +</p> + +<p> +The condition must be an <uri +link="https://en.wikipedia.org/wiki/XPath";>XPATH</uri> expression that will be +evaluated when transforming the XML. If it evaluates to <c>true</c>, the +element is processed, if not, it is ignored. The condition is specified in a +<c>test</c> attribute. +</p> + +<p> +The following example uses the <c>arch</c> value that is defined in each +handbook master file to condition some content: +</p> + +<pre caption="Using conditional elements"> +<body test="contains('AMD64 x86',func:keyval('arch'))"> + +<p> +This paragraph applies to both x86 and AMD64 architectures. +</p> + +<p test="func:keyval('arch')='x86'"> +This paragraph only applies to the x86 architecture. +</p> + +<p test="func:keyval('arch')='AMD64'"> +This paragraph only applies to the AMD64 architecture. +</p> + +<p test="func:keyval('arch')='PPC'"> +This paragraph will never be seen! +The whole body is skipped because of the first condition. +</p> + +</body> + +<body test="contains('AMD64 PPC64',func:keyval('arch'))"> + +<p> +This paragraph applies to the AMD64, PPC64 <comment>and PPC</comment> architectures because +the 'AMD64 PPC64' string does contain 'PPC'. +</p> + +<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'"> +This note only applies to the AMD64 and PPC64 architectures. +</note> + +</body> +</pre> + +</body> +</section> +</chapter> + +<chapter id="codingstyle"> +<title>Coding Style</title> +<section> +<title>Introduction</title> +<body> + +<p> +Since all Gentoo Documentation is a joint effort and several people will +most likely change existing documentation, a coding style is needed. +A coding style contains two sections. The first one is regarding +internal coding - how the XML-tags are placed. The second one is +regarding the content - how not to confuse the reader. +</p> + +<p> +Both sections are described next. +</p> + +</body> +</section> +<section> +<title>Internal Coding Style</title> +<body> + +<p> +<b>Newlines</b> must be placed immediately after <e>every</e> +GuideXML-tag (both opening as closing), except for: +<c><version></c>, <c><date></c>, <c><title></c>, +<c><th></c>, <c><ti></c>, +<c><li></c>, <c><i></c>, <c><e></c>, +<c><uri></c>, <c><path></c>, <c><b></c>, <c><c></c>, +<c><comment></c>, <c><mail></c>. +</p> + +<p> +<b>Blank lines</b> must be placed immediately after <e>every</e> +<c><body></c> (opening tag only) and before <e>every</e> +<c><chapter></c>, <c><p></c>, <c><table></c>, +<c><author></c> (set), <c><pre></c>, <c><ul></c>, +<c><ol></c>, <c><warn></c>, <c><note></c> and +<c><impo></c> (opening tags only). +</p> + +<p> +<b>Word-wrapping</b> must be applied at 80 characters except inside +<c><pre></c>. You may only deviate from this rule when there is no other +choice (for instance when a URL exceeds the maximum amount of characters). The +editor must then wrap whenever the first whitespace occurs. You should try to +keep the <e>rendered</e> content of <c><pre></c> elements within 80 +columns to help console users. +</p> + +<p> +<b>Indentation</b> may not be used, except with the XML-constructs of which the +parent XML-tags are <c><tr></c> (from <c><table></c>), +<c><ul></c>, <c><ol></c>, <c><dl></c>, and +<c><author></c>. If indentation is used, it <e>must</e> be two spaces for +each indentation. That means <e>no tabs</e> and <e>not</e> more spaces. +Besides, tabs are not allowed in GuideXML documents. +</p> + +<p> +In case word-wrapping happens in <c><ti></c>, <c><th></c>, +<c><li></c> or <c><dd></c> constructs, indentation must be used for +the content. +</p> + +<p> +An example for indentation is: +</p> + +<pre caption="Indentation Example"> +<table> +<tr> + <th>Foo</th> + <th>Bar</th> +</tr> +<tr> + <ti>This is an example for indentation</ti> + <ti> + In case text cannot be shown within an 80-character wide line, you + must use indentation if the parent tag allows it + </ti> +</tr> +</table> + +<ul> + <li>First option</li> + <li>Second option</li> +</ul> +</pre> + +<p> +<b>Attributes</b> may not have spaces in between the attribute, the "=" mark, +and the attribute value. As an example: +</p> + +<pre caption="Attributes"> +<comment>Wrong :</comment> <pre caption = "Attributes"> +<comment>Correct:</comment> <pre caption="Attributes"> +</pre> + +</body> +</section> +<section> +<title>External Coding Style</title> +<body> + +<p> +Inside tables (<c><table></c>) and listings (<c><ul></c>, +<c><ol></c>) and <c><dl></c>, periods (".") should not be used +unless multiple sentences are used. In that case, every sentence should end +with a period (or other reading marks). +</p> + +<p> +Every sentence, including those inside tables and listings, should start +with a capital letter. +</p> + +<pre caption="Periods and capital letters"> +<ul> + <li>No period</li> + <li>With period. Multiple sentences, remember?</li> +</ul> +</pre> + +<p> +Code Listings should <e>always</e> have a <c>caption</c>. +</p> + +<p> +Try to use <c><uri></c> with the <c>link</c> attribute as much as +possible. In other words, the <uri link="https://forums.gentoo.org";>Gentoo +Forums</uri> is preferred over <uri>https://forums.gentoo.org</uri>. +</p> + +<p> +When you comment something inside a <c><pre></c> construct, use +<c><comment></c> and parentheses or the comment marker for the language +that is being used (<c>#</c> for bash scripts and many other things, <c>//</c> +for C code, etc.) Also place the comment <e>before</e> the subject of the +comment. +</p> + +<pre caption="Comment example"> +<comment>(Substitute "john" with your user name)</comment> +# <i>id john</i> +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>Resources</title> +<section> +<title>Start writing</title> +<body> + +<p> +GuideXML has been specially designed to be "lean and mean" so that developers +can spend more time writing documentation and less time learning the actual XML +syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" +to start writing quality Gentoo documentation. You might be interested in our +<uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation Development Tips +& Tricks</uri>. If you'd like to help (or have any questions about +GuideXML), please post a message to the <uri +link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd like +to tackle. Have fun! +</p> + +</body> +</section> +</chapter> +</guide> diff --git a/appendices/contributing/text.xml b/appendices/contributing/text.xml index 9ad2011..7cf72a6 100644 --- a/appendices/contributing/text.xml +++ b/appendices/contributing/text.xml @@ -65,7 +65,7 @@ conversion used in some of the figures throughout the document. <body> <p> -DevBook XML is heavily based on <uri link="https://www.gentoo.org/doc/en/xml-guide.xml";> +DevBook XML is heavily based on <uri link="devbook/"> GuideXML</uri> and many tags are similar, if not the same. The main differences occur in layout which are designed to make a large-scale publication easier to produce and manage using a hierarchical tree system. Before starting off you @@ -140,9 +140,15 @@ really should first examine the GuideXML guide in a reasonable amount of depth. </li> </ul> +</body> +</section> +<section> +<title>Contents</title> +<body> +<contentsTree/> </body> </section> </chapter> - +<include href="devbook/" /> </guide>
