Quirks wiki

Quirks with Wiki - systems

This project is documented in Markdown under it's wiki-pages, which in turn are SCM:ed by git and front-ended by either or both:

• Gitit
• Github

The two front-ends work in a similar fashion, both use git as back-end which is excellent. The main difference is that with Gitit you work locally and don't depend on either network connectivity or Github.

Their respective Markdown flavours are however not entirely compatible with each other. As we love non lock-in and transparency, we want the wiki to run on both systems.

Pointing these differences out is the main the purpose for this "quirks" page.

Avoid non-standard

Github, being the lesser Markdown-complaint system and having it's own extensions, writing pages in Github very easily becomes non-portable.

As mentioned, we don't like lock-in, and neither should you. It's pure evil and a plague that has haunted computer science practically since from it's birth. It goes against the very heart and soul of Free Software, and even FOSS for that matter. Avoid avoid avoid...

WYSIWYG using instant-markdown Vim-plugin

Editing markdown pages you can use either of the above front-ends. I however find it much nicer to edit them with the Vim plug-in instant-markdownincluded as sub-module in this project.

You get instant WYSIWYG which makes the need to git-commit just to test the rendering of a page much less needed.

Additional benefits of this practice:

• You can squash commits that belong together just as you would do with source-code, thereby avoid too much clobbering of the git-history.
• Using Vim you would naturally write text that is readable in *ANY EDITOR. Neither Gitit and Github promote clear-text readability this, especially when it comes to line lengt's.
• Sane line-lengt's makes diffs even in text much easier to read, grasp and manage.

Specifics

Filenames

Github expects file-names not to contain white-spaces which is non-Markdown complient. Instead dashes (-) should be used. To make Wiki work on both Github and Gitit, we'll adapt to the lesser. Rendering in Gitit looks annoyng with the dashes visible in page headers but it's a compromize we can live with.

Structure

I.e. documentation with sub-directories.

• Github wiki supports it, but you can't create structure in Github. If you try, it will still be flat, and a Github-extention (evil grin) will make links pointing to pages in sub-directories still work (Huh? Naming conflicts someone...?)
• Github has a page reference to the right which renders flat. This makes it hard to distinguish pages based on name only. Therefore all pages in sub-directiries additionally carries the subdirectory in it's name. For rendering purposes, first letter will be in capital however regardless of the subdirectory-name however. For example, this page is under ./quirks/ and its name is Quirks-wiki.md (i.e. full path-name becomes ./quirks/Quirks-wiki.md)

Hint: For structured documentation, don't use Githog. If you must use Githog at all, use it for editing already existing pages.

Links

• Github does not support unnamed links in the format [Page]() where the actual file should be assumed named Page.md in the same directory as the page refering to it. Avoid this short-form.
• Github supports links in media-wiki format [[A-Page]]. It's an extension and hence it doesn't work on other systems/renderers. Avoid non-standard format.
• Github does not support link-anchoring in the form [AnchorTo](Page#Subsection). We'll adapt to the lesser and will avoid this.