So, you keep hearing me talk about contributing to Kubuntu documentation, and you see that I say it would be nice for you to have some DocBook/XML experience. Many people want to help, but they don’t have that experience. In most cases, the people interested at least understand HTML or some other markup language a little bit. If you can understand that, then you can easily understand DocBook/XML the way we use it for Kubuntu documentation. DocBook/XML has a lot of tags that one can use, however we only use a very small subset of those tags with our documentation. Just an idea of the main tags we use from DocBook/XML are:
- <sect1>
- <sect2> – sometimes
- <title>
- <para>
- <ulink>
- <example> – sometimes
- <mediaobject> – only for screenshots
- <imageobject> – only for screenshots
- <imagedata> – only for screenshots
- <acronym> – sometimes
- <guibutton> – sometimes
There might be a few more, but these are the ones that pop into my head. For instance, when you are trying to let the reader know to open up an application via the menu, there is a tag called <menuchoice>. We have an entities file that contains all of the menu stuff, so you wouldn’t even need to use that tag, as you would call it in the document you are working in. Example: Say you are trying to tell the user how to open Amarok, you would enter &menuamarok;. Easy!
Here is an HTML example, lets say, Hello World 🙂
<html> <head> <title>Hello, World!</title> </head> <body> <p>Hello, World!</p> </body> </html>
The html, head, and title, are already taken care for you with the template, so you just need to do the part in between the <p> and </p>. So in DocBook/XML, that would look:
<para>Hello, World!</para>
Easy. Typically with HTML, when you are trying to show a section or make a section stand out, you might use <h1> to make the title stand out. Well in DocBook/XML there are a few more lines, but still easy to do:
HTML:
<h1>This is the title of the section</h1> <p>This is a paragraph in the section.</p> <p>This is another paragraph in the section.</p>
DocBook/XML:
<sect1 id="intro"> <title>This is the title of the section</title> <para>This is a paragraph in the section.</para> <para>This is another paragraph in the section.</para> </sect1>
If you are looking for a little bit more information concerning documentation in the Ubuntu world, take a look at the Documentation Team Wiki Page. There is also a bit of information on how we use Bazaar when working with documentation as well. To get an idea of how we use DocBook/XML with Kubuntu documentation, take a look at the old Jaunty Documentation for Kubuntu. Under the docs/ directory you will find the topics covered. And then under the topic, in the C/ folder is the XML markup for that topic. There is obviously a bit more DocBook/XML markup in our documentation, but the header portion and the layout is already completed in a template, so all one would need to do is fill in the space and create new sections.
If you have any questions, please do not hesitate to stop by the Ubuntu Documentation IRC channel on Freenode in #ubuntu-doc and ask away. We also have a mailing list where you can ask questions and communicate via email to other documentation people.
