92 lines
4 KiB
Markdown
92 lines
4 KiB
Markdown
+++
|
|
date = "2021-05-18"
|
|
draft = false
|
|
path = "/blog/docs-tricks-and-gnus"
|
|
tags = ["site"]
|
|
title = "My Workflow: Docs tricks and GNUs"
|
|
+++
|
|
|
|
##### TL;DR: check out my GNU docs builds at <https://docs.jade.fyi/gnu>
|
|
|
|
They uniquely have:
|
|
* Limited width/better-font-size CSS I wrote
|
|
* One big page for each tool!!
|
|
|
|
[Send me an email](/about) if you want some page that's not in there, I'll see
|
|
what I can do now that I have the tools built.
|
|
|
|
---
|
|
|
|
I have recently adopted the practice of locally building and serving HTML
|
|
documentation for projects I use and work on. I have concluded it's a really good idea:
|
|
|
|
* No way to get distracted while trying to get to the docs
|
|
* They load extremely fast and don't *cough Oracle* show cookie popups
|
|
* You can get better docs offline!
|
|
|
|
To achieve this I've [set up nginx as a user
|
|
unit](https://github.com/lf-/dotfiles/tree/67dea019b1c26811322d4a7e942b509da3464cd2/docs-svc)
|
|
and have stuffed some docs into that web root. Serving docs over http provides
|
|
a few notable advantages over the `file://` protocol: does not lose zoom across
|
|
pages (accessibility problem!) and can read `index.html` files when present.
|
|
|
|
## Rust docs
|
|
|
|
I do the usual routine with `cargo doc` in a project, which will generate docs
|
|
with links between libraries and the exact right versions of dependencies.
|
|
However, there are some ways I've improved my experience:
|
|
|
|
* I wrote [a shim script](https://github.com/lf-/dotfiles/blob/91c41202b42580a94fb3943e87f4b5785bdc9e65/bin/_cargo_doc_open)
|
|
that symlinks docs pages into the web root then opens them in a browser. The
|
|
idea is that it can be set as `BROWSER` for `cargo` using the `[doc].browser`
|
|
Cargo config setting I added, releasing in Rust 1.54 (to release July 29 2021).
|
|
* Use the `--document-private-items` option and maybe even
|
|
`RUSTDOCFLAGS='--document-hidden-items' cargo +nightly doc`
|
|
in order to build documentation with the fun stuff visible, which is really
|
|
good for understanding how things work.
|
|
|
|
## GNU docs
|
|
|
|
Preface: GNU is politically useless, they refuse to kick out their
|
|
misogynist-in-chief despite him not doing anything good or useful for years,
|
|
and their software is not even very good. I absolutely do not endorse them.
|
|
However, their software is unfortunately very popular and available everywhere.
|
|
Also, for instance, LLVM copies the invocation and other details of the GNU
|
|
equivalents to their tools and does not produce separate documentation, in
|
|
general. Irrespective of reason, I very often end up needing to read GNU
|
|
documentation.
|
|
|
|
The existing ways of reading GNU docs are all terrible. `info(1)` is hot
|
|
garbage, with key bindings that nobody will remember. If you choose to look at
|
|
the HTML docs published by the GNU project, they're in about 50 HTML files each
|
|
of which is less than a screenful, making them absolutely impossible to search
|
|
except with like, Google, which also could do way better but doesn't.
|
|
|
|
It's actually possible to build single page docs, you do something like the
|
|
below snippet:
|
|
|
|
```
|
|
$ git clone git://sourceware.org/git/binutils-gdb.git
|
|
$ cd binutils-gdb
|
|
$ mkdir build
|
|
$ cd build
|
|
$ ../configure
|
|
$ make html MAKEINFO=makeinfo MAKEINFOFLAGS='--no-split'
|
|
$ make pdf
|
|
$ find . '(' -name '*.pdf' -or -name '*.html' ')' -exec cp '{}' ~/dev/docs/gnu ';'
|
|
```
|
|
|
|
However, since GNU has development practices stuck in the 90s and no CI, it is
|
|
an extremely frequent occurrence that their source repo won't build or some
|
|
other nonsense, or nobody has tested the texinfo options or similar (all of
|
|
these have happened to me). The point is, this sucks greatly.
|
|
|
|
Also, when you do actually build these docs, they are using 90s web design
|
|
practices that make them unusable on modern machines: there is no significant
|
|
CSS in use, so the lines are about 400 characters long on my machine. I
|
|
normally fix this with Stylus rules but I've written a
|
|
[BeautifulSoup script](https://github.com/lf-/dotfiles/blob/67dea019b1c26811322d4a7e942b509da3464cd2/docs-svc/add_css.py)
|
|
to bake some CSS into the texinfo HTML I am publishing.
|
|
|
|
As of now they are also available publicly at <https://docs.jade.fyi/gnu>.
|
|
|