blob: d6e307bc18f8605b4e17d617c3ddf8bbdc9ea31b (plain
<title>Contributing to This Document</title>
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.
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.
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.
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.
<title>Quick Introduction to DevBook XML</title>
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.
<title>Differences to GuideXML</title>
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.
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.
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.
This document is in British English. Submissions in other kinds of English are
welcome, but they may have their spelling corrected.
Third person form should be used rather than first.
This is not a formal document. The writing style is intended to be
professional but readable.
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.