`RcDom` issues in `html2html` example

[atjn]

I am trying to figure out how to use this parser, and as far as I can tell, the only "getting started" documentation you provide is the html2html example.

html2html uses the markup5ever_rcdom package, which you have decided to make "unofficial" because it is unsafe and incorrect. This means two things:

1. The html2html example doesn't build by default and provides the message "the trait TreeSink is not implemented for RcDom". It took me quite a lot of hair pulling to figure out that you must pin the markup5ever_rcdom to version 0.5.0-unofficial to fix that problem.

2. If the only documentation you have for using this crate is a bad implementation, how am I supposed to use it? If you had some documentation on how I could write my own RcDom that would go a long way, but I don't see any.

[jdm]

Mmm, point 1 is definitely a problem! I'll see if I can fix that.

[nicoburns]

@atjn Not a substitute for proper documention, but we have an implementation here (https://github.com/DioxusLabs/blitz/blob/main/packages/blitz-html/src/html_sink.rs) which you could use as a second reference. Although our implementation has been less reliable (sometimes panics) since the latest HTML5ever version switched to using interior mutability, and I haven't had chance to track down why yet.

[Calandiel]

I think the second point @atjn mentions is still a p big issue. All of the current examples rely on a crate that itself says is a bad implementation. Additionally, there's no further documentation in the docs of the crate.

This leaves new users with two conjectures as to how to continue:

• they could assume there's some intended RcDom implementation somewhere that isn't linked anywhere
• they could assume they're supposed to implement their own RcDom themselves

Both of these however are major pain points for anyone who isn't already regularly using the library. As per what @nicoburns wrote, custom implementations are less reliable, as library users naturally aren't likely to stay up to date with how the internal invariants and use patterns of the library evolve, especially given the very sparse documentation as to who those use patterns and invariants of a sound implementation would be. New users also (obviously, by virtue of being new users) don't know of other libraries in a wider ecosystem that could hypothetically be used, and neither the documentation, nor the examples suggest any leads to follow.

Imho, there really needs to be at least a single example that's "production ready" enough for it to be a good idea to suggest people to use, and an unsupported crate that calls itself untested and only meant for automated tests of another crate really isn't what should be used in examples.