Clarify parser and render options in docs

[commonmark]

Clarify parser and render options in docs

[jgm]

Some of the options are render options, others are parsing
options. There are no options that are used in both phases.

Parsing: NORMALIZE, VALIDATE_UTF8, SMART

Rendering: SOURCEPOS, SAFE, HARDBREAKS

This could be clearer from the cmark.3 man page, because
currently the options are under a heading "Rendering."
Originally we only had writer options.

I don't want to store render options in the parse tree,
since the same parsed AST might be rendered in different
ways. But maybe it would make sense to more clearly
distinguish between reader and writer options, either in
cmark, or in the ruby wrapper, or both places.

+++ Garen Torikian [Oct 25 15 13:21 ]:

An interesting issue came up on the [1]Ruby wrapper for libcmark.

It looks like, in order to render a string into a document, and that
document into HTML, you must pass the rendering options twice, like
this:

doc = CommonMarker.render_doc(markdown, [:smart, :hardbreaks])
assert_equal result, doc.to_html([:smart, :hardbreaks])

As far as I can see, there's no way for render_doc to store the render
options on the cmark_node document itself. And there's no way for that
same node to call to_html—it must be handled by a different
cmark_render_html method.

Is that correct? And if so, is that design intentional? I could piece
something together for the Ruby wrapper to work around this, but I
thought it might make sense to apply the change at the C level.

—
Reply to this email directly or [2]view it on GitHub.

References

1. gjtorikian/commonmarker#18
2. #88

[gjtorikian]

That makes sense. I'll change the title to reflect that this might be better fixed by a change in the docs.