Re: discuss: Use markdown for Leo's documentation #1147

[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


-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/6707d0f2-e9d5-4dcc-ba3a-d80f166ba3f7%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[Terry Brown]

On Tue, 14 May 2019 20:26:47 -0700 (PDT)
Matt Wilkie  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
> 

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/20190515071451.7f354f51%40lakeview.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[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

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/CAMF8tS0cS%2Bc9MbD8Hb_9KwhPxcuLNNZLoRHpyNhE_XfEOvGw1A%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[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

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/fb97d7fc-b4de-44ec-9818-a15c2c92fcb0%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[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, 
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

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/777c9bf4-8441-4d06-a044-339a18ad6c2a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[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

On 14/05/19 4:37 p. m., Terry Brown wrote:
> On Tue, 14 May 2019 16:07:15 -0500
> Kent Tenney  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  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+unsubscr...@googlegroups.com.
>>> To post to this group, send email to leo-editor@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.
>>>

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/16e5f9e6-fbbd-a6e9-b03b-04531d5de4c1%40riseup.net.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[Edward K. Ream]

On Tue, May 14, 2019 at 4:07 PM Kent Tenney  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

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/CAMF8tS1dsR5hCHRuFOn%2BGfBOAz99NjCRHkgU443ByHeTZ40cHw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[Terry Brown]

On Tue, 14 May 2019 16:07:15 -0500
Kent Tenney  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  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+unsubscr...@googlegroups.com.
> > To post to this group, send email to leo-editor@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.
> >
> 

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/20190514163749.046bcee8%40lakeview.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[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

On Tue, May 14, 2019 at 3:12 PM Matt Wilkie  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+unsubscr...@googlegroups.com.
> To post to this group, send email to leo-editor@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.
>

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/CAAa_k2cMqe%3DZ7vFkRLRD8dKH2Pd0%3Dk4%2BW8tyecuR_ZAAfFbMDQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[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

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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.

Re: discuss: Use markdown for Leo's documentation #1147

[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

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/533ab943-8138-483b-81f1-f5156ab11dc9%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[Edward K. Ream]

On Tue, May 14, 2019 at 8:46 AM Terry Brown  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

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/CAMF8tS0k%3DTu3hNsYGcAsErcVbxfHVocTcXrHap-UcDungKYvGw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[Terry Brown]

On Tue, 14 May 2019 03:50:46 -0700 (PDT)
"Edward K. Ream"  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

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/20190514084648.65712dd5%40lakeview.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[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

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/2371a83b-2023-4eb4-b55e-825a61ab9a93%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: discuss: Use markdown for Leo's documentation #1147

[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

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/f89ef231-9d6b-43d3-a139-5ef19a7b3aef%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

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

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to leo-editor@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/ef99e34c-9f8a-4c31-9975-53241708db27%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.