From reStructuredText to DITA... and back?

My life as technical writer started around 2003. Since then I've been using mainly a CMS, wiki, a very short period DocBook and the last couple of years reStructuredText (reST). Recently I've started working with DITA (Darwin Information Typing Architecture) to replace reST. At the company where I'm employed the main tool to edit DITA is oXygen, which is a nifty well-equipped editor, not to say the reference tool for DITA editing. Having used Vim for quite some years as editing tool for reST, oXygen is quite overwhelming when you start it for the first time. Of course I could reconfigure my Vim for DITA editing but that would take quite a lot of time, which I don't have. Still looking for a decent Vim setup though...

Anyway, while switching regularly between DITA and reST, and thus between oXygen and Vim, the DITA markup couldn't convince me as format. Was it due to oXygen as tool or was it really the markup, don't know, probably a mix. When I recently travelled to the US, I had a huge jetlag, so I got awake every day in the middle of the night. As my documentation in reST had to be transformed to DITA format, these nights provided me some extra hours to get the job done. During these nightly hours I got to know DITA and oXygen a lot better and I have to admit, I started to appreciate the markup and the tool. 

At first there seemed to be too many restrictions in DITA but after taking the first hurdle of getting a bit more familiar with the editing tool, it all became more clear. Especially when you switch from an unstructured language, the DITA markup seems so restrictive, but in fact it isn't. On the contrary, it even helps me in writing documentation. While using the DITA markup more and more I get to appreciate some of the features like reusing content, the easy way of adding indexes and metadata, and so on. And after my 2-day training with Yves Barbion at Flow, formerly known as Teka Infopilots and Scripto, I even have some more sympathy for DITA.

So don't I have cons to DITA? Of course there are. The major con is the way of branding your documentation; this is cumbersome, especially if I compare it with reST. 

Suppose you have an identical manual for company A and company B but both companies have their own product names and product versions. Since we don't want to copy the content from one company to another and then apply a find/replace, we'll use variables.

In reST, define I just have to store my variables in a Python dict in my project's configuration file, where the key of the dict is the company name and the value is the a list of values. In this example I would have a dict like this:

my_variables = {

    company_A : ('company_A', 'A_product_name', 'A_product_version'),

    company_B : ('company_B', 'B_product_name', 'B_product_version'),

}

In the same configuration file I have to define which variable name I have to use in my sources and then of course use the variable names in my sources. When building the output, I just have to select which company I want and build. In DITA this is far more complex as far as I know. Because the only way I found now is that you need a ditamap, a key definition file and a variables file per company, which means six files to maintain only for two companies. Still looking for a way to this in a conditional way, which would make it a lot easier.

Besides this major disadvantage, there's some other minor disadvantages, but if one would ask me now what I'd choose between the two of them? 

Well, it all depends on the project. Even Word could do the trick...

Local Instance of READTHEDOCS

I've been struggling in setting up a local instance of readthedocs (rtd) with Solr for searching.

After lots of testing I've come up with the following procedure to have a local instance of Read The Docs and a working Solr. 

Bare in mind that this procedure is not for production instances!

I did this procedure on a clean Ubuntu 14.04 desktop installation.

Prerequisites

Make sure that you install the following packages:

• python-virtualenv
• git
• curl
• libxml2-dev
• libxslt1-dev
• zlib1g-dev
• openjdk-7-dev

Most of the steps can be found in the documentation of readthedocs.org. Here I will show you the steps I followed.

Steps

Use three terminals to get this thing working, one for running readthedocs, one for Solr and one for building the files and saving them into Solr.

1. Create a virtualenv and activate it:
   virtualenv venv
   source venv/bin/activate
2. Create a folder in venv and clone the readthedocs repository:
   cd venv
   mkdir sources
   

   git clone https://github.com/rtfd/readthedocs.org.git

3. Install rtd:
   cd readthedocs.org
   pip install -r pip_requirements.txt
4. Build the rtd database:
   cd readthedocs
   ./manage.py syncdb
   Create a superuser when requested.
5. Migrate:
   ./manage.py migrate
6. Set Solr as local backend in the rtd settings:
1. Go into the settings directory and update the files __init__.py, base.py, and sqlite.py.
2. Update the parameter HAYSTACK_CONNECTIONS with:
   

   HAYSTACK_CONNECTIONS = {
       'default': {
           'ENGINE': 'haystack.backends.solr_backend.SolrEngine',
           'URL': 'http://127.0.0.1:8983/solr',
       }
   }

7. Open your second terminal and create and activate virtualenv, identical as in step 1. 
8. Download and extract Solr 3.5.0:
   

   cd venv/sources/
   curl -O http://archive.apache.org/dist/lucene/solr/3.5.0/apache-solr-3.5.0.tgz
   tar xvzf apache-solr-3.5.0.tgz && SOLR_PATH=`pwd`/apache-solr-3.5.0/example

9. Install pysolr and pyquery: pip install pysolr && pip install pyquery.
10. Go to the directory venv/sources/readthedocs.org/readthedocs.
11. Build a Solr-schema: ./manage.py build_solr_schema > $SOLR_PATH/solr/conf/schema.xml.
12. Go back to the directory venv/sources/apache-solr-3.5.0/example and start solr:
    java -jar start.jar
13. In your first terminal, go to the directory venv/sources/readthedocs.org/readthedocs and start the rtd instance:
    ./manage runserver

You are now able to log in to RTD with the created superuser. Go to 127.0.0.1:8000 for the RTD instance or to 127.0.0.1:8000/admin for the Django settings.

The created setup needs to be filled with data, you can do this via a third terminal and add some projects.

In this third terminal, create a virtualenv as described above and then add projects as follows:

1. Go to venv/sources/readthedocs.org/readthedocs.
2. Add a project with the following command: ./manage.py update_repos
• pip
• haystack
• tastypie
• kong
• read-the-docs
• ...
3. Add the content to Solr, to be able to search in the documentation:
   ./manage.py build_files.

When you add other projects, either via the above command, or by importing them via the rtd web interface, run this last command to make them available through Solr.

You have now a local instance of RTD with Solr as search engine.

A lot more needs to be done in order to make it ready for production environments. Solr should be working in a container, a webserver is required, automation needs to be set up for new projects to become automatically available, and so on. Hope to get this done in the near future.

Until then, have fun with your local ReadTheDocs!

Sphinx, ReadTheDocs and Dashes

For my documentation, I often have to document *nix command-line stuff. No problem until you have to document options that come along with commands.

In Sphinx you have the ":command:" directive to show commands in a uniform way. However, if the command has options that are indicated with a double-dash, the double-dash is by default converted to a single dash.

For example: ":command:`./mycommand.py --myoptions options.ini`" would render as "./mycommand.py -myoptions option.ini". Very annoying indeed, since people tend to copy/paste commands and then they are surprised that "it doesn't work".

Weird thing is that in my local Sphinx setup, using 1.3a0, the rendering is correct, but in the default Sphinx version 1.2.x (if I'm not mistaken, also used by ReadTheDocs), I have the single dash. After looking around on the web, found that the parameter "html_use_smartypants" in the Sphinx conf.py file is the culprit. This parameter is by default disabled, but the smartypants is not disabled by Sphinx and ReadTheDocs itself. This smartypants converts the double dash to a single dash or sometimes en-dash (or em-dash). Since the parameter was commented I didn't take notice of it, but I didn't come to the proper rendering.

To actually disable the smartypants, you have to literally set it to False and then I finally have the correct rendering of my double dash.

# If true, SmartyPants will be used to convert quotes and dashes to

# typographically correct entities.

html_use_smartypants = False

/me happy to start the last day of the week.

Dear Atlassian

To whom it may concern...

I have been using your Confluence since 2007 and the ease of it was just a joy. Ok, it had its shortcomings, but I could live with them, they didn't annoy me. Confluence, you were easy to learn, you were just a plain text editor, you had enough room for easy customizations. All this made that I could focus on my job, which happens to be technical writing in software companies. My last version I worked with was 3.5, but then came August 2013.
In that month I started at a new company where they use a 5.x version. Now one (yes only ONE) month later and you make me already sick.

I suppose that the function of the new interface is to be more user-friendly than a plain text editor. I have to admit, inserting macros is a step forward, same for inserting warnings, tips, notes,...  BUT, what the hell have you been doing with lists? To insert or add a numbered item to an existing numbered list, you have to be a magician. Luckily CTRL-Z does work in your editor.
And why can't I use a bulleted list in for example a warning block, when this block is in a numbered list? Can you give me an explanation for that?

Table of contents macro, maybe it's not your fault, but why do you use different styles? A table of contents is supposed to have a consistent layout, but why some items are in bold, others in a large font-size and some others in smaller font-size, I really don't see the benefit of it.

Apart from my aforementioned vexations, I have a last one to mention. When you create a PDF of a space, the links in the PDF document refer to the online documentation, whereas in 3.5 and earlier versions, they referred to the page inside the PDF. Did this function moved to more comfy places, is it playing trollface, ... You were in there and now you're gone, how hard can it be to get it back?
This bug is reported 721 days ago (27 September 2011, yes that's almost TWO years). It surprises me that you do go to the selected section when you click an item in the table of contents. So where's the difference? I don't see any so just FIX IT, and if you can't fix it, FIX HARDER!

I can't get the idea out of my head that you, Atlassian, are becoming like that other well-known tech giant, founded by Bill Gates. That company too is very good at ditching good parts of software, creating new versions that annoys people, and not listening to their customers.

Perhaps our annual fee is just 0,00000005% of your annual turnover, which makes us just a 'no-influence-at-all' company for you, but I just don't care. Perhaps that some day I will embrace you again with love and care, but right now, I'm ditching you.

Sincerely

Good to know

I recently started working on MacBook Pro, you have to try it all. In the past I had Windows and Ubuntu, so now the time has come to try OS X. Just like every other OS, OS X also has annoyances, of which iTunes is one of my biggest annoyance. Did they replace that team already? Unfortunately you sometimes need it, so I can't get rid of it.

As default music player I now try Songbird and added the keyboard shortcut add-on, which works perfectly. But the downside is that every time you hit a music key (next, previous, play/pause), it also launches iTunes.

The easiest way to get rid of this behavior was nicely noted in the following post:

http://gavinroy.com/posts/disabling-default-itunes-launch-behavior-with.html

Basically, you just need to execute:

launchctl unload -w /System/Library/LaunchAgents/com.apple.rcd.plist

No more, no less.

Thunderbird configureren voor verzenden mails via Telenet account

Toen ik mijn gsm wou instellen om e-mails te ontvangen en versturen via mijn telenet account, kon ik de mails wel ontvangen, maar niet versturen. Ik kon enkel mails versturen als ik op het telenet netwerk zat (wifi of via telenet gsm-abonnement).
Na enig zoekwerk, bleek dat ik dus TLS moest gebruiken en authenticated SMTP om mails te kunnen versturen. Dit direct ook eens gecontroleerd op mijn computer, want ook daar kon ik geen mails versturen via mijn telenet account.

In Thunderbird (getest met versie 17.0.6):

1. Via Edit > Account Settings, selecteer Outgoing Server (SMTP) in de linker kolom.
   Dit is afhankelijk van operating systeem en taalinstellingen!
2. Klik op Add en vul in/selecteer de opties zoals aangegeven in de afbeelding onderaan.
3. Bij gebruikersnaam, geef je je Telenet gebruikers-ID in, meestal bestaande uit 1 letter gevolgd door 6 cijfers zoals in de afbeelding.

Je zou nu zonder problemen mails moeten kunnen versturen, zelfs als je geen gebruik maakt van een Telenet netwerk.

How to close xml tags easily in VIM

From ViM 7.3 onwards, most of the common programming languages are supported (/usr/share/vim/vim73/autoload/...). To make them work automatically, update your vimrc with:

autocmd FileType python set omnifunc=pythoncomplete#Complete
autocmd FileType javascript set omnifunc=javascriptcomplete#CompleteJS
autocmd FileType html set omnifunc=htmlcomplete#CompleteTags
autocmd FileType css set omnifunc=csscomplete#CompleteCSS
autocmd FileType xml set omnifunc=xmlcomplete#CompleteTags
autocmd FileType php set omnifunc=phpcomplete#CompletePHP
autocmd FileType c set omnifunc=ccomplete#Complete

Use CTRL+ X O to close tags after typing the start of the closing tags.

For example:

This is a sample paragraph </ CTRL +X O will automatically complete the closing tag.

Simple as that

More information on configuring ViM: http://newbiedoc.sourceforge.net/text_editing/vim.html