* [gentoo-commits] proj/devmanual:devbook-guide commit in: appendices/contributing/devbook-guide/, appendices/contributing/
@ 2017-04-12 21:24 Göktürk Yüksek
0 siblings, 0 replies; only message in thread
From: Göktürk Yüksek @ 2017-04-12 21:24 UTC (permalink / raw
To: gentoo-commits
commit: 8be0d382fb82dc4cfe73b1b85bb7fc3c923a21c7
Author: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Wed Apr 12 15:37:57 2017 +0000
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Apr 12 17:19:38 2017 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=8be0d382
appendices/contributing/devbook-guide: initial commit
Imported from:
https://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo/xml/htdocs/doc/en/xml-guide.xml?revision=1.72
The only modifications that have been made are the removals of DOCTYPE
and the CVS header, and the addition of self attribute to <guide>
appendices/contributing/devbook-guide/text.xml | 1224 ++++++++++++++++++++++++
appendices/contributing/text.xml | 3 +-
2 files changed, 1226 insertions(+), 1 deletion(-)
diff --git a/appendices/contributing/devbook-guide/text.xml b/appendices/contributing/devbook-guide/text.xml
new file mode 100644
index 0000000..a4a69af
--- /dev/null
+++ b/appendices/contributing/devbook-guide/text.xml
@@ -0,0 +1,1224 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<guide self="appendices/contributing/devbook-guide/">
+<title>Gentoo GuideXML Guide</title>
+
+<author title="Author">
+ <mail link="neysx"/>
+</author>
+<author title="Author">
+ <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
+</author>
+<author title="Author"><!-- zhen@gentoo.org -->
+ John P. Davis
+</author>
+<author title="Editor">
+ <mail link="peesh@gentoo.org">Jorge Paulo</mail>
+</author>
+<author title="Editor">
+ <mail link="swift@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 http://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>
+If you are planning on contributing documentation to Gentoo, or you want to
+test GuideXML, please read our <uri
+link="/proj/en/gdp/doc/doc-tipsntricks.xml">Doc Tips 'n' Tricks</uri> guide
+which contains tips and tricks for documentation development.
+</p>
+
+<p>
+You may want to look at the <uri link="?passthru=1">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>yourname@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 http://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="http://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>http://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>http://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>"http://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.bar@example.com">Mr. Foo Bar</mail></c>. If you want to display the
+email address, you can use <c><mail>foo.bar@example.com</mail></c>, this
+would be displayed as <mail>foo.bar@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>http://forums.gentoo.org/</uri>. To create this link, I typed
+<c><uri>http://forums.gentoo.org/</uri></c>. The alternate form is
+when you want to associate a URI with some other text -- for example, <uri
+link="http://forums.gentoo.org/">the Gentoo Forums</uri>. To create
+<e>this</e> link, I typed <c><uri link="http://forums.gentoo.org/">the
+Gentoo Forums</uri></c>. You don't need to write
+<c>http://www.gentoo.org/</c> to link to other parts of the Gentoo web site.
+For instance, a link to the <uri link="/doc/en/">documentation main index</uri>
+should be simply <c><uri link="/doc/en/index.xml">documentation main
+index</uri></c>. You can even omit <c>index.xml</c> when you link to a
+directory index, e.g. <c><uri link="/doc/en/">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="http://en.wikipedia.org/wiki/Click_here">click here
+syndrome</uri> as recommended by the <uri
+link="http://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="http://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="/doc/en/handbook/handbook-x86.xml">
+<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, such as the <uri
+link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, 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 http://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 http://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="http://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="http://forums.gentoo.org">Gentoo
+Forums</uri> is preferred over <uri>http://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 5550aef..04fc9a8 100644
--- a/appendices/contributing/text.xml
+++ b/appendices/contributing/text.xml
@@ -143,5 +143,6 @@ really should first examine the GuideXML guide in a reasonable amount of depth.
</section>
</chapter>
-</guide>
+<include href="devbook-guide/"/>
+</guide>
^ permalink raw reply related [flat|nested] only message in thread
only message in thread, other threads:[~2017-04-12 21:24 UTC | newest]
Thread overview: (only message) (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-04-12 21:24 [gentoo-commits] proj/devmanual:devbook-guide commit in: appendices/contributing/devbook-guide/, appendices/contributing/ Göktürk Yüksek
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox