vmem.9: align lists + tag spdx

[concussious]

Align lists to polish the presentation of the document. Tested with MANWIDTH=80 and MANWIDTH=59. We loose a line at 80 and gain a line at 59.

Cc @mhorne, @gperciva

[gperciva]

I have no major objection to this.

Some slight concern over whether "qcache_max" will be updated in the future -- suppose that 15 years from now, somebody adds a longer argument to vmem_alloc(). Will they notice that all the other .Bl ... -width tags should also be updated? In my experience with multi-decade, multi-user documentation projects, it's easy for people to miss such details. (Probably doubly-so for kernel developers!)

One option would be to add a comment above each .Bl .. -width line to remind people to update the widths. But even that's no foolproof -- if somebody adds a new vm_alloc() argument at the end of the list on line 250, would they notice a comment on line 234?

However, I tried writing a proof-of-concept python script to detect such instances, and it looks like it works. So if there's a desire to do so, one could automatically discover all instances of .It exceeding with -width.

(That said, there's a lot of such instances. Out of the 40 files in bin/*/*[1-9], there's 43 such places. If we ignore list items longer than 12 chars, then there's "only" 27 problems. Ignoring contrib code, there's over 4000 man pages in -CURRENT; if bin/ is representative, then that's around 2700 -width values that would need changing. Not including the "align all widths on a page" question, which I haven't added to the script yet.)

Anyway, as far as I'm concerned, go ahead and merge this. :)

[concussious]

You're definitely more experienced and educated than me and really I hope to learn from you, but I don't agree with this. Doc mistakes come from not looking at the doc and changing it. Doc is for humans to read. The flow and presentation of the document is important, and affects it's functionality, and can't be obtained if you don't read the whole doc while you're editing it. Formatting it nicely does not introduce maintenence concerns, it's paying technical debt introduced from people treating it like it's a program instead of doc. Anyone who is looking at the doc while they're editing it will definitely notice.

[gperciva]

I'm not saying that presentation is meaningless; I'm just much more pessimistic about people looking at the docs when they edit it.

But that's beside the point of whether a script would be useful.

Let's put it this way: suppose that it takes you 5 minutes on average to align the lists on each man page. That's 5 minutes to look the page, decide on the appropriate indentation(s), make any edits, do a git commit, and create a new PR.

Given 4000 man pages, that's 333 hours of effort. (If you think that 5 minutes per file is too short, then it's even more hours!)

By contrast, suppose that we spent 5 hours working on a script which would align the lists automatically. Huge time saving! (And if anybody edited a man page without regard for the alignment, no worries: just run the script again to fix it.)

I'm happy to work on the python side of things. Where my interest wanes is:

1. testing the script -- I'm sure that there's some .It lines that it doesn't parse correctly. (I made sure that it works on bin/* but not other files.)
2. deciding on the typography. For example, if an .It has 40 chars, that's obviously too long to bother aligning. But if it has 5 chars, yeah, let's align it. Where's the dividing line? Does it matter whether the list is nested (or offset)? etc.