discuss: Use markdown for Leo's documentation #1147

[Matt Wilkie]

Re: https://github.com/leo-editor/leo-editor/issues/1147. Posting as a thread in groups to keep the issue short and clean.

Edward:

I much prefer markdown syntax, but there questions about using markdown:

1. Replacing Sphinx .css. This css is a minimal .css that replaces the GitHub markdown css.
2. Markdown does not support tables of contents, glossaries, etc. Pandoc translates between rst and markdown, but it's unclear how good the translation is.

Matt:

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. ;-)

--matt

[Edward K. Ream]

On Monday, May 13, 2019 at 3:11:24 PM UTC-5, Matt Wilkie wrote:

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).

Thanks, Matt, for these links.  I had no idea AsciiDoctor existed. I'll look into it next.

Edward

[Edward K. Ream]

On Monday, May 13, 2019 at 3:11:24 PM UTC-5, Matt Wilkie wrote:

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).

The code blocks feature is something that Leo must have.  The other features look useful as well.

I had not given any thought to markdown's failings. I've changed the title of #1147.

Anyone think AsciiDoctor is a bad idea?

Edward

[Terry Brown]

On Tue, 14 May 2019 03:50:46 -0700 (PDT)
"Edward K. Ream" <edre...@gmail.com> wrote:

> Anyone think AsciiDoctor is a bad idea?

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.

Pandoc markdown has enough extensions to allow research papers to be
written in it (tables, figures, captions, citations, cross references
etc.) but it's more a collection of plugins adopting assorted
variations than a coherent whole.

I wish restructuredText or something like it had won the text markup
war and not markdown, but it didn't.

I haven't used asciiDoc but I've heard of it often enough to think it's
a persistent ecosystem, it's just a matter of balancing functionality
with familiarity across possible contributors.

Cheers -Terry

[Edward K. Ream]

On Tue, May 14, 2019 at 8:46 AM Terry Brown <terry...@gmail.com> wrote:

Thanks for these comments.

I think it's easy to argue that there are better (more expressive /
extensible) text dialects than markdown.  restructuredText is an obvious
example.

That's what Leo uses at present.

The big win for AsciiDoctor, as I see it, are code blocks that can be referenced. This would allow a frequently-requested feature, namely gathering code snippets into docs.  Imo, this makes AsciiDoctor worth a close look. I'll revise the rst3 command if we go with AsciiDoctor, but referencing code blocks is worth the effort.

I don't think we need to worry about what "everyone" uses or expects, so long as those writing big chunks of Leo's docs are comfy with AsciiDoctor.

Edward

[Edward K. Ream]

On Tuesday, May 14, 2019 at 5:50:46 AM UTC-5, Edward K. Ream wrote:

> The code blocks feature is something that Leo must have.  The other features look useful as well.

For example, the various tables features would moot #433: re the tables.py plugin. I would like to retire this unfinished plugin.

Edward

[Matt Wilkie]

Hi Terry! thanks for chiming in

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.

A salve for this is Markdown compatibility, via AsciiDoctor, though it remains to be tested how much of the itch that would absolve.

https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#markdown-compatibility

--matt

[Kent Tenney]

I don't use a lot of rst capability, but really depend on

.. contents::

to generate links to sections in a document

anyone found a way to do that in Markdown?

Thanks,

Kent

--
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.

[Terry Brown]

On Tue, 14 May 2019 16:07:15 -0500
Kent Tenney <kte...@gmail.com> wrote:

> I don't use a lot of rst capability, but really depend on
> .. contents::
>
> to generate links to sections in a document
> anyone found a way to do that in Markdown?

I think pandoc will generate tocs from markdown, I know it will if the
target's PDF, but presumably other targets too.

But pandoc uses lots of extensions.

Cheers -Terry

> Thanks,
> Kent
>
> On Tue, May 14, 2019 at 3:12 PM Matt Wilkie <map...@gmail.com> wrote:
>
> > Hi Terry! thanks for chiming in
> >
> > 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.
> >>
> >
> > A salve for this is Markdown compatibility, via AsciiDoctor, though
> > it remains to be tested how much of the itch that would absolve.
> >
> > https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#markdown-compatibility
> >
> > --matt
> >
> > --
> > 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

> > <https://groups.google.com/d/msgid/leo-editor/3e92270d-237c-43bf-9ce0-a6df1366bf89%40googlegroups.com?utm_medium=email&utm_source=footer>
> > .

[Edward K. Ream]

On Tue, May 14, 2019 at 4:07 PM Kent Tenney <kte...@gmail.com> wrote:

I don't use a lot of rst capability, but really depend on

.. contents::

Leo will always support the rst3 command, so you should have no worries.

Edward

[Offray Vladimir Luna Cárdenas]

Hi,

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, which, BTW, has an Abstract
Syntax Tree that enables high programmability an personalization[2] from
several  programming languages, including Python, Lua, Ruby and
Javascript. If you need a particular feature for your publishing, you
can rely on a formal specification of it, via a programming language
that reads and writes using Pandoc's AST facilities. We have used that
several times on complex documentation projects of our local community,
like the ports of the Data Journalism Handbook (Spanish at [3]) and the
Data Feminism Book [4] to our pocket infrastructures and custom
templates on the Grafoscopio[5] and Documentathon manuals[6]

[1] https://commonmark.org/
[2] https://pandoc.org/filters.html
[3] https://mutabit.com/repos.fossil/mapeda
[4] https://mutabit.com/repos.fossil/datafem/
[5]
https://mutabit.com/repos.fossil/grafoscopio/uv/Docs/En/Books/Manual/manual.pdf
[6] https://mutabit.com/repos.fossil/documentaton/

What I like about AsciiDoc is the code snippets support and the way it
declares tables. But Pandoc can read ASCIIDoc and also has
importing/exporting support for ipynb files, and we know the increasing
importance of Jupyter Notebooks in the Python ecosystem. Also, as
Pandoc's author Jhon MacFarlane, makes a good comparison between both[7]
(of course he chooses Pandoc's Markdown) 

[7] https://news.ycombinator.com/item?id=9206755

So, while my advice is not use plain Markdown for (Leo's) documentation
I would strongly consider Pandoc's Markdown as a serious contender
against AsciiDoc, and while the last has a nicer set of features in some
fronts, like tables, and code snippets, the former has the incredible
extensibility of a programmable Abstract Syntax Tree, and we a Leonizens
know about the power of programmable trees.

Cheers,

Offray

[Matt Wilkie]

What I like about AsciiDoc is the code snippets support and the way it

declares tables. But Pandoc can read ASCIIDoc [...]

(?) This seems to be in the air or incomplete according to https://github.com/jgm/pandoc/issues/1456. (From the ycombinator thread you linked, which by the way also highlights another consideration: Asciidoc readability of nested lists in plain text is somewhat compromised relative to Markdown.)

I have generally high opinion of pandoc. It has saved me many hours of frustration more than once.

It's hard to install automatically on Windows (it's not just `pip install pandoc`, last time I checked), but easier than AsciiDoctor which is in Ruby.

--matt

[Matt Wilkie]

Since we're discussing documentation and have stretched into scholarly writing and book writing, Pollen is worth a serious look. Not for Leo, I don't think, it's too different, but the reasoning and thinking which went into it resonates strongly with me. Plus it's just a damn good read. ;-)

https://docs.racket-lang.org/pollen/

"At the core of Pollen is an argument: 1) Digital books should be the best books we’ve ever had. So far, they’re not even close. 2) Because digital books are software, an author shouldn’t think of a book as merely data. The book is a program."

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 don't think I'll venture into racket-lang, not enough attentive hours in the day, but the thinking over there is inspiring. It puts me in the same "the future is bright" mood as Offray's Grafscopio, Mike Bostock's Observable live code, and Leo's tree's and clones and working with external files in-situ.

--matt

[Edward K. Ream]

On Tue, May 14, 2019 at 6:34 PM Offray Vladimir Luna Cárdenas <off...@riseup.net> wrote:

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

My next post will discuss the design of support for AsciiDoctor in Leo.

Here, I'll just point out that such support will not inhibit the use of other tools such as PanDoc.

Edward

[Terry Brown]

On Tue, 14 May 2019 20:26:47 -0700 (PDT)
Matt Wilkie <map...@gmail.com> wrote:

>
> >
> > What I like about AsciiDoc is the code snippets support and the way
> > it declares tables. But Pandoc can read ASCIIDoc [...]
> >
>
> (?) This seems to be in the air or incomplete according to
> https://github.com/jgm/pandoc/issues/1456. (From the ycombinator

> thread, which by the way also highlights another consideration:

> Asciidoc readability of nested lists in plain text is somewhat
> compromised relative to Markdown.)

The R software community and in particular the ~commercial RStudio
front end are I think helping to drive the markdown -> pandoc pipeline,
so it might be more mature / maintained than some other input formats
for pandoc. Not really sure, seeing I haven't really used any other
input formats.

> I have generally high opinion of pandoc. It has saved me many hours
> of frustration more than once.
>
> It's hard to install automatically on Windows (it's not just `pip
> install pandoc`, last time I checked), but easier than AsciiDoctor
> which is in Ruby.

Sometimes I find conda, anaconda's package manager, usually installed
via miniconda, works where pip doesn't, and visa versa. I think I've
been able to install pandoc in Windows with conda, although I've been
using Windows less, again, recently.

Cheers -Terry

> --matt
>

[Chris George]

It seems to me that moving from rst to asciidoc for documentation in Leo is a good move. It adds features and provides a stable path into the future. Rst seems to have "lost" to markdown in the quick and easy markup space.

But markdown seems to still be somewhat of a moving target. I don't see any barriers to providing the same sort of support to the pandoc specific version of markdown as it exists today via a mechanism similar to the rst3 command if someone wanted to write that. But knowing that the specification and the prerequisites for support via Leo will always be subject to change seems to be a bit of a buzz kill for that. And it remains to be seen which flavor of markdown is going to ultimately win in the race to a specification.

When I first came to Leo I taught myself to use rst. I have since added tools to that from the python toolkit that support it. I use nikola to build my static website, for example, and it happily gobbles up all of the rst I can throw at it. All of my organization and templating is done using Leo and its abbreviations. Inertia being what it is I will probably continue to use rst for the forseeable future, simply because it exceeds my requirements for blogging and writing fiction. So I don't really have a preference one way or another as I don't write documentation for Leo.

Chris