diff options
| -rw-r--r-- | appendices/contributing/text.xml | 120 | ||||
| -rw-r--r-- | appendices/text.xml | 22 | ||||
| -rw-r--r-- | tasks-reference/completion/text.xml | 25 | ||||
| -rw-r--r-- | text.xml | 1 |
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><subsection></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><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 -- 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><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. + </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><d/></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> @@ -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> |