aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTim Yamin <plasmaroo@gentoo.org>2006-04-06 23:10:12 +0000
committerTim Yamin <plasmaroo@gentoo.org>2006-04-06 23:10:12 +0000
commitd364e13e7e0967cb654c8ff0b9fdc8b3bf7dfa71 (patch)
tree78f1cc9e8303e05daba78cb6f7ceebfb765d662f
parentFix '((' highlighting. (diff)
downloaddevmanual-d364e13e7e0967cb654c8ff0b9fdc8b3bf7dfa71.tar.gz
devmanual-d364e13e7e0967cb654c8ff0b9fdc8b3bf7dfa71.tar.bz2
devmanual-d364e13e7e0967cb654c8ff0b9fdc8b3bf7dfa71.zip
Add very brief draft of "Contributing to This Document". The DevBook XML will obviously need to be expained in more detail...
git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@31 176d3534-300d-0410-8db8-84e73ed771c3
-rw-r--r--appendices/contributing/text.xml120
-rw-r--r--appendices/text.xml22
-rw-r--r--tasks-reference/completion/text.xml25
-rw-r--r--text.xml1
4 files changed, 157 insertions, 11 deletions
diff --git a/appendices/contributing/text.xml b/appendices/contributing/text.xml
new file mode 100644
index 0000000..d6e307b
--- /dev/null
+++ b/appendices/contributing/text.xml
@@ -0,0 +1,120 @@
+<?xml version="1.0"?>
+<guide self="appendices/contributing/">
+<chapter>
+<title>Contributing to This Document</title>
+
+<body>
+<p>
+Contributions for this document are highly welcomed. Whether you've found a typo
+or have written an entire new section, the best way to get in touch is to `send
+an email to plasmaroo.
+</p>
+
+<p>
+The editor reserves the right to modify submissions as he sees fit. Any
+substantial changes will of course be discussed with the submitter first --
+unless explicitly requested, minor typo corrections and formatting fixes will
+not be discussed.
+</p>
+
+<p>
+This document is licensed under the <uri link="http://creativecommons.org/licenses/by-sa/2.0/">
+Creative Commons Attribution-ShareAlike 2.0 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 here: :FIXME:. You
+can also view the XML of any page by adding <c>./text.xml</c> to the URL. If
+you'd rather just work with plain text, that's fine too -- the formatting can
+be easily done by someone else.
+</p>
+</body>
+
+<section>
+<title>Quick Introduction to DevBook XML</title>
+<body>
+
+<p>
+DevBook XML is heavily based on <uri link="http://www.gentoo.org/doc/en/xml-guide.xml">
+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 hierachical tree system. Before starting off you
+really should first examine the GuideXML guide in a reasonable amount of depth.
+</p>
+
+<subsection>
+<title>Differences to GuideXML</title>
+<body>
+
+<dl>
+ <dt>
+ Indentation
+ </dt>
+ <dd>
+ <p>
+ Indent when needed -- you should not indent any section flow elements such as
+ <c>&lt;subsection&gt;</c> but do indent tables, lists and definition lists.
+ Do <e>not</e> indent text in ordinary paragraph blocks.
+ </p>
+ </dd>
+ <dt>
+ Code Samples
+ </dt>
+ <dd>
+ <p>
+ You can use the normal GuideXML tag <c>&lt;pre&gt;</c> when you need no syntax
+ highlighting. When you need syntax highlighting use the <c>&lt;codesample&gt;</c>
+ tag along with a <c>lang</c> attribute -- usually you want this to be set to
+ <c>ebuild</c> to syntax highlight ebuild code snippets.
+ </p>
+ </dd>
+ <dt>
+ Hierachy
+ </dt>
+ <dd>
+ <p>
+ The whole document is organized as a tree. Each directory can contain one
+ document. Each document can inherit multiple sub-documents using the
+ <c>&lt;include&gt;</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.
+ </p>
+ </dd>
+</dl>
+
+</body>
+</subsection>
+</body>
+</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>
+ <li>
+ When using in-sentence hyphens as punctuation <d/> like this <d/> use a space,
+ followed by the <c>&lt;d/&gt;</c> tag. The build system will automatically turn
+ this into a proper Unicode long dash.
+ </li>
+</ul>
+
+</body>
+</section>
+</chapter>
+
+</guide>
+
diff --git a/appendices/text.xml b/appendices/text.xml
new file mode 100644
index 0000000..653f73a
--- /dev/null
+++ b/appendices/text.xml
@@ -0,0 +1,22 @@
+<?xml version="1.0"?>
+<guide self="appendices/">
+<chapter>
+<title>Appendices</title>
+
+<body>
+<p>
+This section incorporates various auxiliary documents which may be useful as a reference.
+</p>
+</body>
+
+<section>
+<title>Contents</title>
+<body>
+<contentsTree/>
+</body>
+</section>
+</chapter>
+
+<include href="contributing/"/>
+
+</guide>
diff --git a/tasks-reference/completion/text.xml b/tasks-reference/completion/text.xml
index 7290060..dec64ac 100644
--- a/tasks-reference/completion/text.xml
+++ b/tasks-reference/completion/text.xml
@@ -360,9 +360,11 @@ Lines 1-12 are pretty much the same as in the previous section.
15
</ti>
<ti>
- If <c>${prev}</c> is equal to -X|--package-names, call _pkgname (a function
- defined by <c>gentoo-bashcomp</c> that completes on package names - it sets
- <c>${COMPREPLY}</c>, so we don't worry about that here).
+ If <c>${prev}</c> is equal to <c>-X</c>
+ or <c>--package-names</c>, call <c>_pkgname</c> (a function
+ defined by <c>gentoo-bashcomp</c> that completes on package
+ names - it sets <c>${COMPREPLY}</c>, so we don't worry about
+ that here).
</ti>
</tr>
<tr>
@@ -370,9 +372,10 @@ Lines 1-12 are pretty much the same as in the previous section.
18
</ti>
<ti>
- If <c>${prev}</c> is equal to --soname, generate a list of all shared libs
- in /lib and /usr/lib*. Pass that list to <c>compgen</c> to generate a list
- of possible completions that match <c>${cur}</c>.
+ If <c>${prev}</c> is equal to <c>--soname</c>, generate a list
+ of all shared libs in <c>/lib</c> and <c>/usr/lib*</c>. Pass
+ that list to <c>compgen</c> to generate a list of possible
+ completions that match <c>${cur}</c>.
</ti>
</tr>
<tr>
@@ -381,7 +384,7 @@ Lines 1-12 are pretty much the same as in the previous section.
</ti>
<ti>
Obviously we cannot complete on any regexp's so if <c>${prev}</c> is equal
- to --soname-regexp, do nothing.
+ to <c>--soname-regexp</c>, do nothing.
</ti>
</tr>
<tr>
@@ -391,7 +394,7 @@ Lines 1-12 are pretty much the same as in the previous section.
<ti>
For anything else (any options not specified in the case statement above
OR any argument to one of the options specified in the case statement)
- perform the tests. Since --package-names can take multiple package
+ perform the tests. Since <c>--package-names</c> can take multiple package
names, we want to continue to complete on package names until another
recognized option is encountered (ie. is <c>${prev}</c>).
</ti>
@@ -401,8 +404,8 @@ Lines 1-12 are pretty much the same as in the previous section.
30
</ti>
<ti>
- Since _pkgname sets <c>${COMPREPLY}</c> and we want to add to that list,
- we have to use the COMPREPLY=(${COMPREPLY[@] ... ) construct.
+ Since <c>_pkgname</c> sets <c>${COMPREPLY}</c> and we want to add to that list,
+ we have to use the <c>COMPREPLY=(${COMPREPLY[@] ... )</c> construct.
</ti>
</tr>
<tr>
@@ -410,7 +413,7 @@ Lines 1-12 are pretty much the same as in the previous section.
37
</ti>
<ti>
- Tell bash to use _revdep_rebuild to generate all possible completions
+ Tell bash to use <c>_revdep_rebuild</c> to generate all possible completions
for revdep-rebuild.
</ti>
</tr>
diff --git a/text.xml b/text.xml
index 528fc08..e22aa67 100644
--- a/text.xml
+++ b/text.xml
@@ -43,4 +43,5 @@ section for how to get started.
<include href="function-reference/"/>
<include href="eclass-reference/"/>
<include href="tools-reference/"/>
+<include href="appendices/"/>
</guide>