I, for one, do not like text browsers like lynx or elinks and think we can do better with "real" text files.
Therefore my question: Would it be possible to add a backend to rustdoc to compile to text files, e.g. Markdown or similar, that can easily be used with tools like less or vim?
Coming from C originally, I was used to having the libc documentation available as manpages. So if a json backend became available, I think taking that short step from json to groff/man would help satisfy a lot of the other greybeards out there.
Honestly, pure plain (non-hyper-) text seems horribly difficult to peruse when we’re talking about a large hierarchically structured API. Indeed so do manpages with their lack of any concept of hierarchy whatsoever even if they’re fine for C-like flat namespaces.
While I definitely see the logic in what you're saying, I think it's important to remember that if Rust makes it into the Linux kernel (which is a part of the beginning of this discussion) then it's good to account for providing documentation in very minimal environments that might consist of just the kernel, busybox and some custom utilities, without a web browser in sight. In such an environment having plain text and manpages is a plus, even if it's somewhat hard to navigate.
The point is options. Options are good.
And if plain text of groff/man doesn't seem useful for the reasons outlined, consider GNU info pages, which do allow hyperlinking and hierarchical menus. A json backend for rustdoc would make it relatively trivial to convert to arbitrary formats, and html should not be viewed as the only option. I could argue that it's not necessarily even the best option.
No, its feature gated on nightly, so you can use it now (see here for how nightly features work) with cargo +nightly rustdoc -- -Z unstable-options --output-format json
But if you want to write a roff/texinfo generator that takes json, I'd sugest you start now, before it stabilizes, so if any problem with the format come up, you can report them and we can change them.
Do you know what sort of documentation you would be looking for?
There standard library has a fair amount of documentation and even the API docs for core alone has over 18,000 pages (functions, modules, macros, structs, traits, etc.) taking up about 160 MB. Whether that would be acceptable or not is up to the kernel developers.
$ cd $(rustup doc --core --path)
$ find -iname '*.html' | wc --lines
18325
$ du --total --human-readable $(find -iname '*.html')
...
157M total
I'm genuinely curious, is it common for people to be writing and compiling code (either C or, hypothetically, Rust) in such a constrained environment?
HTML doc is great for when you want to read and peruse documentation. Most these days can and do have an environ that can present HTML.
But when writing, coding, working. I assume there a many that prefer their terminal for grepping or what not. Not having to take fingers off keyboard, switching interfaces and going reaching for the mouse. I assume there are many that like to be able to do "man getppid" for example to read how to use a c function?
My workaround for rust is from my terminal I type "rustup doc std::env::arg" to bring up the "manual page" in my browser. Because text browsers suck, I then am into the browser to read instead of the terminal I was in, having to point and click to copy paste etc, then back to terminal window to paste in to code I was typing. I assume many developers also use "screen" or "tmux" and just like to keep it simple.
But then again I am an construction worker, physical labor by trade, so my programming advice should be taken with a grain of salt.
Exactly this. And with the JSON backend, I could think of something like a vim
binding that opens a vim/tmux split with the appropriate documentation for the
keyword under the cursor, even! I know that this functionality is given with the
language server project, but, at least right now, running a language server is
too heavy for me.
It used to be more common, and you bring up a fair point that it's not hugely likely anymore.
However, there's almost always another scenario that we're not thinking of, so let me give one more. We're close to seeing consumer market RiscV general purpose computers, with the BeagleV coming out for general consumption later this year. And while you can run a graphical environment on RiscV now, as of now the major Javascript environments are not portable to it, limiting your choice of web browsers to text mode and, say, Dillo.
Hopefully that situation will improve. But I'm still grateful for options.