Comparer et contraster les langages de balisage légers [fermé]

90

Veuillez identifier les langages de balisage légers les plus populaires et comparer leurs forces et leurs faiblesses. Ces langages devraient être un balisage à usage général pour la prose technique, comme pour la documentation (par exemple, Haml ne compte pas).

Voir aussi: Markdown contre ReStructuredText

documentation markdown markup restructuredtext textile JasonSmith
la source
1
Voir aussi superuser.com/questions/209897/text-formatter-tools/…
RedGrittyBrick

Réponses:

115

Je connais trois principaux langages couramment utilisés dans la grande communauté de programmation et de technologie: Textile, Markdown et reStructuredText. Tous les trois peuvent être appris en quelques heures ou «ailés» avec la feuille de triche à proximité.

Textile

  • Utilisé par Redmine et la communauté Ruby
  • 113 questions actuellement taguées sur Stack Overflow
  • La source la plus similaire au HTML, mais la moins lisible
  • Listes imbriquées les plus faciles des trois langues
  • Incompréhensible pour les non-programmeurs ou les ignorants du HTML
  • Idéal pour les documents courts complexes (avec liens, listes imbriquées, code, HTML personnalisé); par exemple: brève documentation, tutoriels, contenu de blog ou CMS
  • Référence de syntaxe

Réduction

  • Ne semble pas avoir de «communauté» de langue parlée à la maison, mais ...
  • 1274 questions taguées sur Stack Overflow *
  • Accentue la lisibilité du code source, similaire aux traditions de messagerie
  • Intégration HTML simple (il vous suffit de taper les balises)
  • Aucun moyen de créer des tableaux en plus d'incorporer du HTML
  • Vous le savez déjà si vous connaissez Stack Overflow
  • Facile à apprendre si vous connaissez déjà reStructuredText
  • Obscurcissement automatique des adresses e-mail pour le format <[email protected]> (avec chevrons)
  • Référence de syntaxe

reStructuredText (AKA ReST)

  • Populaire dans la communauté Python
  • 285 questions taguées sur Stack Overflow
  • Un peu de perspicacité sur les espaces et l'alignement si vous me demandez
  • Les listes (en particulier les listes imbriquées) et les paragraphes semblent toujours se battre
  • Lisible par des non-programmeurs
  • Seul format permettant de construire une table des matières (via une extension dans l'implémentation de référence Python)
  • Convertit directement vers d'autres formats tels que PDF et XML
  • Idéal pour les gros documents avec beaucoup de prose (par exemple, une alternative au docbook pour un manuel d'utilisation)
  • Référence de syntaxe
JasonSmith
la source
4
Pour les utilisateurs de ReST, sphinx.pocoo.org ressemble à un très bon outil pour les grandes collections de documentation de référence structurées en arborescence.
bendin
6
Je n'ai aucun problème avec les listes et les paragraphes dans reStructuredText lorsque j'emballe les choses dans Emacs. En fait, ils fonctionnent exactement comme je m'attendais à ce qu'ils le fassent :-)
Martin Geisler
1
Il existe des extensions de Markdown qui permettent de composer des tables en ASCII.
Jakub Narębski
1
ReST possède également un excellent support d'outils: par exemple, notex.ch, basé sur le navigateur, est un bon outil pour expérimenter, apprendre et utiliser ReST (basé sur le backend sphinx.pocoo.org).
hsk81
31

Vous pourriez également envisager l' asciidoc

  • balisage relativement lisible
  • utilisation simple de la ligne de commande
  • certains pourraient le percevoir comme relativement `` pointilleux '' (vs flexible) en ce qui concerne la syntaxe
  • docbook et (x) sortie html
dat
la source
2
Malheureusement, asciidoc a une horrible syntaxe pour les éléments de liste avec plusieurs paragraphes: vous devez les séparer avec une seule ligne ne contenant qu'un signe plus (oui, un "+").
Martin Geisler
4
@Martin: Les éléments de liste à plusieurs paragraphes sont-ils vraiment si importants? Si vous avez besoin de plus d'un paragraphe, les titres / sections ne seraient-ils pas plus appropriés qu'une liste?
Steve S
Le plus grand avantage d'AsciiDoc est qu'il prend en charge beaucoup plus de fonctionnalités. Il peut créer des livres, avoir des sections de conseils, de nombreuses sorties ... powerman.name/doc/asciidoc
Wernight
21

La page Wikipédia sur les langages de balisage légers présente une bonne comparaison entre les différentes options, ainsi que la syntaxe des utilisations courantes (en-têtes, gras, italique, etc.)

technomalogique
la source
5

J'essaie de couvrir tous les différents langages de balisage légers ici:

http://www.subspacefield.org/~travis/static_blog_generators.html

Comme vous pouvez le voir, cela a commencé par "comment puis-je créer un blog sécurisé" - c'est-à-dire un blog qui génère du HTML statique, et je me suis retrouvé pris au piège des langages de balisage, des systèmes de modèles, etc.

Mettre à jour

Je me suis recentré uniquement sur les LWML avec des implémentations python, et ils sont ici:

http://www.subspacefield.org/~travis/python_lightweight_markup_languages.html

Jusqu'à présent, j'ai essayé Markdown et ReST, et j'aime mieux ce dernier pour tout sauf les extraits de code HTML intégrés dans d'autres pages. Tableaux, références croisées, liens indirects, etc ...

Travis H.
la source
4

pour la documentation? Que diriez - vous doxygen ?
Je l'ai utilisé pour certains des projets c / c ++ que je dois documenter. Même vous pouvez en `` abuser '', tout comme l'auteur de doxygen l'utilise pour la documentation de doxygen

mhd
la source