Re: mdoc.7 tweaks

[Ingo Schwarze <schwarze@usta.de>]

Hi Jason,

first, many thanks for ploughing through this really large manual!

Jason McIntyre wrote on Mon, Aug 02, 2010 at 08:00:05PM +0100:

> this page makes my head hurt ;(

We hope to change that ASAP...
It is already a better manual than we had before,
and it is supposed to become a good manual.  ;-)

> i cannot do a diff for too many things here, so this diff:

Right, let's try to work with diffs of manageable size,
not mixing too many unrelated things.

> *) corrects a few obvious mistakes
> *) adopts some of the changes i proposed for man(7)
> *) tries to cut down just a little on the awful tendency to stick
>    a hyphen between two words.

Everything not related to .Sx / .Sy is ok schwarze@.

> *) uses Sy for macros instead of Sx. we could use something else but
>    not, please, Sx.

Hmm, i'm not sure.
Using exactly Sx (and not anything else) has a point.
On http://mdocml.bsd.lv/mdoc.7.html , you can easily navigate
the whole manual using the macro hyperlinks.
I know that is irrelevant for man(1), and for terminal output
in general, but it may still be considered useful.

Of course, we can decide against hyperlinking, but do we really
want to make that decision in a hurry, right now, after release
soft lock, and while Kristaps is not around?  When the choice of
what to use instead is not even obvious?

> *) uses Sx for section names.

I don't think i agree with that item.
Let's take the first example from the top of the file:

  >  The first section (sections are denoted by
  > -.Sx \&Sh )
  > -must be the NAME section, consisting of at least one
  > -.Sx \&Nm
  > +.Sy \&Sh )
  > +must be the
  > +.Sx NAME
  > +section, consisting of at least one
  > +.Sy \&Nm
  >  followed by
  > -.Sx \&Nd .
  > +.Sy \&Nd .
  >  .Pp

What is the hyperlink from NAME supposed to point to?
Logically, it should point to the explanation of the NAME section,
which is here:

  The sections in an
  .Nm
  document are conventionally ordered as they appear above.
  Sections should be composed as follows:
  .Bl -ohang -offset Ds
  .It Sx NAME
  The name(s) and a one line description of the documented material.

But it won't point there, because the ".It NAME" is not an ".Ss NAME".
And even if it were, the .Sx reference would be ambiguous, because
mdoc(7) of course has its proper ".Sh NAME" section, which comes
before anything else.  That's where the hyperlink will point - which
makes very little sense, because we are not talking about the NAME
section of the mdoc(7) manual, but about the syntax and semantics
of NAME sections in general.

It gets even worse.  Look here:

  > +.It Sx EXIT STATUS
  > +This section documents the
  > +command exit status for section 1, 6, and 8 utilities.

This is a dangling, invalid hyperlink.
The mdoc(7) manual has no EXIT STATUS section,
so we cannot point to it.

On the other hand, there were a few valid internal references
which you have mangled.  I think the following are correct
as they stand and shouldn't be changed:

   macro is a
  -.Sx Block full-implicit
  +.Sy Block full-implicit
   macro only when invoked as the first macro
   in a

   .Ss Block partial-implicit
   Like block full-implicit, but with single-line scope closed by
  -.Sx Reserved Characters
  +.Sy Reserved Characters
   or end of line.

  @@ -1477,7 +1478,7 @@
   which signifies the current manual revision date dictated by
   .Xr cvs 1 ,
   or instead a valid canonical date as specified by
  -.Sx Dates .
  +.Sy Dates .
   If a date does not conform or is empty, the current date is used.
   .Pp
   Examples:

   macro uses
  -.Sx Block full-implicit
  +.Sy Block full-implicit
   semantics when invoked as the first macro on an input line in the
   .Em SYNOPSIS
   section; otherwise, it uses ordinary
  -.Sx In-line
  +.Sy In-line
   semantics.

  @@ -2627,15 +2634,15 @@
   .Em SYNOPSIS
   section, in which case a variable name is also specified.
   Note that it accepts
  -.Sx Block partial-implicit
  +.Sy Block partial-implicit
   syntax when invoked as the first macro in the
   .Em SYNOPSIS
   section, else it accepts ordinary
  -.Sx In-line
  +.Sy In-line
   syntax.

   .It
   groff behaves irregularly when specifying
   .Sq \ef
  -.Sx Text Decoration
  +.Sy Text Decoration
   within line-macro scopes.
   mandoc follows a consistent system.

> one issue: formatting the page with groff:
> 
> 	mdoc.7:773: warning: can't find special character `lb'
> 	mdoc.7:773: warning: can't find special character `rb'
> 
> and the offending text:
> 
> 	\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb

That seems easy; i guess it's a typo, and i would just change lb to lB
and rb to rB, like this:

  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB


> anyway, this is a start.

Yes, indeed, and thanks again for attacking this.

Thus, i don't really like asking the following question:

Are you really sure we should switch from .Sx to .Sy right now?

If yes, we need to get it right at once, including choosing the
macro we really want, but i do not want to digress into .Sy vs. .Ic
vs. whatever bikeshedding as long as we do not even agree that we
need to get rid of .Sx at all.

If no, will you pull the .Sx/.Sy parts out of the diff for now,
or shall i do it?

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv