4 ms·
TBH it's really hard to care about the "I need my docs to render in a terminal" use case.
by staticassertion 5y ago
TBH it's really hard to care about the "I need my docs to render in a terminal" use case.
- edflsafoiewq 5y agoWhat about "programmatic access to docs"? HTML pages aren't pipeable.
- staticassertion 5y agoHonestly, I hadn't considered that (and I've upvoted) because I just use "search" in the rust docs. But I can see some value in grep'ability of docs, even if for me it has never really come up. I suppose it would be nice if rust's docs supported a full text search.
- spoiler 5y agoWhat use case is that? FWIW, the docs are already generated programmatically in the first place, so you could access them with a similar approach (not sure how difficult that is, so maybe it's unrealistic advice). Also there's a tool (forgot the name now) that can render them in the terminal similar to manpages.
- arghwhat 5y agoIf there is a terminal rendition tool, please share. Last I checked all efforts where abandoned, either due to too tight integration to rustdoc or due to bike shedding… Note that there is no problem with the web version being available, it’s useful at times.
- bogeholm 5y agoSure they are, `cat x.html | rg -A 5 -B 5 ‘some string’`
- arghwhat 5y agoIt’s really hard to care about people who consider waiting for a webpage to build, a browser to load and a search to be typed as an acceptable solution to documentation access.
- alexvoda 5y agoThat argument doesn't work both ways. One group has far more stringent requirements than the other as evidenced by your use of the word "acceptable". Web documentation is easy to produce and is acceptable to many. All other kinds of documentation can also be converted into web documentation, therefore you do not have to spend extra effort for it. Terminal documentation is more difficult due to the limitations of displaying things in the terminal, therefore it requires more effort.
- arghwhat 5y agoI’m sorry, what? I certainly agree that those who prefer terminals are a subset of developers - despite this missing the point of terminal-friendly documentation also means generally reusable and integration friendly, unlike a full web application - but terminal documentation is objectively orders of magnitude less work than writing web app for showing documentation. Terminal documentation just means plan text. You print it, that’s it. Making it pretty involves indents and line wrapping. Any source formatting is just ignored.
- throwamon 5y agoWho said it has to be a "full web application"? Where are the orders of magnitude more work in parsing text and saving it as HTML files?
- arghwhat 5y agorustdoc, the tool being discussed, generates a full, interactive web application as documentation. Plus, while one can dump plain text to HTML files it's still easier to just print the text.
- staticassertion 5y agoIf it were orders of magnitude less work to get the same results in a terminal that you get in a browser we wouldn't have browsers.