Ubuntu Wiki

Ubuntu Open Week - Docs Day - Working with System Documentation - Docbook - EmmaJane - Tue, Apr 28th, 2009

(06:10:17 PM) emmajane: let's get started with the awesomeness of DocBook!
(06:10:18 PM) emmajane: woo!
(06:10:27 PM) emmajane: let's hear some noise in #ubuntu-classroom-chat!
(06:10:31 PM) emmajane: YAY DocBOOK!
(06:11:32 PM) ***emmajane notes the chat channel is waning.
(06:11:58 PM) emmajane: alrighty!
(06:12:15 PM) emmajane: The notes for this talk are at: http://pastebin.ubuntu.com/160267/
(06:12:29 PM) emmajane: please feel free to read ahead, but try to keep questions "on topic." Thanks!
(06:12:53 PM) emmajane: Oh wait. jcastro can you do a topic change?
(06:13:05 PM) emmajane: I don't know how to do fancy IRC things. :/
(06:13:20 PM) ***emmajane proceeds.
(06:13:22 PM) emmajane: Next up we're going to look at the format of the source files for the Ubuntu system documentation files. I've been working with DocBook and talking about it for over five years. My first exposure to DocBook was through The Linux Documentation Project (www.tldp.org) where I was an author and later a coordinator.
(06:13:35 PM) emmajane: This talk has several parts:
(06:13:35 PM) emmajane: 1. Choosing a markup language
(06:13:35 PM) emmajane: 2. Looking at DocBook files
(06:13:35 PM) emmajane: 3. DocBook editors
(06:13:35 PM) emmajane: 4. Common DocBook tags
(06:13:36 PM) emmajane: 5. Transformations
(06:13:41 PM) jcastro has changed the topic to: Welcome to Open Week || Session: 2100-2300 UTC: Working with System Docs - Docbook  || https://wiki.ubuntu.com/UbuntuOpenWeek || All questions to #ubuntu-classroom-chat
(06:14:11 PM) emmajane: This talk is significantly less reading and a lot more poking around with files. Let's get started...
(06:14:23 PM) emmajane: Topic 1: Choosing a Markup Language.
(06:14:37 PM) emmajane: There are three parts to a published document (whether in-print or on-line):
(06:14:37 PM) emmajane: 1. The Content
(06:14:37 PM) emmajane: 2. The Markup (Semantics)
(06:14:37 PM) emmajane: 3. The Transformation (Style)
(06:14:54 PM) emmajane: Let's take a look at each one briefly:
(06:14:57 PM) emmajane: Content is the most important thing you'll ever do (when it comes to technical documentation)!!
(06:15:05 PM) emmajane: The markup language, such as DocBook, is used to describe the content. Adding meaningful tags to your document helps keep consistent formatting.
(06:15:17 PM) emmajane: The transformation is what converts the document into a human-readable format. The final file might be rendered by a browser, or output from a printer.
(06:15:36 PM) emmajane: There are a lot of converters available which allow you to switch from one markup language to another. This means you can write your documentation in just about any format you'd like. Even if it's just plain text, that's fine!
(06:15:46 PM) emmajane: Of course if you want to submit system documentation to the Ubuntu project it will need to use the markup language DocBook.
(06:16:00 PM) emmajane: For more information read: The Secret Life of Markup by Steven Champeon http://hotwired.lycos.com/webmonkey/02/42/index4a.html
(06:16:26 PM) emmajane: As you can see Markup is just *part* of what it takes to write good documentation.
(06:17:10 PM) emmajane: But in this session we're going to focus on only that one slice: the markup.
(06:17:16 PM) emmajane: Topic 2: Looking at DocBook files
(06:17:23 PM) emmajane: Let's take a look at a DocBook file. In a Web browser, please pull up the following page. It's a sample document from the ubuntu documentation project. Please have your browser window open next to the IRC window as I'm going to be referencing this file.
(06:17:31 PM) emmajane: http://bazaar.launchpad.net/~ubuntu-core-doc/ubuntu-doc/ubuntu-karmic/annotate/head%3A/about-ubuntu/C/about-ubuntu.xml
(06:18:13 PM) emmajane: If you've finished downloading the system files, you can also peek inside: ubuntu-doc/about-ubuntu/C/about-ubuntu.xml
(06:18:35 PM) emmajane: Now that you've got that file open, let's take a look.... actually first off: is anyone here colour blind? It makes life a little more tricky if you are...
(06:19:26 PM) emmajane: There are a few different kinds of things that I'd like you to see. First of all: DocBook is a tag-based markup language. Anything inside of a green <tag> is a little piece of DocBook.
(06:19:36 PM) emmajane: Please scroll down to line 48. Take a look at that line.. it's real text! DocBook merely provides the structure to a bunch of plain text words.
(06:20:58 PM) emmajane: Now scroll back up to line 29. Do you see the word that is bold and in reddish-brown? &distro-rev; This is an entity--it refers to another file somewhere else and allows the documentation team to place identical content into various parts of the documentation.
(06:21:27 PM) emmajane: Want to see what the value is for that entity? Take a look at the "rendered" version of that XML file. On your desktop, navigate to System -> About Ubuntu. it's the same content, but rendered for human consumption! (I think transformations are cool, but I might be sort of weird.)
(06:22:09 PM) emmajane: Step away from the scary DocBook file and take a look at the rendered text in the System menu....
(06:22:31 PM) emmajane: <dinda> Why do some lines wrap and others don't?
(06:22:46 PM) emmajane: good question! This is "simply" to do with the settings that each of the authors used.
(06:22:51 PM) emmajane: White space is ignored.
(06:23:25 PM) emmajane: Has everyone taken a look at System, About Ubuntu?
(06:23:40 PM) emmajane: Go take a peek!
(06:24:17 PM) emmajane: You can see how the words that were &something; have been converted into real text that is relevant to your system.
(06:24:32 PM) emmajane: for example: mine says 9.04. But if you're running LTS it'll say 8.04
(06:24:34 PM) emmajane: cool, eh?
(06:24:43 PM) emmajane: ok....Let's take a look at what else is in this file....ah right, the stuff at the top in light blue. These are the instructions that talk about what version of DocBook the document is using (4.1.2), where the files are that contain the entities (.ent files).
(06:24:49 PM) emmajane: (back in the Web browser)
(06:24:59 PM) emmajane: <dinda> QUESTION: Why can't we just use a wysiwyg editor for docbook?
(06:25:19 PM) emmajane: We'll take a look at possible editors in the next section. Good news: you can use a WYSIWYG editor...sometimes.
(06:25:38 PM) emmajane: We can also see that this is an "article." You can also make "books" and "slides" using DocBook.
(06:26:01 PM) emmajane: Without going into the tags themselves, are there any other questions about what a DocBook file is?
(06:26:16 PM) emmajane: We've taken a look at the "code" and the output.... but what other questions do you have?
(06:27:45 PM) emmajane: <jtholmes> looks a lot like XML always has ending tags
(06:27:51 PM) emmajane: Absolutely!
(06:27:56 PM) emmajane: that's exactly what DocBook is. :)
(06:28:34 PM) emmajane: see up at the top of the web page there's a long URI that ends in .DTD? That's exactly the same as other XML files except this time it's DocBook XML
(06:28:49 PM) emmajane: Topic 3: DocBook editors
(06:28:56 PM) emmajane: Fortunately you can use just about any kind of text editor for DocBook. You may want to use a fancy XML editor, or a graphical editor (like OpenOffice.org), or just a regular text editor (like gedit).
(06:29:03 PM) emmajane: (sad news)
(06:29:04 PM) emmajane: Note: right now I'm getting Java errors in Jaunty when I try to open an XML file in OOo. I know that you can edit DocBook in OpenOffice.org v3, but I'm not sure which package is not provided in Jaunty by default. I'll post something in the transcript of this session when I know more....
(06:29:16 PM) emmajane: What text editors are you using right now? Let's take a look at whether or not you are already equipped to edit a DocBook file.
(06:29:28 PM) emmajane: How many people use vim?
(06:29:28 PM) emmajane: How many people use gedit or the KDE editor?
(06:29:28 PM) emmajane: How many people use Emacs?
(06:29:28 PM) emmajane: How many people use OpenOffice.org?
(06:29:36 PM) emmajane: Or something else entirely!
(06:30:14 PM) ***emmajane collates responses from -chat: jEdit, Vim
(06:30:44 PM) emmajane: The hardest part about editing the system documentation is finding the right file to edit. Take a look in your Web browser again.
(06:30:54 PM) RoozbehOnline is now known as Roozbeh|Away
(06:30:59 PM) xray7224: i use vim :P
(06:31:07 PM) emmajane: See the link at the top to "download file"? Go ahead and click it now... Save the file to your desktop. Next open up your favourite text editor. If you don't have a favourite, use gEdit which is available under Applications, Accessories, Text Editor.
(06:31:25 PM) ***emmajane adds bluefish to the list of editors.
(06:31:38 PM) emmajane: (this is in your Web browser again)
(06:32:08 PM) emmajane: Once again, that Web page is at: http://bazaar.launchpad.net/~ubuntu-core-doc/ubuntu-doc/ubuntu-karmic/annotate/head%3A/about-ubuntu/C/about-ubuntu.xml
(06:33:09 PM) emmajane: Once you've downloaded the file, make sure you open it up in a text editor.
(06:33:44 PM) emmajane: It's all scary and voodoo in there, but it's also "just" a plain text file that you can open with any text editor. (Yes, even Notepad on windows.)
(06:33:48 PM) emmajane: You can see that even though DocBook looks like "code" it's a simple text file that can be edited "by hand."
(06:33:51 PM) xray7224 left the room ("laaaaaaaa (window smash's)").
(06:34:12 PM) emmajane: Now that we have file open, let's look even closer...
(06:34:15 PM) emmajane: Topic 4: Common DocBook tags
(06:34:25 PM) emmajane: The tags in DocBook are a way of adding meaning to plain text content. There is a really great online reference book at http://www.docbook.org/tdg/en/html/docbook.html which explains what all of that tags are. There are HUNDREDS and that can be a little bit overwhelming.
(06:35:09 PM) emmajane: Remember though: when you looked at the System Documentation (About ubuntu) all of those tags were hidden and instead you were seeing nicely formatted text.
(06:35:15 PM) emmajane: One way to get a feel for DocBook is to look through an existing file to see which tags have been used.
(06:35:47 PM) emmajane: If you are using a GUI editor, like OpenOffice.org you would never need to see these tags.
(06:36:15 PM) emmajane: Unfortunately, because there are so many tags (over 300) it's hard for graphical editors to implement the *entire* set.
(06:36:22 PM) drostie is now known as drostie|dreams
(06:36:32 PM) emmajane: This is why it's taken so long for OOo and other graphical editors to get on board.
(06:36:43 PM) emmajane: Here are some common tags in a comparison table that shows HTML and DocBook:
(06:36:43 PM) emmajane: http://web.archive.org/web/20041024082240/xtrinsic.com/lsm/docbook/foil14.html
(06:37:31 PM) emmajane: Yes, that's sort of a horrible URL to use... it's from a talk I gave in 2004 about DocBook as found in archive.org. This also shows you that unlike a lot of stuff, DocBook rarely changes. ;)
(06:37:46 PM) emmajane: Once you get the hang of it, you're golden!
(06:37:54 PM) emmajane: And here are some tags that are very common in the Ubuntu system documentation:
(06:37:54 PM) emmajane: https://wiki.ubuntu.com/DocumentationTeam/DocbookTags
(06:38:04 PM) emmajane: And also a great summary of the whole process (including common DocBook tags) at: http://www.lynxworks.eu/files/BugsPlaybook.pdf
(06:38:45 PM) emmajane: HTML has about 1/3 the number of tags, so it feels "easier" to people who are new to markup language.
(06:38:58 PM) emmajane: realistically though, *nobody* uses them all. ;)
(06:39:10 PM) emmajane: <dinda> QUESTION: are their any known 'problem' tags?  ones to avoid using
(06:39:22 PM) emmajane: Problem tags will depend on your transformation toolkit.
(06:39:43 PM) emmajane: Sometimes things like graphics get a little bit dicey.
(06:40:28 PM) emmajane: Generally though, if you can figure out the tags, someone else will have figured out how to do the transformations. :)
(06:40:52 PM) emmajane: Does anyone have questions about the tags they're seeing in their text editor?
(06:41:12 PM) emmajane: It's a fairly straight forward set of tags. Nothing TOO fancy.
(06:42:24 PM) emmajane: If you've downloaded the source files from the previous session as well, you can go poke around in those files to see if there are other tags that are "intriguing."
(06:42:31 PM) emmajane: <jtholmes> QUESTION: does intentation leading white space matter
(06:42:40 PM) emmajane: Just like all XML: white space is ignored.
(06:43:11 PM) emmajane: <dinda> QUESTION: Lines 42, 43  and others have what look like old line numbers - are those part of the revision history?
(06:43:37 PM) emmajane: Click them and see what happens. :)
(06:44:16 PM) emmajane: Indeed it is part of the revision history. Loggerhead (the graphical viewer) automatically links them to the "older" version of the file.
(06:44:39 PM) emmajane: Where there are numbers, like line 16, it has to do with merged branches.
(06:45:43 PM) emmajane: <mfitzhugh> What do status attributes refer to?
(06:46:07 PM) emmajane: Those are internal flags for the documentation team to say whether or not the material as been reviewed.
(06:46:11 PM) emmajane: DougieRichardson, are you still up?
(06:46:15 PM) emmajane: DougieRichardson, can you speak to those?
(06:46:41 PM) DougieRichardson: emmajane: sorry wasn't paying attention - what was the question
(06:46:53 PM) DougieRichardson: Ah status?
(06:46:54 PM) emmajane: look up three lines. ;)
(06:47:10 PM) emmajane: e.g.  <sect1 id="about-ubuntu-name" status="review">
(06:47:22 PM) DougieRichardson: We use them within the team to control where we're at with them
(06:47:30 PM) emmajane: What are the other options?
(06:47:37 PM) DougieRichardson: review - needs review
(06:47:38 PM) emmajane: i.e. what other "status" can a section have?
(06:47:57 PM) DougieRichardson: it can be anything
(06:48:00 PM) DougieRichardson: but writing
(06:48:05 PM) DougieRichardson: review
(06:48:11 PM) DougieRichardson: and complete are the most common
(06:48:19 PM) emmajane: excellent, thanks. :)
(06:48:22 PM) c is now known as Guest2298
(06:48:22 PM) DougieRichardson: we don't use them as much as we could do though
(06:48:28 PM) DougieRichardson: so I wouldn't worry too much
(06:49:13 PM) emmajane: ok, last topic! :)
(06:49:17 PM) emmajane: Topic 5: Transformations
(06:49:26 PM) emmajane: And finally there are transformations. This is the part of the process that allows you to convert DocBook into one of the many formats that we use as part of the documentation team. For example: the Web based version of the system documentation.
(06:49:35 PM) emmajane: Fortunately you don't really need to worry about transformations when you are contributing to the system documentation as this is handled by a set of tools on the server side.
(06:49:46 PM) emmajane: But what if you want to read the documentation that you're working on? It's sort of hard to "see" what you're writing about if you're working in DocBook.
(06:50:21 PM) emmajane: You'll need to "transform" your DocBook into something that you can read!
(06:50:26 PM) emmajane: One of the best little tools for this is a command line utility called xmlto. You can install it using Synaptic or at the command line. If you are working at the command line use the following:
(06:50:26 PM) emmajane: $ sudo apt-get install xmlto
(06:50:58 PM) emmajane: Once installed you can convert your xml files to PDFs using the following command:
(06:50:58 PM) emmajane: $ xmlto pdf yourdocbookfile.xml
(06:51:20 PM) emmajane: If you're just reading the files yourself, this is probably more than enough. There are more complicated setups, of course. But I like to keep things simple where I can!
(06:51:56 PM) emmajane: For example: this tool won't be enough if you also need to embed fonts and do any kind of crazy customizations to your files, but it will be "good enough" to read the files you're writing in DocBook.
(06:52:54 PM) emmajane: And that, in a 40 minute nutshell, is DocBook! We covered:
(06:52:55 PM) emmajane: 1. Choosing a markup language
(06:52:55 PM) emmajane: 2. Looking at DocBook files
(06:52:55 PM) emmajane: 3. DocBook editors
(06:52:55 PM) emmajane: 4. Common DocBook tags
(06:52:55 PM) emmajane: 5. Transformations
(06:53:25 PM) emmajane: We've still got another 10 minutes and then it's an open slot after this. Please feel free to hammer the -chat channel with questions!!
(06:53:38 PM) emmajane: We'll start off with a recap of what an entity is...
(06:54:12 PM) emmajane: An "entity" is a short form that allows you to refer to text elsewhere.
(06:54:19 PM) emmajane: You can think of this as a portal.
(06:54:53 PM) emmajane: Like a black hole portal. They take you to another dimension.
(06:55:16 PM) emmajane: If we go back to the Web-based file you saw a number of black hole portals (entities).
(06:55:24 PM) emmajane: they always start with & and end with ;
(06:55:39 PM) emmajane: <dinda> like a time portal or black hole portal?
(06:55:40 PM) emmajane: <dinda> ah, like a worm hole ;)
(06:55:58 PM) emmajane: I have to paste that clarification because I'm a Luddite when it comes to sci fi references. :)
(06:56:55 PM) emmajane: When a document is rendered into something its new form, all of the entities are expanded and the little worlds of text that were contained on the other end of the worm hole "appear" in the full document.
(06:57:39 PM) emmajane: In the Web URL that we looked at the version of Ubuntu was expanded from &distro-rev; to 9.04
(06:58:10 PM) emmajane: This means we don't have to search and replace 9.04 when it's time for 9.10. We just update the other end of the worm hole to have the new value.
(06:58:49 PM) emmajane: at the other end of the worm hole it looks like this:
(06:58:50 PM) emmajane: <!ENTITY language "en">
(06:59:01 PM) emmajane: If I wanted to put "en" somewhere I would use &language;
(06:59:14 PM) emmajane: this is especially relevant for HTML pages.
(07:00:09 PM) emmajane: again we can refer to that Web file.
(07:00:11 PM) emmajane: <!ENTITY % gnome-menus-C SYSTEM "../../libs/gnome-menus-C.ent">
(07:00:33 PM) emmajane: in this case the value of the entity is stored in an external file, libs/gnome-menus-C.ent
(07:01:30 PM) emmajane: You can also create catalogues, which are sort of like a shopping store of entities that you want to use in multiple projects.
(07:01:57 PM) emmajane: http://www.oasis-open.org/committees/entity/spec-2001-08-06.html <--- scary specification document.
(07:02:41 PM) emmajane: That wraps up our time, but I'm happy to stick around if people have more questions!
(07:03:14 PM) emmajane: Thanks for slogging through it with me. These are conceptually very difficult topics!