diff options
| author |   Göktürk Yüksek <gokturk@gentoo.org> | 2017-04-12 14:00:31 -0400 |
|---|---|---|
| committer | Göktürk Yüksek <gokturk@gentoo.org> | 2017-04-12 14:00:31 -0400 |
| commit | e86ac3f696f078dc7aedc5b56111098c16934c10 (patch) | |
| tree | a0c77223ca11e51c7587dd401c3a280f53221b2d | |
| parent | appendices/contributing/devbook-guide: initial commit (diff) | |
| download | devmanual-e86ac3f696f078dc7aedc5b56111098c16934c10.tar.gz devmanual-e86ac3f696f078dc7aedc5b56111098c16934c10.tar.bz2 devmanual-e86ac3f696f078dc7aedc5b56111098c16934c10.zip | |
appendices/contributing/devbook-guide: remove unnecessary sections 3 and 4
Remove the unnecessary sections "Handbook Format" and
"Advanced Handbook Features".
| -rw-r--r-- | appendices/contributing/devbook-guide/text.xml | 279 |
1 files changed, 0 insertions, 279 deletions
diff --git a/appendices/contributing/devbook-guide/text.xml b/appendices/contributing/devbook-guide/text.xml index a4a69af..4f4e8ac 100644 --- a/appendices/contributing/devbook-guide/text.xml +++ b/appendices/contributing/devbook-guide/text.xml @@ -767,285 +767,6 @@ obvious. </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> |