[bug #58653] want the short mdoc(7) page that Linux man-pages used to ship

[G. Branden Robinson]

Follow-up Comment #9, bug #58653 (project groff):

[comment #1 comment #1:]
> In general, it is an extremely bad idea to have a short and a long version
of the same manual page.  All that does is making it likely that both get out
of sync and eventually neither are correct.  One reference manual is enough.

For groff_man(7), I cut this knot through yet another layer of indirection. 
We now have an m4 document, groff_man.7.man.in, that produces (after another
layer of sed-foolery managed by make(1)) groff_man(7) and groff_man_style(7).

It's WAY easier to maintain than the duplicated and occasionally triplicated
material that is our ms(7) documentation, where we have a big chunk of
groff.texi, ms.ms, and groff_ms(7).

But I'm getting closer to being able to kill off the Texinfo portion, and the
differences in terseness between ms.ms and groff_ms(7) are already clear.


> Ingo's approach is admirable but I don't think it's the norm, certainly not
for me and others I've worked with.

Maybe I've become a bit more like Ingo.  I didn't know jack about me(7) a few
months ago, and meintro.me didn't help me to acquire it.  I now feel I have a
fairly strong command of it.

What did the trick?

Revising meref.me down to the last jot and tittle, almost literally.

So I guess for me, the way I learn a system is not with separate basic and
advanced user guides, nor with counterpart tutorials and references, nor even
a single comprehensive master document, though the latter comes closest.

No, I have to take that master document and strike it with lightning until it
no longer bothers me.

I do not recommend this path for everyone.

> In general I think it behooves experienced users to listen to new users when
they say what has helped them get a handle on learning something.  Hackerb9,
as someone who has just gone through that initial learning curve, is in a
unique position to say what has been most useful.  There may be fatal flaws in
the particular mdoc(7) page he consulted, but what aspects of it were helpful,
and how can those be worked into something that's useful to beginners without
oversimplifying to the point of inaccuracy?

I agree with this.  Many valuable insights arise from newcomers to a system,
while they are innocent of its quirks and haven't yet internalized all the
knowledge about how "it just doesn't work that way".
 
> It's not like the groff package is any stranger to overlapping
documentation, having the Texinfo package for complete documentation for the
core language, and the groff(7) man page as a terse reference guide.

groff(7) has gotten less terse over the past couple of years.  Without
actually planning to, I seem to be evolving it in a CSTR #54-ish direction.

    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?58653>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/