jostylr / literate-programming-lib

The library component of literate-programming
MIT License
36 stars 3 forks source link

Cleaner renderings #13

Closed yrashk closed 8 years ago

yrashk commented 8 years ago

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.

jostylr commented 8 years ago

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.

yrashk commented 8 years ago

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 https://github.com/jostylr/literate-programming-lib/issues/13#issuecomment-172834426 .

Y.

jostylr commented 8 years ago

Done. Install litpro 0.12.0 and see if it works.