Plain Text markup (HTML, reST, markdown & co)

September 8th, 2010 by exhuma.twn

Two of my personal quests I’ve been on since I started to work are the hunt for a good note-taking system, and the hunt for a good programming font. This post is related to the former…

My preferred medium to write down notes of any kind has been plain-text for a long time. This feels to me like the digital equivalent of pencil & paper. Mostly…

The big advantage being, that it let’s you focus on what’s important. And that is content! But it has one important challenge. How do you represent section headers, bulleted lists, hyperlinks,… in plain text?

While writing plain text files is quick and easy, sometimes you still want to convert it to a more visually appealing style. Say for example you’d like to incorporate it into a web-page, then converting it to HTML would be nice.

Over the years I’ve dealt with quite a few systems used for plain-text markup. Without a question, the most widely known markup language is HTML. Other’s which come to mind are javadoc, phpdocumentor, ROBOdoc and doxygen. While these are meant to document code, I still count them as markup languages as they have constructs to add style or semantics to the content. All of these are pretty useless as tool to write notes as they are stubbornly assuming you are generating text for code.

About ten years back while writing my own CMS, I needed a way to allow users to markup content. Allowing HTML was not an option because it was hard to edit, and hard to explain for non tech-savvy users. Especially at that time, when the Internet was still something most people considered either “Magic” or the “The Work of The Devil”. I didn’t need much. So I concocted my own markup language, and with not even a one-page introduction, people got productive with it.

A few years later I found what I then considered “The Holy Grail” of markup: And that was markdown. It’s really well designed, and the resulting “source” plain text format is very concise and clean. There’s not a lot of “noise” in the document. It is a perfect candidate for a note-taking format. The only thing that is really missing are tables.

Only recently ( about two years back ) did I come across reST (reStructuredText). It’s been around for quite some time, and I’m surprised I didn’t hear from it earlier. And if I had to sum it up in one word, it would be, without any hesitation: Mature! The “source” you write is, very clean and readable. Some parts (f. ex.: section headings) are even cleaner as in markdown, whereas other areas are not (f. ex.: hyperlinks). But it is much more complete than markdown!

One thing neither markdown nor reST can do very well is interlinking of documents. This is where Sphinx comes in. Sphinx is a document generation system which uses a collection of reST files as input. To completely understand it’s inner workings is not very straight-forward. But easy enough. And it pays off. It generates downright beautiful HTML and PDF (through LaTeX) documents.

In summary I would say that I would in any case prefer reST to anything else. It’s simple for basic cases, but complete enough, when the document starts to grow. Unfortunately I have not yet found convincing parsers for PHP. So in that case I’d go with Markdown Extra. If I needed to write really large documents, I’d consider Sphinx. Primarily because the generated HTML pages have an offline JavaScript search included, and because of the nice default style 😉

Posted in Babble | No Comments »

Best “How to run your internet company” video EVER!

October 24th, 2008 by wickeddoc

this week i’ve stumbled over the following video.

the video shows a presentation from Jason Fried from “37Signals” about how he runs his company.

as i’m working for a small internet service provider myself, i found this video very inspiring and a must-see for everybody in the business.

i think that there are a lot of very good points being made, like teleworking, focus on what matters, don’t waste your time on “david vs goliath” battles etc.

i recommend this video to everybody who owns or works for a small web-related company


Posted in Babble, Techno Voodoo | 3 Comments »

Throwing standards out the window

September 24th, 2008 by exhuma.twn

This really seems to be a trend in software development. Especially on the Web. We have organisations like the W3C that continuously struggle to promote interoperability and standards.While developing I am trying to re-use as much of that knowledge as possible. Afterall, if someone already made the effort to solve a specific problem why should you rethink it again? And actively developing since the late ’90s I can safely say that I’ve seen my fair share of source code.

One thing I have realised is that in the past, developers seemed to care more about clean coding and standards.I have the impression that all this is seriously going down the drain since – let’s name it- the “Broadband Revolution”. Since then about everybody has an Internet connection at home and the number of wannabe web-developers skyrocketed. Now, if you google for JavaScript/HTML/whatever references you do not find one reference, you find hundreds. And about all of them seems to be written by somone who thinks to know better.

Why do these people re-invent the wheel by writing down on their web-space what’s already been written by domain-specialists? Are they trying to show the world just how “good” they really are? Are they looking for recognition on the web that they could not get in real life? Because, frankly, I would not have much respect for the work they do

Back to topic. About standards. Consider the following excerpt:

Note: The latest W3C method to connect an event handler to an event is to use the addEventListener method, similar to Java. However, this is not supported by Internet Explorer, and since Internet Explorer owns 96 percent of the browser market, we can ignore addEventListener.1

It’s statements like these that drive me up the wall. And it’s one of the first links I got back from google when looking into the ins and outs of event handling in modern browsers. I am all for education and educating new (web-)developers about how things should be done. And this simply is not the way! Stating that you should throw out all the standards, simply because the market leader does not support it is just wrong. With this train of thought, the standards will never be adopted properly. Now this is the special case of Web-Browsers and JavaScript support, but this example easily spans over other areas as well.

Having a text like this in the top google hits surely gives newcomers the wrong idea.

I am honestly curious to see how the web evolves in the next few decades. But maybe I’m just too pessimistic and it will all turn out well. Time will tell!


Posted in Babble | No Comments »

Demographics of Open Source projects

September 4th, 2008 by exhuma.twn

One thing I have been asking myself quite often lately: “Why do – even popular – open source projects often have mediocre coding standards?”

My first thought was: Ok, most likely many of the projects were written by non IT-professionals who only code “out of their head” without thinking things through at first. Curious as I am, I googled for the very title of this post. And I fell across an article on Linux Today about a study done by the Boston Consulting Group (Also quoted on slashdot). What I found particularly disturbing was the finding that the most part of the interviewees considered themselves as IT-Professionals. Granted, only interviewing less than 600 developers from only one source (sourceforge), is barely representative, and most likely highly biased as well. But it’s an interesting survey nonetheless.

So, why – in the love of $deity – do so many projects written by allegedly IT-Professionals present themselves with very poor coding style and more often than not very poorly designed database schemata? It’s becoming an increasing nuisance to work with these projects. If you want/need to make changes/extensions to the existing code you often need quite a while to get to grips with the logic behind all that exists.

Interestingly though, the stricter the rules of the used programming language/database the better the code, but the less common it is as well in open source projects. This does not mean though that it’s the fault of the programming language. Not at all. Even with a language as flexible as Perl you still can write very sexy code. But I haven’t seen a single Perl script that fit’s that description (though I haven’t inspected many Perl scripts yet in detail).

I would really like to see a study on the demographics of open source software that focusses it’s goal on coding style/standards rather than on the age group / motivations of coders. And it should also pick a representative sample of developers instead of going the lazy route and only querying sourceforge. This would certainly be an interesting project to do 😉

Posted in Babble | No Comments »

Martian Headsets

March 18th, 2008 by exhuma.twn

One link, lot’s of text 😉

Posted in Babble, Links | 1 Comment »


October 1st, 2007 by exhuma.twn

About these homes and at the intersections of the roads in this nomadic ‘city’ are the gardens. Each is unique. One may centre around an unusually-shaped stump or an arrangement of stones or a graceful bit of wood. They may contain fragrant herbs or bright flowers or any combination of plants. One notable one has at its heart a bubbling spring of steaming water. Here grow plants with fleshy leaves and exotically-scented flowers, denizens of some warmer clime brought here to delight the mountain-dwellers with their mystery. Often visitors leave gifts in the gardens when they depart, a wooden carving or a graceful pot or perhaps merely an arrangement of bright pebbles. The gardens belong to no one, and all tend them.

Robin Hobb, Assassins Quest.
Great Britain: Harper Voyager, 1998

When rading this passage of this book (which is part of the Farseer Trilogy) I could not help but think about Open Source projects. If you did not had the same thought when reading the text, go read it again. It is a beautiful analogy.

Note: If any directly involved party feels that any copyright claims have been violated by posting this, please leave a comment. I will take this text down if so requested.

Posted in Babble | No Comments »

GPG… anyone?!?

September 24th, 2007 by exhuma.twn

I can sympathize that GPG (a free and toolset to encrypt and sign digital data) has not been used by the wide public in the past. It was complex to set up, the concept of private/public keys was a bit flaky to most people, PGP (not GPG!) costs precious money, and integration with mail clients was not trivial.

With the spreading of Mozilla Thunderbird this has changed drastically however. With enigmail (a mozilla-addon to use GPG with the mail client), things are becoming much easier and accessible. It offers most of the functionalities you wish to see in such a tool. It allows you to create a new private/public key pair, has a simple management tool for keys, and lets you very transparently sign and/or encrypt e-mails.

In my opinion, the main reason why GPG is still a thing for “geeks” or “professionals” is the ignorance (or naiveté) of people about how easy mails can be intercepted. Yesterday I demonstrated somebody this exact fact. And him still being quite computer-literate, he was still baffled that I could show him the text of a mail he sent with his password along the lines (All done with his consent of course). And I do not consider myself a hacker. Just a few minutes of googling, downloading and installing the right tool did it for me. And if I can do this, so can many other people as well. With a little bit more effort, it’s even possible to alter the text of a mail in transit. Needless to say, the emails are stored on somebody else’s server. An this in plain text! Even if the server does support SSL, TLS or whatnot. This only means that the transmission between mail-client and mail-server is secured. Not the storage. And you never know who sit’s behind the screen of that server.

Granted, most of the time, people managing servers like this are most likely geeks themselves, which usually share the concern about security, and thus keep things safe.

Considering this, it can become easy to demonstrate the advantages of mail encryption/signing. And usability is increasing steadily. With the mozilla suit (and thunderbird) now having a user-friendly tool at the ready, people are not yet easily convinced to keep security in mind. Other mail-clients offer easy user-interfaces as well. The KDE-Suite (with KMail and KGPG) had brilliant supoprt for this already a long time ago. And there are more free tools available to make it a user-friendly experience. The Swiss-Army-Knife for a Windows environment would probably be GPGShell. It still resorts to the GPG-Cli application from time-to-time, but it keeps it to a minimum. It also offers easy file-encryption via Windows Explorer shell entries. Another alternative is Evolution, which has built-in supoprt for GPG.

Suffice it to say, there is widespread support for GPG (and PGP) in mail-application across all OS’es. To become more widespread in use, people should be made aware of the risks that are posed by e-mails and how easy it can be made to keep personal information really personal.

Posted in Babble | No Comments »

Web Provider Fun

August 16th, 2007 by exhuma.twn

Oh yess… rants… I love to rant… and after my adventures of today and reading the last post, I have to dump my thoughts as well. And this one is about one of our web-providers in our oh-so technically advanced country. Or so they claim.
Read the rest of this entry »

Posted in Babble | No Comments »

VIM rc-file

August 10th, 2007 by exhuma.twn

Due to inane network restrictions I am maintaining several copies of my vimrc file. I would syncronize it though other means. Alas, the restrictions not only cover the network. So I have to resort to simply posting it here.

This is not meant to be an explanation of vim configuration file. However, it contains lots of comments, and might prove a good primer/starting-point. Eventually I will also include other modifications I made in my vim-home-folder as they are either used in the vimrc or just plain useful 😉

Read the rest of this entry »

Posted in Babble, Coding Voodoo | 2 Comments »


Recent Posts