reSt oder markdown?

[mutetella]

Hallo,

ich schreibe parallel zum Programm auch die Dokumentation mit. Bisher hab' ich das in meinem trac-Wiki unter deren Syntax gemacht. Damit ich nun dieselbe Textquelle später auch unter Bitbucket verwenden kann, möchte ich die (IMHO auch sehr sperrige) trac-Syntax durch reSt oder markdown ersetzen.
Momentan tendiere ich ein klein wenig zu reSt, da es bereits in trac implementiert ist, markdown wird jedoch auch in einer der nächsten trac Versionen integriert sein. Ansonsten sieht es für mich so aus, als wäre es ziemlich wurschd, für was ich mich entscheide. Ist es so oder gibt es Argumente für das eine oder gegen das andere?

mutetella

[lunar]

@mutetella ReST und Markdown haben beide diverse Vor- und Nachteile, und es ist eher eine Frage der Gewöhnung, für welche Du Dich entscheidest. Letztlich musst Du früher oder später wahrscheinlich trotzdem beide Format können.

ReST allerdings ist schon wegen Sphinx das Standard-Markupformat im Python-Ökosystem. Für mich ist diese Tatsache das entscheidende Argumente für ReST.

[mutetella]

Ich werd' wohl auch reST verwenden. Dabei ist für mich erstmal nicht die (mir durchaus sehr sympathische) Nähe zu Python entscheidend, sondern schlicht und ergreifend die `.. contents::` directive. Gerade beim Schreiben einer Dokumentation ist das schon eine große Vereinfachung. Markdown hat kein Equivalent dafür.

Markdown wiederum geht IMHO einfacher und auch flexibler mit internen oder externen Links um.
So etwas z. B. würde ich gerne mit reST machen:

Code: Alles auswählen

In diesem Text ist allein das Wort python_ verlinkt. Wäre es nicht schön,
wenn man mit weiteren Wörtern, wie z. B.  `like it <python_>`_ auf 
denselben Link verweisen könnte?

.. _python: http://www.python.org

Mit markdown sehr einfach:

Code: Alles auswählen

Das Wort [_python_] verweist auf python.org. Um z. B. 
[like it][_python_] ebenfalls darauf zu verlinken ist sehr einfach.

[_python_]: http://www.python.org

Nun ja, wie so oft: Irgendwas ist immer...

mutetella

[Leonidas]

Der Markdown-Teil ist sogar noch einfacher weil du in der letzten Zeile die eckigen Klammern weglassen kannst. Und die ganzen Unterstriche.

[BlackJack]

Ich wollte mich nur mal kurz lunar's Meinung anschliessen.

[mutetella]

@Leonidas
Das mit den Klammern wusste ich nicht, die Unterstriche musste ich wegen dem Foren-Python-Tag machen...

Wie auch immer: Ich kann nicht verstehen, weshalb es keine Möglichkeit gibt, einen externen oder internen Link zu definieren und diesen dann auf beliebige Wörter anzuwenden. :K

mutetella

[lunar]

@mutetella Laut Dokumentation wird es diese Möglichkeit beginnend mit Docutils 0.11 geben. Wann diese Version veröffentlicht wird, kann ich Dir nicht sagen.

Bis dahin kannst Du Dich einer Kombination von indirekten und anonymen Zielen:

Code: Alles auswählen

In diesem Text ist allein das Wort python_ verlinkt. Wäre es nicht schön,
wenn man mit weiteren Wörtern, wie z. B.  `like it`__ auf 
denselben Link verweisen könnte?

__ python_

.. _python: http://www.python.org

[mutetella]

@lunar
Danke für die Info... Aber sag' mal: Wo hast Du das gefunden? Ich bin auf dieser fürchterlichen sourceforge Projektseite herumgeirrt und hab' selbst jetzt, da ich weiß, dass es diese Info gibt, nichts finden können...

mutetella

[lunar]

@mutetella In der Dokumentation.

[mutetella]

@lunar
Oh Mann, das macht mich jetzt schon a bisl wütend, weiß nur noch nicht auf wen, mich oder den Verfasser der Doku... Die Stelle, die Du verlinkt hast, genauer gesagt eins weiter, die Beschreibung, die auf Version 0.11 hinweist, hab' ich immer und immer wieder versucht umzusetzen.
Dass die Dokumentation bereits auf eine kommende Version vorgreift, dann aber nicht "as of Docutils 0.11" sondern "since Docutils 0.11" schreibt, ist IMHO "etwas unglücklich".

Aber gut, jetzt weiß ich ja Bescheid...

mutetella