'Rust manpages' -> UNIX-style manpages for Rust (still WIP, just letting you know of the progress) --- Thoughts? (pastebin.com)
from ChubakPDP11@programming.dev to rust@programming.dev on 20 Apr 2024 16:42
https://programming.dev/post/13027923

The URL leads to a pastebin for a Ruby script I have been writing for the past 2-3 days. It’s called mk_rustman.rb on my system. They will turn JSON files for Rust docs into UNIX manpages, with Groff ROFF macros for man (groff_man).

The script may be rewritten, or I may change the language. I wish to use:

1- An interpreted language; 2- A dynamically typed language

I will choose a fast language, because the JSON file for Core is very large. Ruby has not been very fast so far, but there’s an alternative implementation of Ruby I may try. Another candidate is F#. Does anyone know a dynamic but functional scripting language? Not a giant programing language like OCaml, something small that is functional.

Anyways.

Let me explain the JSON files first.

If you install rust-doc on your system:

sudo apt-get install rust-doc

And:

exa /usr/share/doc/rust/json
or
ls /usr/share/doc/rust/json

You shall see these:

alloc.json.gz  core.json.gz  proc_macro.json.gz  std.json.gz  test.json.gz

All these JSON files have an ‘index’ object, this ‘index’ object is made up of sub-objects indexed by their ID:

zcat /usr/share/doc/rust/json/std.json.gz | jq '.index' | head -n 48

{
  "a:1:8659:4267-0:638:4291": {
    "id": "a:1:8659:4267-0:638:4291",
    "crate_id": 0,
    "name": null,
    "span": null,
    "visibility": "default",
    "docs": null,
    "links": {},
    "attrs": [],
    "deprecation": null,
    "inner": {
      "impl": {
        "is_unsafe": false,
        "generics": {
          "params": [],
          "where_predicates": []
        },
        "provided_trait_methods": [],
        "trait": {
          "name": "UnwindSafe",
          "id": "1:8659:4267",
          "args": {
            "angle_bracketed": {
              "args": [],
              "bindings": []
            }
          }
        },
        "for": {
          "resolved_path": {
            "name": "BacktraceFrame",
            "id": "0:638:4291",
            "args": {
              "angle_bracketed": {
                "args": [],
                "bindings": []
              }
            }
          }
        },
        "items": [],
        "negative": false,
        "synthetic": true,
        "blanket_impl": null
      }
    }
  },

This is the first object in the list.

The ‘meat’ of an object is the ‘inner’ field. Inner can be one of:

zcat /usr/share/doc/rust/json/std.json.gz | jq '.. | objects | .inner // empty | keys[]' | sort | uniq 

=>

"assoc_const"
"assoc_type"
"constant"
"enum"
"extern_crate"
"function"
"impl"
"import"
"macro"
"module"
"primitive"
"struct"
"struct_field"
"trait"
"type_alias"
"variant"

I have parsers for most of these, but not all .And the parsers are incomplete.

These all have common fields. The most important field is the type. Another one is generics field. These two occur a lot.

I wanna turn this into perhaps, a larger project. I made a ChatGPT model to teach me PostScript. I wanna write a documentation language, similar to POD, and I wanna write several targets for it. Then, the Rust Manpaes could use this language.

---

I know that there MIGHT be some people who may not be aware of what UNIX manpages are, maybe they use Window, dunno. So I wanna explain manpages, and why I am adamant to convert Rust documentation to them.

Basically, the story is:

MacIlroy, Thompson and Ritchie decided that, instead of sucking the dicks of higher-ups at Bell labs to buy them a shiny PDP-11 to expand their shiny new OS, UNIX, with, they could promise them some sort of ‘clerical use’ for it. Using computers for clerical use was not very common back then. In fact, it was only a few years after ASCII was introduced. Story goes, 20-25 years prior, Von Neumann himself slaughtered an undergrad student who had dared to write what is today’s equivalent of a ‘charset encoding’ for one of them giant compooters. This was modern times and people were slowly realizing that computers have other uses than launching rockets at the Vietnamese rice field workers. But even a mini-computer was an investment.

So they conceived ROFF, a documentation system which was adapted by the patent office gals. These gals would get their asses slapped, their boobies touched (as was the custom of the time) and write patents on their terminals with ROFF.

Source of this story:

man 7 roff

The same documentation system was used when Bell Labs decided to sell UNIX to people. And today, we have GNU Roff to take its place. There’s also the Hoodlum Toolchest or whatever it’s called, and BSD’s Roff (which happens to be identical to Bedlam or whatever toolchest).

Groff has a man macro package which makes it extremely easy to write manpages with.

Manpages have ‘sections’, which are numbered. They could also have letters in them. On Linux, the section for utilities like ls and sh and man itself is 1, then syscalls are 2, library is 3 etc:

These two are equivalent:

man ls
man 1 ls

But these two are not:

man getopt
man 3 getopt

Most languages have manpages.

man 3o List # Ocaml List manpage
man 3perl Pod::Usage # Perl Pod::Usage manpage

In both these instances, you can omit ‘3o’ and ‘3perl’. On Linux, when man gets a conflict, it looks uses the default order ,which the user may set.

Man pages are saved at /usr/share/man and /usr/local/share/man.

You can use apropos to search man pages:

apropos pid

You can view all the pages in a section with:

apropos -s [section] -k .
# line
apropos -s 3o -k .

Why do I want Rust Manpages?

Simply put, manpages are simpler to navigate, at least for me, than a webpge. Convenience is key here.

Some people like to launch Firefox or Chrome or whatever, and search their shit on google. I don’t like that. I consider myself an intermediate practicioner of programming. The last time I used Stack Overflow was several months ago. I don’t need to see how a function is used to know how to use it. I can just look at the documentation. So I think that is why I find manpages necessary.

I may make them for Go too. And Nim! Python needs them too. Although Python is like 10 years older than Go and Rust (12 yo Rust, 14 yo Go) so there might be manpages for Python.

Tell me what you think? Do you like this? Has someone already done this?

Thanks.

#rust