Re: man-intro

[Oliver Corff]

Hi James,

this is a very nice intro indeed. I have a few suggestions:

I agree with Dave that the passus on numbered sections of man pages
should be moved further down. The majority of novice users will likely
search for commands, not necessarily for functions etc. A dedicated
section "On Sections" could begin with:

The library of man pages provides much more documentation than "just"
the commands you may want to use. System calls, library functions,
kernel interfaces and many other topics are treated in separate
sections. These sections are accessed by a number. Try, for instance,
man groff, which gives a synopsis of the details necessary for running
groff. In contrast, man 7 groff gives a "short reference" (not so short
after all) of the GNU roff language.

Near the beginning, I humbly suggest inserting a paragraph which
introduces the interaction of man page, formatter and pager, like:

All man pages your system offers are formatted uniformly. Calling a
given man page sends that man page through a formatter and prepares it
for display. You can read man pages on screen, but they will look
equally readable when formatted for print.


Finally, I'd encourage the user to verify for him/herself the difference
between a shell (e. g. bash) built-in and a man page call. In the case
of "cd", the difference is striking! "help cd" offers just a bit more
than a screenful of information, exactly the amount one is willing to
digest in the beginning.

"man cd", on the other hand, opens the bash built-in command *man page*,
which, at least on my system is a plethora of text to read (and digest).

Just my 2cents,

Oliver.


On 5/17/21 10:05 PM, James K. Lowden wrote:
> On Mon, 17 May 2021 16:24:34 +1200
> "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> wrote:
>
> > > Maybe Michael or Alejandro can advise regarding where they think a
> > > good place for a man page utilization tutorial would be.
> > If any place, I think intro(1) would be most appropriate, or,
> > failing that, an initial sentence that points the reader at another
> > page (that could be added in man-pages). My guiding principle would
> > be that the guidance given should be simple (introductory and not
> > comprehensive), finishing with pointers to man(1) and/or less(1)
> > for further details.
> >
> > The current intro(1) is an odd page though. Andries Brouwer made
> > some steps to turning into a general "intro to Linux" page, but that
> > was, to my mind, always going to be an impossibly huge scope. I'm
> > not a huge fan of what is there.
> Attached is a straw man 1st draft of what an introduction to the man
> system might look like.  If it clears the threshold of raspberries,
> perhaps we can mold it into something useful.
>
> I think the page should be called man-intro, or intro-man.  (Need
> help?  Never fear, Intro Man is here!)  I included what I wish
> someone had told me back when VAXes were in production.
>
> This is my work.  I'm happy to consign it to the groff project or FSF,
> or to the public domain.
>
> --jkl
--
Dr. Oliver Corff
-- China Consultant --
Wittelsbacherstr. 5A
D-10707 Berlin
Tel.: +49-30-8572726-0
Fax : +49-30-8572726-2
mailto:oliver.corff@email.de