В чём писать программерскую и юзерскую документацию?

Plain Old. Можно транслировать в xml, markdown, tex, html. Для html есть скрипты делающие подсветку кода.

Для программерской есть Doxygen.

Markdown

А в маркдауне работает

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#indented-l...

Пиши

Some C++ example::

  int do(int i, int j) {
    return i+j+1;
  }
  extern int dodo();

http://orgmode.org/worg/images/screenshots/org-mode-publishing.jpg

Можно ли без гемора вписать что-то вроде:

Можно.

Заплюсую анонимуса

о, спасибо! не вкурил сначала, что нужна пустая строка между двоеточием и текстом =)

сколько ни пытался освоить емакс: - подтормаживает

- не умеет определять изменённые извне файлы, т.е. если я изменил файл, молчит, если включить опцию, то будет перетирать изменения и т.д. (там какие крипто-команды надо настраивать, почему этой крайне необходимой фичи нет по-умолчанию?)

- после года осваивания вима, понял, что на осваивание емакса потребуется времени не меньше

Markdown

Markdown

+1