- Why is neato the only capable choice for rendering those example files?
neato (and only neato) has special features that allows it to accept pre-defined node layouts (pos attribute) and predefined node + edge layouts (see FAQ | Graphviz and FAQ | Graphviz). It then takes these pos values as given and creates finished graphs - much faster. - How did you know it was the right choice?
Eventually, I really looked at the source. Upon noticing the pos= node attributes, neato -n was the obvious choice. - Can more of that logic/guidance be encoded into the documentation, somehow?
Oddly, this (presence of pos= attributes) is a situation that is reasonable documented - but who gazes at a 1Mb input file?
I like all kinds of documentation styles (see scnorth’s answer below) I also like active documentation (my term, not trademarked) - systems that volunteer answers to questions the user does not know to ask.
Specifically, one thing we might do is enhance the layout engine front-end to- flag language misuse (e.g. rankdir applied to a cluster)
- engine use suggestions (e.g. use neato -n if pos attributes present)
- flag implementation weaknesses/bugs (e.g. ortho splines fail if ports used)
- flag invalid or dubious attribute values (e.g. height=25)
- See Linter for the DOT language & Gvstats - info about your Graphviz files for more info.