Re: https://github.com/leo-editor/leo-editor/issues/1147. Posting as a thread in groups to keep the issue short and clean.
I much prefer markdown syntax, but there questions about using markdown:
- Replacing Sphinx .css. This css is a minimal .css that replaces the GitHub markdown css.
- Markdown does not support tables of contents, glossaries, etc. Pandoc translates between rst and markdown, but it's unclear how good the translation is.
AsciiDoc as syntax with AsciiDoctor for handling is smarter and on my shortlist. See Stop Using Markdown For Documentation (read conclusion first then go back for details).However I've not stepped up for serious AsciiDoc experimentation because the tools I've used so far for Markdown editing don't support it (Markdown Monster, Markdown Pad). I use tools primarily for 2 reasons:
- paste image and have it converted to a referenced file
- insert link with a keyboard shortcut and have it converted to footnote style (
[title][1]
...[1]: url
)I'm sure both of these features could be done in Leo but I haven't mustered the wherewithal to begin tackling how. ;-)
Re: https://github.com/leo-editor/leo-editor/issues/1147. Posting as a thread in groups to keep the issue short and clean.
AsciiDoc as syntax with AsciiDoctor for handling is smarter and on my shortlist. See Stop Using Markdown For Documentation (read conclusion first then go back for details).
AsciiDoc as syntax with AsciiDoctor for handling is smarter and on my shortlist. See Stop Using Markdown For Documentation (read conclusion first then go back for details).
I think it's easy to argue that there are better (more expressive /
extensible) text dialects than markdown. restructuredText is an obvious
example.
The problem is that markdown's what everyone uses / expects. So the
downside to anything that's not markdown is that people won't know it,
whereas they would know markdown.
--
You received this message because you are subscribed to the Google Groups "leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send an email to leo-editor+...@googlegroups.com.
To post to this group, send email to leo-e...@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
To view this discussion on the web visit https://groups.google.com/d/msgid/leo-editor/3e92270d-237c-43bf-9ce0-a6df1366bf89%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
I don't use a lot of rst capability, but really depend on.. contents::
What I like about AsciiDoc is the code snippets support and the way it
declares tables. But Pandoc can read ASCIIDoc [...]
Writing for the web involves "a steady stream of products, frameworks, tools, and content management systems that claimed to bring a programming model to web development. ... none of them displaced the text editor as the preferred tool of web developers. And none of them matched the power and flexibility you get from any reasonable programming language. ... all separate tools, with different syntax and functions. Good luck finding a single preprocessor that can handle all your web files simultaneously.This kind of thinking — from the edges inward, rather than from the center out — has been the thematic failure of web-publishing tools ... even web-publishing systems ostensibly based on general-purpose programming languages — like WordPress or Django — suffer from recurring deficiencies:
No native data structure for HTML. Core to any programming model is data structures. Good data structures make processing easy; bad ones make it hard. Even though HTML has a well documented format, rarely has it been handled within a programming system with a native, intuitive data structure. Instead, it’s either been treated as a string (wrong), a tree (also wrong), or some magical parsed object (really wrong). This has made working with HTML in programming environments needlessly difficult.
[...]"
I agree on plain Markdown as a bad option for complex documentation, but
almost nobody uses plain Markdown for that but some superset of
CommonMark[1], as happens with Pandoc