1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
<?xml version="1.0" encoding="UTF-8"?>
<guide self="appendices/contributing/">
<chapter>
<title>Contributing to This Document</title>
<body>
<p>
Contributions for this document are very welcome. Whether you've found a typo
or have written an entire new section, the best way to get in touch is via
Bugzilla. Please look at the
<uri link="https://bugs.gentoo.org/buglist.cgi?product=Documentation;component=Devmanual;resolution=---">
bug list</uri> and file a
<uri link="https://bugs.gentoo.org/enter_bug.cgi?product=Documentation;component=Devmanual;format=guided">
new bug</uri>.
</p>
<p>
The editors reserve the right to modify submissions as they see fit. Any
substantial changes will of course be discussed with the submitter first <d/>
unless explicitly requested, minor typo corrections and formatting fixes will
not be discussed.
</p>
<p>
This document is licensed under the
<uri link="https://creativecommons.org/licenses/by-sa/4.0/">
Creative Commons Attribution-ShareAlike 4.0 International License</uri>.
If this is a problem, don't submit anything.
</p>
<p>
This document is produced using the DevBook XML build system. You can download
a snapshot of the system as well as the relevant XML files from Git,
see the <uri link="::appendices/contributing/#Where to find the sources">
following section</uri>. If you'd rather just work with plain text, that's
fine too <d/> the formatting can be easily done by someone else (meaning, us).
</p>
</body>
<section>
<title>Where to find the sources</title>
<body>
<p>
Currently, sources are hosted on
<uri link="https://gitweb.gentoo.org/proj/devmanual.git">git.gentoo.org</uri>.
For current Gentoo developers, access is at
<c>git+ssh://git@git.gentoo.org/proj/devmanual.git</c>.
Non-developers can clone the repository by typing
<c>git clone git://anongit.gentoo.org/proj/devmanual.git</c>.
The sources are also hosted on
<uri link="https://github.com/gentoo/devmanual">GitHub</uri>
for those who prefer to submit patches using pull requests.
</p>
<p>
To build the devmanual, simply run <c>make</c> in the top directory of
the repository. You need <c>xsltproc</c> (from <c>dev-libs/libxslt</c>)
for the XML to HTML conversion, <c>xmllint</c> (from <c>dev-libs/libxml2</c>)
for validation, and <c>rsvg-convert</c> (from <c>gnome-base/librsvg</c>) for
the SVG to PNG conversion used in some of the figures throughout the document.
</p>
<p>
To check if the document's XML is valid, run <c>make validate</c> in the
top-level directory, which will validate all XML files using <c>xmllint</c>.
</p>
</body>
</section>
<section>
<title>Quick Introduction to DevBook XML</title>
<body>
<p>
DevBook XML is heavily based on GuideXML 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 really should first examine the
<uri link="::appendices/devbook-guide/">DevBook XML guide</uri> in a reasonable
amount of depth.
</p>
</body>
<subsection>
<title>Differences from GuideXML</title>
<body>
<dl>
<dt>
Indentation
</dt>
<dd>
Indent when needed <d/> you should not indent any section flow elements
such as <c><subsection></c> but do indent tables, lists and
definition lists. Do <e>not</e> indent text in ordinary paragraph blocks.
</dd>
<dt>
Code Samples
</dt>
<dd>
You can use the normal GuideXML tag <c><pre></c> when you need
no syntax highlighting. When you need syntax highlighting use the
<c><codesample></c> tag along with a <c>lang</c> attribute <d/>
usually you want this to be set to <c>ebuild</c> to syntax highlight ebuild
code snippets.
</dd>
<dt>
Hierarchy
</dt>
<dd>
The whole document is organized as a tree. Each directory can contain
one document. Each document can inherit multiple sub-documents using the
<c><include></c> flag. You <b>must</b> ensure that the <c>self</c>
tag in each document correctly points to the relative path of the document
from the root node so that the tree-walking algorithms work correctly.
</dd>
</dl>
</body>
</subsection>
</section>
<section>
<title>Style Guidelines</title>
<body>
<ul>
<li>
This document is in British English. Submissions in other kinds of English are
welcome, but they may have their spelling corrected.
</li>
<li>
Third person form should be used rather than first.
</li>
<li>
This is not a formal document. The writing style is intended to be
professional but readable.
</li>
</ul>
</body>
</section>
</chapter>
</guide>
|
GitWeb