5 ms·
There are so many markup languages and conversion possibilities, just have a look on the to-from option from pandoc. Personally, I prefer reStructuredText, its
by smartmic 8y ago
There are so many markup languages and conversion possibilities, just have a look on the to-from option from pandoc.
Personally, I prefer reStructuredText, its design feels more consistent in comparison to the ambiguous implementations of the various markdown dialects.
In Asciidoc, I do not like that lower lever headings occupy more markers than higher level ones. Visually,
=== This heading
appears more important than
== This heading
By the way, a good comparison is at http://hyperpolyglot.org/lightweight-markup http://hyperpolyglot.org/lightweight-markup
- xrd 8y agoWell worth the read. I agree.
- warent 8y agoThere's a couple reasons why I think it would be bad if higher level headings would be considered more important. First, in HTML, <h1> is the top heading which directly maps to = heading If you were to do it the other way around, there's no easy way to know which would would map to h1 ======= this? ============= this? The second reason why is because you have to have a baseline of maximum-importance. It's like ticket priorities capping out at P0 for maximum priority. The first intuitive thought would be that P5 should be more important than P0, but if you don't set a baseline of maximum importance, then there will always be someone who feels their thing is slightly more important. ========== Top level heading =========== Super top level heading ============== Extra super top level heading deluxe
- smartmic 8y agoFrom a technical implementation point of view, I agree. But I had the viewpoint of a visually guided human, the non-technical type. That is also why I stick to reStructeredText, they circumnavigate ATX-style headers at all.
- smartmic 8y agoConcerning the baseline, doesn't the HTML5 standard just specify 6 ranks from <h1> … <h6>? Would be at least a candidate for common agreement on the lowest (highest) rank.
- occamrazor 8y agoHTML5 also supports nestet <section> with their <h> tags. I’m not sure if there is a maximum nesting level in this case.
- Someone 8y agoAnother argument in favor of adding markers for lower levels is that indenting the first character of a header typically indicates lower level headings in a table of contents. Chapter 1 ............... 5 Section 1a ............. 7 Section 1b ............ 11 Chapter 2 .............. 17 Section 2a ............ 21 is nicely similar to # Chapter 1 Lorem ipsum dolor sit amet. ## Section 1a Lorem ipsum dolor sit amet. ## Section 1b Lorem ipsum dolor sit amet. # Chapter 2 Lorem ipsum dolor sit amet. ## Section 2a Lorem ipsum dolor sit amet.
- mikeholler 8y agoI think this is a bikeshedding criticism more than something that requires serious concern. Asciidoctor simply supports more out-of-the-box and officially than reStructuredText. Preferring reStructuredText to Asciidoctor this way is like comparing Python to Ruby for syntax alone. Function is just as important. In Asciidoctor, I can: * Use GraphViz (and other diagram) docs to describe architectural components. * Actually test my example code, using named, delineating comments in my test suite and including the code between those comments as an example in my file. * Support for WARNING, NOTE, etc. callout "admonitions" * Auto-numbered list blocks with "." Some of these may be possible with reStructuredText, and can definitely be supported with third party plugins, but all of this is first-party and amazing. Note: IntelliJ's Asciidoctor plugin is incredible and it live renders mathematical equations AND graphing support in addition to everything else.
- cyberbanjo 8y agoSounds like org-mode. All hail Emacsen.