'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

threaded - newest

taladar@sh.itjust.works on 20 Apr 2024 17:12 next collapse

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

Why? In fact, why would you want to write tooling for Rust in anything other than Rust?

nous@programming.dev on 20 Apr 2024 17:42 collapse

Yeah, I really hate having to install a different language interpreter when working another one. Basically makes me very unlikely to bother with the tool in the first place.

taladar@sh.itjust.works on 20 Apr 2024 21:09 collapse

And not only that, technically everyone who wants to install your code from source would have to install that and installing a specific version of a dynamic language interpreter on an arbitrary platform can be a real pain.

radiant_bloom@lemm.ee on 20 Apr 2024 18:12 next collapse

Great idea ! I don’t personally use Rust, but man pages are so much better than searching the web 😭

ChubakPDP11@programming.dev on 20 Apr 2024 22:06 next collapse

Exactly! I still remember crawling through manpages back in the day. It’s very nice.

kdwarn@programming.dev on 22 Apr 2024 18:20 collapse

Rust documentation online is pretty great (docs.rs/std), and you can also generate it locally by running rustup doc --std.

owsei@programming.dev on 22 Apr 2024 22:11 collapse

The point, I think, is not about fetching the page, but how to navigate it.

I adore using man pages with vim and i would rather have that than a web browser

Turun@feddit.de on 21 Apr 2024 07:51 next collapse

What about cargo doc? With lynx if you demand terminal exclusive usage.

expr@programming.dev on 21 Apr 2024 18:23 next collapse

Briefly glancing through your code there’s a typo on line 37:

outlives_parsed = parse_trail_outlives(bouds.fetch(‘outlives’, nil))

Of course this wouldn’t be an issue had you actually implemented it in Rust since such a thing wouldn’t compile. Not really a good reason to be using ruby for this.

ChubakPDP11@programming.dev on 22 Apr 2024 10:58 collapse

Ever heard of an ‘static analyzer’?

Lmaydev@programming.dev on 22 Apr 2024 12:04 collapse

You clearly haven’t lol

crispy_kilt@feddit.de on 24 Apr 2024 19:22 collapse

Nice. Now reimplement it in Rust

ChubakPDP11@programming.dev on 25 Apr 2024 14:01 collapse

You guys do realize that, Rust, a compiled, statically-typed systems language is not a good suit for scripting right? I understand, when I was a beginner years ago I used Rust for scripting. That was because I was clueless. Right now I am using Rust for what it’s suited for, systems programs. This is a scripting task. I really ask you to learn about the difference between scripting and programming.

leean00@discuss.systems on 25 Apr 2024 14:04 next collapse

@ChubakPDP11 @crispy_kilt hmm sounds like a place I worked where they were writing applications in c, in win32 with no version control because...I dunno they were sadists!!!!

crispy_kilt@feddit.de on 26 Apr 11:32 collapse

That must be why man is written in a scripting language instead of C.

ChubakPDP11@programming.dev on 27 Apr 08:12 collapse

‘man’ is not a single program. Manpages, as I said, are written in ROFF. These are then processed and then paged. I use Most to page them. You can use less or more or any other pager to page them. I am not going to write a pager, I am going to write a script that translates the JSONs of manuals to ROFF.