Richard A. Johnson

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.

I am really just adding this so I have it documented in case I forget it in the future or need to reference it. One thing I like to do when messing around with web development is when I use a table to hold something, instead of a silly div (really on wiki pages and such to create cheap button-like objects), is use a round border. So here are the example on how to use round borders for tables, utilizing border-radius and CSS.

Firefox

/* 5px radius on all 4 corners of the table */
-moz-border-radius: 5px;
/* 5px radius on top left and bottom right corners only */
-moz-border-radius: 5px 0 5px 0;
/* 5px radius on bottom left and top right corners only */
-moz-border-radius: 0 5px 0 5px;
/* 5px radius on the top left corner only */
-moz-border-radius-topleft: 5px;
/* 5px radius on the bottom left corner only */
-moz-border-radius-bottomleft: 5px;
/* 5px radius on the top right corner only */
-moz-border-radius-topright: 5px;
/* 5px radius on the bottom right corner only */
-moz-border-radius-bottomright: 5px;

CSS 3

/* 5px radius on all 4 corners of the table */
border-radius: 5px;
/* 5px radius on top left and bottom right corners only */
border-radius: 5px 0 5px 0;
/* 5px radius on bottom left and top right corners only */
border-radius: 0 5px 0 5px;
/* 5px radius on the top left corner only */
border-top-left-radius: 5px;
/* 5px radius on the bottom left corner only */
border-bottom-left-radius: 5px;
/* 5px radius on the top right corner only */
border-top-right-radius: 5px;
/* 5px radius on the bottom right corner only */
border-bottom-right-radius: 5px;

Webkit

/* Just add -webkit- in front of the CSS 3 styles */
-webkit-border-top-right-radius: 5px;

KHTML (Konqueror)

/* Just add -khtml- in front of the CSS 3 styles */
-khtml-border-radius: 5px;

And with that said, Why is there 4, count them 4, different ways to skin the same exact cat? Come on browser devs, lets come together and accept 1 solution and implement it. I have been noticing Ajax-like functions out there to do rounded corners, and now I see why. With like 10 lines of JavaScript, you get this same functionality. Now do this in your style sheet, and 1 table could have as less as 4 lines if it is a simple table, or as many as 16 lines for a bit more complex layout. Anyways, just wanted to keep this documented instead of Googling for it all of the time when I need it, and pass it on to all of you fine folks who are unfortunate enough to read my blog. Plus, I also wanted to pass on how web developers, when utilizing border-radius, can now make a KHTML friendly site

Wanted to get this out quickly as the weekend draws near. On Saturday, January 3, 2009, I will be giving a brief introduction on the upcoming Ubuntu Global Bug Jam that will take place towards the end of February.

Off hand, I will probably give a quick talk about:

• What to expect when expecting
• Venue
• The tools we will use
• and answer any questions people may have

If you are interested in participating in the Global Bug Jam next month, come on out Saturday to the Chicago GNU/Linux Users Group meeting. Typically the talks are awesome, the beer is flowing, and afterwards we head to dinner.

When I need to test some Django code, I find it much easier to just run or install a copy of Turnkey Linux and grab the appliance that I need. They have a few different types of appliances and if you need to do any code testing for Django, Rails, Drupal, and more, I suggest you give this a shot if you don’t want to sit there and configure a server just for testing.

One thing with the Turnkey Django appliance, there are 2 HTTP ports. One is 80 for the Django administration interface and the other is 10000 for the Webmin administration interface. One problem I just ran across was how do I forward 2 TCP ports with Virtual Box. Easy, just do this:

$ VBoxManage setextradata <vbox guest name> "VBoxInternal/Devices/pcnet/0/LUN#0/Config/apache/HostPort" 8888
$ VBoxManage setextradata <vbox guest name> "VBoxInternal/Devices/pcnet/0/LUN#0/Config/apache/GuestPort" 80
$ VBoxManage setextradata <vbox guest name> "VBoxInternal/Devices/pcnet/0/LUN#0/Config/apache/Protocol" TCP

To connect to your guest OS via Firefox, you would go to the following URL in your web browser: http://localhost:8888

This works great for one port, but what if I need 2 HTTP ports? Then try this:

$ VBoxManage setextradata <vbox guest name> "VBoxInternal/Devices/pcnet/0/LUN#0/Config/guesthttp/HostPort" 8889
$ VBoxManage setextradata <vbox guest name> "VBoxInternal/Devices/pcnet/0/LUN#0/Config/guesthttp/GuestPort" 10000
$ VBoxManage setextradata <vbox guest name> "VBoxInternal/Devices/pcnet/0/LUN#0/Config/guesthttp/Protocol" TCP

To connect to your guest OS via Firefox to this port, look above on how I explained the connection via port 8888. Just change the 8888 to 8889.
Adding more than this, well that I will have to dig in to further, but for this case, I only needed to forward the 2 HTTP/Apache ports.

Now if you would like to SSH into your guest, try this:

$ VBoxManage setextradata <vbox guest name> "VBoxInternal/Devices/pcnet/0/LUN#0/Config/ssh/HostPort" 2222
$ VBoxManage setextradata <vbox guest name> "VBoxInternal/Devices/pcnet/0/LUN#0/Config/ssh/GuestPort" 22
$ VBoxManage setextradata <vbox guest name> "VBoxInternal/Devices/pcnet/0/LUN#0/Config/ssh/Protocol" TCP

You can now SSH into your guest box by typing the following at the command line:

$ ssh -p2222 username@localhost

Or you could add the following to your ~/.ssh/config:

Host guest
        Hostname localhost
        Port 2222
        User username

And now to connect you would just do:

$ ssh guest

OK, so how many of you are trying out Kubuntu Intrepid with a second monitor which works somewhat, but constantly sits there and blinks on and off? If you answered “ya, mine does that” then this is what you need to do:

1. Open up System Settings
2. Go to the Advanced tab
3. Select Service Manager
4. Select Detecting RANDR (monitor) changes and stop the service
5. Uncheck the box next to the previous step in order to prevent this service from starting up at login
6. Apply everything and close out
7. Enjoy the non-blinking external or 2nd display

Thanks to those of you who responded to bug #278471 for helping us out!

If you spend a lot of time editing wiki pages from within your browser, do I have some good news for you! The good news? It is called editmoin. Editmoin is a simple application, available in the repositories, that allows you to edit any MoinMoin wiki page from within your default text editor.

Setup took me a few minutes to finally get correct, but after dabbling for a few minutes, I got it down. What you will need is the MOIN_ID cookie which you can grab by viewing the cookies from within your browser. The line you are interested in is the Content section. For example, for https://wiki.ubuntu.com, you may see content that looks similar to 1a2b3CdEFG4hIJ/5klMnoPQrsTuVWxyzabCdefgH6iJk. Once you have this, you create a file named .moin_ids in your home directory, and then add the following information:

https://wiki.ubuntu.com 1a2b3CdEFG4hIJ/5klMnoPQrsTuVWxyzabCdefgH6iJk

Once you have done that and saved it, at the command line type the following:

foo@bar:~$ editmoin https://wiki.ubuntu.com/WikiPage

That will open up the page for your editing delight! This is much faster than editing pages with a browser, at least it is for me, and I am sure many of you will feel the same.

Once you have that setup, read over the editmoin documentation for some other customizations such as vi syntax highlighting and aliases. For syntax highlighting you will need 2 extra files:

• moin1_5.vim
• moin1_6.vim

Hope I covered the necessities here, if not, add them to the comments. Thanks!

EDIT: If you do not see MOIN_ID, that means you need to log into the wiki first.