search

Nemo157 / maud-pulldown-cmark

An adapter to allow rendering strings as markdown inside a maud macro using pulldown-cmark efficiently.
Apache License 2.0
5 stars 2 forks source link

Complete examples, and valid links #1

Closed critiqjo closed 8 years ago

critiqjo commented 8 years ago

I had a hard time getting the example to work. Tell me what you think; let's get the examples right...

Nemo157 commented 8 years ago

Hmm, it would be nice to have the examples actually compiled and checked as part of the build, I notice I missed changing it when I removed the need to wrap events in a closure. They are duplicated in the source as doc-tests which do get checked, but for brevity those don't display the fully compiling example and it's quite hard to read the example in the source... I'll merge this but take a look at moving the examples into examples/ so cargo test will check them.

What was the issue with the links? Any markdown parser should be picking them up from the definition below (https://github.com/Nemo157/maud-pulldown-cmark/pull/1/files#diff-04c6e90faac2675aa89e2176d2eec7d8R11)

critiqjo commented 8 years ago

What was the issue with the links? Any markdown parser should be picking them up from ...

Ahh! I didn't know... I'll undo it and rebase... I slightly improved the wording (hopefully) too...

Nemo157 commented 8 years ago

I slightly improved the wording (hopefully) too

Yep, that wording sounds better to me too :smile:.

Nemo157 commented 8 years ago

Thanks! (It's nice to see someone else has actually tried using this at all :grinning:)

critiqjo commented 8 years ago

It's nice to see someone else has actually tried using this at all

I just started (an attempt at) rewriting rustdoc, and the best candidate for replacing hoedown is this, according to my research! So, keep up the good work! :+1:

critiqjo commented 8 years ago

I want to open an issue for a feature request! Please enable it (I don't see an alternative in the original repo)...

Also, the fork of rustdoc to replace hoedown is already working!!! :smile: I tested it for building docs for this repo. Please take a look at it if you've time... The main limitation is the lack of option to add attributes in various html tags. I have a simple design in mind to accomplish that...

Nemo157 commented 8 years ago

Enabled issues, not sure why I disabled them in the first place...

critiqjo commented 8 years ago

I just noticed that the only use of maud in this library is for escaping. I thought maud provided some high level html builder API, other than the macros.

I did a little more research, and the conclusion I reached is for this library to ditch maud! :smile: (and rename!)

Jokes aside, the ecosystem really needs a proper html builder, something similar to xml-rs. And a bridge between pulldown-cmark and that builder -- a (customizable) map from pcmark-events to htmlbuilder-events.

Unrelated: I don't understand the need for HREF_SAFE. Is it intended for url-encoding + html-encoding? If it's just for escaping attribute values, then escaping the characters shown here would suffice, right?

critiqjo commented 8 years ago

And about the "simple idea" I had: it was too short-sighted; the html-builder+bridge is the long-sighted version!

Nemo157 commented 8 years ago

I initially wrote this as I was using maud to render https://git.nemo157.com and wanted to integrate pulldown-cmark for rendering the readmes. Yes, the only thing it uses from maud is the escaping, the aim was to provide the RenderOnce trait impl for pulldown-cmark.

A proper html builder sounds interesting, that would definitely help me elsewhere in the cases where maud macros are too limiting so I'm failing back to just writing text to the writer directly. If we had that then I guess maud could provide impl<T: IntoIterator<HtmlEvent>> RenderOnce for T and a pcmark-events -> htmlbuilder-events adapter wouldn't have to depend on maud at all.

I can't remember if I was following a spec for HREF_SAFE, I've opened #3 to take another look at it and make sure it matches the spec (and probably make it easier to read, trying to work out what characters are disallowed from that array is really difficult :frowning:).

Nemo157 commented 8 years ago

I took a bit of a look at what exists on crates.io around html builders. There's:

Are you interested in collaborating on this at all? I'm tempted to throw together a basic html-event crate and some test branches of this and maud using it to see what it would look like.

critiqjo commented 8 years ago

Isn't htmlstream a parser, and not a builder? I think it would be better to just fork xml-rs, strip off the reader and parts of writer to simplify it for html5.

@nagisa Sorry for the sudden question! Are you currently working on marksman? Would you like to discuss the design you have in mind? Is it similar to xml-rs?

Nemo157 commented 8 years ago

Isn't htmlstream a parser, and not a builder?

Yep, but the parser should output the same events you send into the builder, so you could get an iterator of events from htmlstream, do some sort of map on them then send them into some html::Writer to convert back into text. Say for something like sanitisation, you might have some html docs you want to inline so you need to parse them, sanitise them, then output them.

critiqjo commented 8 years ago

Ahh! But having an HtmlTag event (as per htmlstream) sent to a Writer is not useful in our case, since we need to send opening and closing events separately.

And furthermore, I'd like to:

Nemo157 commented 8 years ago

@critiqjo If you want to take a look I threw together a very basic html event library + writer and added a branch that uses those instead of maud.

nagisa commented 8 years ago

Are you currently working on marksman?

I was intending to do it, but got distracted with rustc and ended up never doing it. I’m not sure if I’ll ever get back to it.

Would you like to discuss the design you have in mind? Is it similar to xml-rs?

I don’t know what xml-rs’ approach is; I was intending to borrow a considerable amount of ideas from blaze.

critiqjo commented 8 years ago

@nagisa So syntax-wise it is very similar to horrorshow. Unfortunately, that's not what we are looking for. We need an event-based open-tag/close-tag builder so that it can operate directly on pulldown-cmark events (for md->html conversion). Well, thanks for the reply...

critiqjo commented 8 years ago

and added a branch that uses those instead of maud.

I think you should create a new repo for it, since you are ditching "maud" :smile:

(Why not call the new repo "cmark-html"?)