On 2013-05-20, at 07:52 , Jeaye wrote: > On 05/19/2013 02:09 PM, Lucian Branescu wrote: >> I don't see it either, fwiw. >> > Ok, so I'm not crazy. I was wondering the exact same thing. Can we get the > original message sent to the list, Masklinn?
Yesterday as I was trying to provide more info/background for an answer to the list, I encountered an issue which I think is going to hinder lots of people trying out rust: using the documentation is an exercise in frustration. To expand, I hit 2 main pain points: 1. I wanted to see all the built-in ways to use Option<T> (aside from simply pattern-matching on None and Some), for this I went to the corresponding doc page http://static.rust-lang.org/doc/0.6/core/option.html. Although probably not the worst by a long shot, this page still demonstrates a number of issues: - None of the methods provides examples showing off their purpose and how they can improve code. For some of them, it makes understanding their power and purpose much harder (e.g. Option.each) especially for people coming from languages without these facilities and thus not actively looking for them - The only examples could actually be simpler if replaced by using one of Option's methods, e.g. I believe the second example let unwrapped_msg = match msg { Some(m) => m, None => ~"default message" }; could have been written: let unwrapped_msg = msg.get_or_default(~"default message"); and would demonstrate the value of the corresponding method (this could of also be used as a teaching device by first showing "raw" examples then showing how the code can be simplified/improved using the module's toolbox, but it's not the case here) (and the example is incorrect in the first place, the compiler rejects `Some(ref m) => io::println(m)`, this should be `Some(ref m) => io::println(*m)`) - The uniform color scheme, font and indentation make it hard to notice e.g. admonitions (several methods will fail on a None, have a note indicating it, but the node melds into the rest of the document) - None of the method is hyperlinked from the module's top (or some sort of sidebar) and it's impossible to get a link to them short of inspecting the page's HTML source Now part of these issues are tooling and parts are copywriting, most are easily fixable per-documentation the issue is that they're exist across all of the documentation. But there's a bigger issue: 2. Missing cross-section hyperlinks and references. There I was looking for the various formats available in fmt!. fmt! is mentioned and used extensively in the Rust tutorial[0] and is also listed as an example macro in the reference manual[1]. Yet *not one* of the mentions is hyperlinked to any specification or documentation for it. The core library[2] nor the standard library[3] indexes don't list anything having to do with fmt! either. And to add insult to injury, the first mention of fmt! in the tutorial is linked to the documentation for C++'s printf[4] but *not* to any fmt! related documentation. I ended up finding extfmt[5] (after quite a bit of googling), but looking for it wasn't exactly fun. As I mentioned part of it is basic copywriting (and putting the effort in), but I think part of it is also tooling: nobody is going to bother looking up the exact url to the spec/documentation of fmt! (if it even exists, does it?). Having "short syntaxes" for object-aware hyperlinks (e.g. being able to easily link to the definition/documentation of a macro, module, function, type or method) in the way of Sphinx domains[6] and extensively using these would solve the issue at least in part, but I don't know if Pandoc can be extended in such a way, or if the Rust team would be willing to switch to Sphinx[8]. [0] http://static.rust-lang.org/doc/tutorial.html [1] http://static.rust-lang.org/doc/rust.html#syntax-extensions [2] http://static.rust-lang.org/doc/core/index.html [3] http://static.rust-lang.org/doc/std/index.html [4] http://static.rust-lang.org/doc/tutorial.html#syntax-extensions [5] http://static.rust-lang.org/doc/core/extfmt.html [6] http://sphinx-doc.org/latest/domains.html there is no Rust domain at the moment, but a custom one can be written[7] [7] http://sphinx-doc.org/latest/ext/appapi.html#domain-api https://bitbucket.org/birkenfeld/sphinx-contrib [8] that would give the documentation code-coloration for free as well, since there is already a Rust lexer in Pygments: http://pygments.org/demo/81135/, though of course Rust support can also be added to Pandoc. _______________________________________________ Rust-dev mailing list [email protected] https://mail.mozilla.org/listinfo/rust-dev
