manpages is mdoc(7)

[Michael]

My ... (if 2 bits is 25 cents, then 0.2 bits is 2.5 cents, ... ok, call it inflation) 0.2 bits on this subject:

In the past, I attempted to write stuff with man page macros. I could not find any actual docs on the macros or how to use them.

I found that there was no consistent style or rules from reverse engineering the shipped system man pages.

After a lot of attempts to decipher rules, find what seemed to be non-existent docs, etc., I came away with the following:

As long as it looked close enough, that was good enough.

If you are going to talk about re-writing something in a new language, it isn't enough to say that it is documented; point out the docs.

If you are going to say that "Oh, this language is better because it makes semantic separation, and you can make it look appropriate yourself", make sure you are not falling into the stupidity of the HTML to CSS trap -- going from "Here's a simple, uniform, consistent way to say bold or underline" to "Here's a site dependent way to format, that will differ from site to site, that isn't even easy for an end user to adjust or change, that tries to make your monitor look like the dev's monitor even if the two monitors are completely different in all aspects, that changes the rules for scrolling, for letting people see stuff, that leaks privacy data, that while it can say "this is a paragraph" or "this is a link" or "this is someone's name" or "this is a video", etc., in reality everyone wants to declare different things in different ways, and the end user only gets one override style sheet that if used will replace everything else by everyone making it completely useless in the end".

Yes, I'm bitter about that.

Seriously: Being able to say "This is to be emphasized" or "This is to be stressed" or "This is to be ignored" is not really much different than "This is to be bold" or "this is to be italic" or "this is to be strikethrough"; or having a display translate strikethrough into greyed-out because it can't do strikethrough.

But being able to arbitrarily declare "this is a new class of thing", and then require a rule for how to display thing before it displays correctly because lacking that CSS it now displays wrong?

Man page rules allowed specifying the important stuff -- standard section headers, command name, etc. The language was badly documented, and not really consistently templated. Gnu switched to a "info" language. Apple just made PDF's from their own internal stuff and didn't even bother with man pages. Etc.

> Do you also look at generated HTML in your browser and complain about all the hacks and workarounds that are necessary for certain browsers?

I've had to go into source mode / firebug / Stylish / other tools and *FIX* things to work with my browser.
So yes.

===

The TL;DR: Based on what has happened historically, it really does look like the -man macros for roff don't provide enough function and are too hard to use for what is provided. There's 14 competing standards, and a 15th won't do better (ref XKCD). Use something that is usable if displayed raw, that has conversions into other formats (such as -man), and doesn't fall into the "everything behaves differently" trap.

An ascii-based rewrite sounds like it fits that. 
A UTF-based rewrite might help, but it also opens up the horrors of a page that cannot be displayed on an ascii screen at all using nothing but foreign alphabet stuff.
And an extended ascii rewrite (providing standard accents, tilde-n, etc) might be a "good enough" compromise.

Heck, programming languages went through the sequence of "very limited" to "can do anything and everything" to "no gotos, this set of control flows". Maybe we should be doing something similar with formatting rules by now?