manpages is mdoc(7)

[Jan Stary]

On Apr 01 09:24:22, keybounce at gmail.com wrote:
> 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.

Whether you mean the man(7) macros or the mdoc(7) macros,
they have been around and clearly documented for decades,
on each and every UNIX system. To quote http://man.openbsd.org/mdoc

  The mdoc language first appeared as a troff macro package in 4.4BSD.
  It was later significantly updated by Werner Lemberg and Ruslan Ermilov
  in groff-1.17. 

(Seriously, are you pretending to not know that?)

> 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.

That's the impression I got so far in the reactions.

So let's use the horrendous docbook-xsl to produce
low-level roff of abysmal quality - it still looks close 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.

The new language is as old as 4.4BSD,
and the documentation for it is exactly as old.

> 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".

Could you please elaborate on each of those points, specifically?
How is mdoc(7) "site dependent"? What "rules for scrolling"? etc.
How does it "leak privacy data"? (And what what "privacy data"
are in the manpages?) etc

> Yes, I'm bitter about that.

Apparently.

> 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.

That's a strawman attack. mdoc(7) doesn't do _any_ of that.
On the contrary, it has annotations for "this is an optional argument",
"this is a variable name" etc - precisely the things you need to say
in a manpage for a piece of software.

> Man page rules allowed specifying the important stuff -- standard section headers, command name, etc. The language was badly documented,

No it wasn't, and isn't.

> 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.

What's that nine thousand files doing
in my OSX's /usr/share/man then?

> 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.

That's why I suggest to use mdoc(7), as opposed to man(7),
to be used for the manpages.

> Use something that is usable if displayed raw,
> that has conversions into other formats (such as -man),

>From the mdoc(7) source, the following are easily generated
using either gorff or mandoc:

ascii
html
man
markdown
pdf
ps

> and doesn't fall into the "everything behaves differently" trap.

I don't know what you mean by that,
and how mdoc(7) "falls into that trap".

> An ascii-based rewrite sounds like it fits that. 

mdoc(7) does not fit that by definition, if you want
something that is usable if displayed raw,
which rules out any kind of markup.

	Jan