1 |
commit: e86ac3f696f078dc7aedc5b56111098c16934c10 |
2 |
Author: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org> |
3 |
AuthorDate: Wed Apr 12 18:00:31 2017 +0000 |
4 |
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org> |
5 |
CommitDate: Wed Apr 12 18:00:31 2017 +0000 |
6 |
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=e86ac3f6 |
7 |
|
8 |
appendices/contributing/devbook-guide: remove unnecessary sections 3 and 4 |
9 |
|
10 |
Remove the unnecessary sections "Handbook Format" and |
11 |
"Advanced Handbook Features". |
12 |
|
13 |
appendices/contributing/devbook-guide/text.xml | 279 ------------------------- |
14 |
1 file changed, 279 deletions(-) |
15 |
|
16 |
diff --git a/appendices/contributing/devbook-guide/text.xml b/appendices/contributing/devbook-guide/text.xml |
17 |
index a4a69af..4f4e8ac 100644 |
18 |
--- a/appendices/contributing/devbook-guide/text.xml |
19 |
+++ b/appendices/contributing/devbook-guide/text.xml |
20 |
@@ -767,285 +767,6 @@ obvious. |
21 |
</section> |
22 |
</chapter> |
23 |
|
24 |
-<chapter> |
25 |
-<title>Handbook Format</title> |
26 |
-<section> |
27 |
-<title>Guide vs Book</title> |
28 |
-<body> |
29 |
- |
30 |
-<p> |
31 |
-For high-volume documentation, such as the <uri |
32 |
-link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a |
33 |
-broader format was needed. We designed a GuideXML-compatible enhancement that |
34 |
-allows us to write modular and multi-page documentation. |
35 |
-</p> |
36 |
- |
37 |
-</body> |
38 |
-</section> |
39 |
-<section> |
40 |
-<title>Main File</title> |
41 |
-<body> |
42 |
- |
43 |
-<p> |
44 |
-The first change is the need for a "master" document. This document contains no |
45 |
-real content, but links to the individual documentation modules. The syntax |
46 |
-doesn't differ much from GuideXML: |
47 |
-</p> |
48 |
- |
49 |
-<pre caption="Example book usage"> |
50 |
-<?xml version='1.0' encoding='UTF-8'?> |
51 |
-<!DOCTYPE book SYSTEM "/dtd/book.dtd"> |
52 |
-<!-- $Header$ --> |
53 |
- |
54 |
-<<i>book</i>> |
55 |
-<title>Example Book Usage</title> |
56 |
- |
57 |
-<author...> |
58 |
- ... |
59 |
-</author> |
60 |
- |
61 |
-<abstract> |
62 |
- ... |
63 |
-</abstract> |
64 |
- |
65 |
-<!-- The content of this document is licensed under the CC-BY-SA license --> |
66 |
-<!-- See http://creativecommons.org/licenses/by-sa/3.0 --> |
67 |
-<license version="3.0"/> |
68 |
- |
69 |
-<version>...</version> |
70 |
-<date>...</date> |
71 |
-</pre> |
72 |
- |
73 |
-<p> |
74 |
-So far no real differences (except for the <c><book></c> instead of |
75 |
-<c><guide></c> tag). Instead of starting with the individual |
76 |
-<c><chapter></c>s, you define a <c><part></c>, which is the |
77 |
-equivalent of a separate part in a book: |
78 |
-</p> |
79 |
- |
80 |
-<pre caption="Defining a part"> |
81 |
-<part> |
82 |
-<title>Part One</title> |
83 |
-<abstract> |
84 |
- ... |
85 |
-</abstract> |
86 |
- |
87 |
-<comment>(Defining the several chapters)</comment> |
88 |
-</part> |
89 |
-</pre> |
90 |
- |
91 |
-<p> |
92 |
-Each part is accompanied by a <c><title></c> and an |
93 |
-<c><abstract></c> which gives a small introduction to the part. |
94 |
-</p> |
95 |
- |
96 |
-<p> |
97 |
-Inside each part, you define the individual <c><chapter></c>s. Each |
98 |
-chapter <e>must</e> be a separate document. As a result it is no surprise that |
99 |
-a special tag (<c><include></c>) is added to allow including the separate |
100 |
-document. |
101 |
-</p> |
102 |
- |
103 |
-<pre caption="Defining a chapter"> |
104 |
-<chapter> |
105 |
-<title>Chapter One</title> |
106 |
- |
107 |
- <include href="path/to/chapter-one.xml"/> |
108 |
- |
109 |
-</chapter> |
110 |
-</pre> |
111 |
- |
112 |
-</body> |
113 |
-</section> |
114 |
-<section> |
115 |
-<title>Designing the Individual Chapters</title> |
116 |
-<body> |
117 |
- |
118 |
-<p> |
119 |
-The content of an individual chapter is structured as follows: |
120 |
-</p> |
121 |
- |
122 |
-<pre caption="Chapter Syntax"> |
123 |
-<?xml version='1.0' encoding='UTF-8'?> |
124 |
-<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> |
125 |
-<!-- $Header$ --> |
126 |
- |
127 |
-<!-- The content of this document is licensed under the CC-BY-SA license --> |
128 |
-<!-- See http://creativecommons.org/licenses/by-sa/3.0 --> |
129 |
- |
130 |
-<sections> |
131 |
- |
132 |
-<abstract> |
133 |
- This is a small explanation on chapter one. |
134 |
-</abstract> |
135 |
- |
136 |
-<version>...</version> |
137 |
-<date>...</date> |
138 |
- |
139 |
-<comment>(Define the several <section> and <subsection>)</comment> |
140 |
- |
141 |
-</sections> |
142 |
-</pre> |
143 |
- |
144 |
-<p> |
145 |
-Inside each chapter you can define <c><section></c>s (equivalent of |
146 |
-<c><chapter></c> in a Guide) and <c><subsection></c>s (equivalent |
147 |
-of <c><section></c> in a Guide). |
148 |
-</p> |
149 |
- |
150 |
-<p> |
151 |
-Each individual chapter should have its own date and version elements. The |
152 |
-latest date of all chapters and master document will be displayed when a user |
153 |
-browses through all parts of the book. |
154 |
-</p> |
155 |
- |
156 |
-</body> |
157 |
-</section> |
158 |
-</chapter> |
159 |
- |
160 |
-<chapter> |
161 |
-<title>Advanced Handbook Features</title> |
162 |
-<section> |
163 |
-<title>Global Values</title> |
164 |
-<body> |
165 |
- |
166 |
-<p> |
167 |
-Sometimes, the same values are repeated many times in several parts of a |
168 |
-handbook. Global search and replace operations tend to forget some or introduce |
169 |
-unwanted changes. Besides, it can be useful to define different values to be |
170 |
-used in shared chapters depending on which handbook includes the chapter. |
171 |
-</p> |
172 |
- |
173 |
-<p> |
174 |
-Global values can be defined in a handbook master file and used in all included |
175 |
-chapters. |
176 |
-</p> |
177 |
- |
178 |
-<p> |
179 |
-To define global values, add a <c><values></c> element to the handbook |
180 |
-master file. Each value is then defined in a <c><key></c> element whose |
181 |
-<c>id</c> attribute identifies the value, i.e. it is the name of your variable. |
182 |
-The content of the <c><key></c> is its value. |
183 |
-</p> |
184 |
- |
185 |
-<p> |
186 |
-The following example defines three values in a handbook master file: |
187 |
-</p> |
188 |
- |
189 |
-<pre caption="Define values in a handbook"> |
190 |
-<?xml version='1.0' encoding='UTF-8'?> |
191 |
-<!DOCTYPE book SYSTEM "/dtd/book.dtd"> |
192 |
-<!-- $Header$ --> |
193 |
- |
194 |
-<book> |
195 |
-<title>Example Book Usage</title> |
196 |
- |
197 |
-<i><values> |
198 |
- <key id="arch">x86</key> |
199 |
- <key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key> |
200 |
- <key id="min-cd-size">57</key> |
201 |
-</values></i> |
202 |
- |
203 |
-<author...> |
204 |
- ... |
205 |
-</author> |
206 |
- |
207 |
-... |
208 |
-</pre> |
209 |
- |
210 |
-<p> |
211 |
-The defined values can then be used throughout the handbook with the in-line |
212 |
-<c><keyval id="key_id"/></c> element. Specify the name of the key in its |
213 |
-<c>id</c> attribute, e.g. <keyval id="min-cd-name"/> would be replaced by |
214 |
-"install-x86-minimal-2007.0-r1.iso" in our example. |
215 |
-</p> |
216 |
- |
217 |
-<pre caption="Using defined values"> |
218 |
-<p> |
219 |
-The Minimal Installation CD is called <c><i><keyval id="min-cd-name"/></i></c> |
220 |
-and takes up only <i><keyval id="min-cd-size"/></i> MB of diskspace. You can use this |
221 |
-Installation CD to install Gentoo, but <e>only</e> with a working Internet |
222 |
-connection. |
223 |
-</p> |
224 |
-</pre> |
225 |
- |
226 |
-<p> |
227 |
-To make life easier on our translators, only use actual values, i.e. content |
228 |
-that does not need to be translated. For instance, we defined the |
229 |
-<c>min-cd-size</c> value to <c>57</c> and not <c>57 MB</c>. |
230 |
-</p> |
231 |
- |
232 |
-</body> |
233 |
-</section> |
234 |
-<section> |
235 |
-<title>Conditional Elements</title> |
236 |
-<body> |
237 |
- |
238 |
-<p> |
239 |
-Chapters that are shared by several handbooks such as our <uri |
240 |
-link="/doc/en/handbook/">Installation Handbooks</uri> often have small |
241 |
-differences depending on which handbook includes them. Instead of adding |
242 |
-content that is irrelevant to some handbooks, authors can add a condition to |
243 |
-the following elements: <c><section></c>, <c><subsection></c>, |
244 |
-<c><body></c>, <c><note></c>, <c><impo></c>, |
245 |
-<c><warn></c>, <c><pre></c>, <c><p></c>, |
246 |
-<c><table></c>, <c><tr></c>, <c><ul></c>, <c><ol></c> |
247 |
-and <c><li></c>. |
248 |
-</p> |
249 |
- |
250 |
-<p> |
251 |
-The condition must be an <uri |
252 |
-link="http://en.wikipedia.org/wiki/XPath">XPATH</uri> expression that will be |
253 |
-evaluated when transforming the XML. If it evaluates to <c>true</c>, the |
254 |
-element is processed, if not, it is ignored. The condition is specified in a |
255 |
-<c>test</c> attribute. |
256 |
-</p> |
257 |
- |
258 |
-<p> |
259 |
-The following example uses the <c>arch</c> value that is defined in each |
260 |
-handbook master file to condition some content: |
261 |
-</p> |
262 |
- |
263 |
-<pre caption="Using conditional elements"> |
264 |
-<body test="contains('AMD64 x86',func:keyval('arch'))"> |
265 |
- |
266 |
-<p> |
267 |
-This paragraph applies to both x86 and AMD64 architectures. |
268 |
-</p> |
269 |
- |
270 |
-<p test="func:keyval('arch')='x86'"> |
271 |
-This paragraph only applies to the x86 architecture. |
272 |
-</p> |
273 |
- |
274 |
-<p test="func:keyval('arch')='AMD64'"> |
275 |
-This paragraph only applies to the AMD64 architecture. |
276 |
-</p> |
277 |
- |
278 |
-<p test="func:keyval('arch')='PPC'"> |
279 |
-This paragraph will never be seen! |
280 |
-The whole body is skipped because of the first condition. |
281 |
-</p> |
282 |
- |
283 |
-</body> |
284 |
- |
285 |
-<body test="contains('AMD64 PPC64',func:keyval('arch'))"> |
286 |
- |
287 |
-<p> |
288 |
-This paragraph applies to the AMD64, PPC64 <comment>and PPC</comment> architectures because |
289 |
-the 'AMD64 PPC64' string does contain 'PPC'. |
290 |
-</p> |
291 |
- |
292 |
-<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'"> |
293 |
-This note only applies to the AMD64 and PPC64 architectures. |
294 |
-</note> |
295 |
- |
296 |
-</body> |
297 |
-</pre> |
298 |
- |
299 |
-</body> |
300 |
-</section> |
301 |
-</chapter> |
302 |
- |
303 |
<chapter id="codingstyle"> |
304 |
<title>Coding Style</title> |
305 |
<section> |