Friday, July 4, 2014

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:`./ --myoptions options.ini`" would render as "./ -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 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.

Wednesday, September 18, 2013

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.


Friday, August 16, 2013

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:

Basically, you just need to execute:

launchctl unload -w /System/Library/LaunchAgents/

No more, no less.

Friday, June 21, 2013

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.

Tuesday, May 21, 2013

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:

Thursday, February 21, 2013

USB connection on Galaxy S3 Mini

Lately my galaxy s3 mini phone was not detected through USB. This is quite annoying... to say the least.

I thought a reboot of my phone would solve the problem, but guess what, it didn't.
I checked the cable, used different ports on my pc and other computers, used different cables, nothing worked, it only started to charge the battery.

I own this phone for only a couple of weeks, so perhaps this thing needed a repair under guarantee. But of course this would take weeks before having it back, so I called my best friend as help.

Google offered me this link

Most of the links referred to Windows drivers but I'm not a Windows user. However, scrolling down led me to a very simple solution:

*#7284# to access PhoneUtil 

 and select PDA in both sections. Reset phone and that's it.

Credits to the user "eidolon" from Australia.

The only thing is that I don't know how I got in this situation... but at least now I know how to solve it.

Thursday, June 7, 2012

Windows 7 and the Search Function

I'm not a Windows lover to say the least, but lately I'm working on Windows for professional reasons, hopefully not for too long.
Being upgraded to Win 7, I must admit that I was surprised in the positive way, but not that I'll replace my Ubuntu. For the simple reason that Windows just annoys me too often (

One of the negative surprises was the search function in Explorer. They made it a real piece of crap of it. I must admit that I'm spoiled with the built-in grep function in my Ubuntu and I also admit that my last search operations date from the Windows XP times. The only thing that I wanted to do is search for a word in a specific file-type. So in XP you could easily perform a search on a file type and then look in this result in the content. You even had a search shortcut in the context-menu of a directory.  Assumed that this function didn't change that much, oh boy, was I completely wrong about that. I know I know, many would say now, why don't you just install a grep-program? Well I guess I'm just too stubborn... Why install a program to perform an action that I could do in Windows XP and if I'm not mistaken in all XP's predecessors?

First of all, Search in context-menu: GONE.
Ok, looking for a search box... found it in the top right corner rather fast, since this is similar to the search in some of the popular web browsers.
Next look for files, that went pretty smooth, start to search the moment I start entering characters.
But this was not what I wanted, I wanted to look for content inside a file, and furthermore content in specific file types. For example I want to look for a word 'parrot', but only in files with file name 'animals.cfg'.
Since I didn't find this immediately, I used my best friend Google. Unfortunately even this friend let me down a bit. No satisfying result on the first results page... how is that possible.
Ok, let's look a bit further then. Finally found how to make the search function also look inside files, the easy but slow way, slow as in takes ages to find a result, even if directory is indexed:

  1. Open Windows Explorer
  2. In the blue bar under the address and search boxes, click Organize and select Folder and search options.
  3. Go to the Search tab. In the What to search box, select "Always search file names and contents..."
  4. That's it, happy looking for content
But of course not the result that I wanted, even when it has to look for content, it only looks for content in the file name. It's getting more and more fun. Now it doesn't even do what they promise.

So looking some more on the web I found that you can use a keyword to look in the content. See the Microsoft answers page. But guess what... And then people keep asking me why I don't like to work with Windows...

I give up, back to my Ubuntu to quickly find my files of a specific file type, containing a specific word. Wow, that took me 1s to type my command and about 0.16s (ZERO POINT SIXTEEN seconds) to give me the list of files. So dear Microsoft, fix your Search function, document it better, or fix your Search function harder.