Giters

jostylr / literate-programming-lib

The library component of literate-programming

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Cleaner renderings

yrashk opened this issue · comments

commented

I think I've got an idea how to make these LP documents look much better on GitHub or another Markdown viewers. I've looked briefly into what tooling do you use for Markdown, and it appears to me if you'll handle HtmlInline nodes that start with <!-- and end with --> and process the text inside as regular text (as if there was no comment), then we can have beautifully rendered documents without noise and still have the same link syntax.

<!-- [section name]() -->

    Block

What do you think? I am happy to lend a hand if necessary. It is one of my biggest grips right now, having too much noise. It seriously impacts the readability of the document I am writing.

P.S. I worked around this for now by having a build-time sed hack (https://github.com/reactuate/reactuate/blob/ec689745cd912a0a917e70cb4e9bb1a4a3526283/Makefile#L3), and the results are great (see https://github.com/reactuate/reactuate#readme), so it would definitely be interesting to have this as a "native" feature.

commented

I don't mind implementing this though to allow actual comments I would want to have the syntax be <!--+ whatever --> and then I would strip the <!--+ and --> before processing. Is that syntax fine with you?

I realize that the switch syntax is a little noisy, but the point of it is that it does clue the reader when there is a new block in the path. With it being commented out, the blocks would no longer be so obvious as to what they are being called.

Having said that, I am happy to accommodate it anyway. Authors ought to be able organize and present their docs as they see fit.

commented

James, this sounds great, I'm fine with the syntax!

On Tuesday, 19 January 2016, James Taylor notifications@github.com wrote:

I don't mind implementing this though to allow actual comments I would
want to have the syntax be and then I would strip the

before processing. Is that syntax fine with you?

I realize that the switch syntax is a little noisy, but the point of it is
that it does clue the reader when there is a new block in the path. With it
being commented out, the blocks would no longer be so obvious as to what
they are being called.

Having said that, I am happy to accommodate it anyway. Authors ought to be
able organize and present their docs as they see fit.

—
Reply to this email directly or view it on GitHub
#13 (comment)
.

Y.

commented

Done. Install litpro 0.12.0 and see if it works.