Full path in SYNOPSIS for /usr/libexec programs

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Full path in SYNOPSIS for /usr/libexec programs

Lyndon Nerenberg (VE6BBM/VE7TFX)
For programs that live in /usr/libexec, those with manpages show
just the bare program name in the SYNOPSIS section (when there is
a SYNOPSIS section).

There is a long-standing expectation that programs documented in
section 8 of the manual can be run from a shell with /sbin:/usr/sbin
in the $PATH.  It's frustrating for newer BSD admins when foo(8)
programs aren't there, apparently, due to living in libexec.  Also,
sometimes, even for the older BSD admins who expect to find these
things in *sbin from, e.g., older SunOS releases.

What I'd like to do is fully qualify the paths to those commands in
the SYNOPSIS section, where that makes sense.  E.g. for the mail.*(8)
entries, 'mail.*' becomes '/usr/libexec/mail.*' under SYNOPSIS (only).

For entries that have a *sbin command shadowing a /usr/libexec program,
nothing changes.

If people think this makes sense I'll sendbug a patch.

--lyndon

Reply | Threaded
Open this post in threaded view
|

Re: Full path in SYNOPSIS for /usr/libexec programs

Theo de Raadt-2
Disagree on this.

Those programs are intentionally not in the path, since you don't
run them by hand.

I think you are making a mountain out of a molehill.

Lyndon Nerenberg <[hidden email]> wrote:

> For programs that live in /usr/libexec, those with manpages show
> just the bare program name in the SYNOPSIS section (when there is
> a SYNOPSIS section).
>
> There is a long-standing expectation that programs documented in
> section 8 of the manual can be run from a shell with /sbin:/usr/sbin
> in the $PATH.  It's frustrating for newer BSD admins when foo(8)
> programs aren't there, apparently, due to living in libexec.  Also,
> sometimes, even for the older BSD admins who expect to find these
> things in *sbin from, e.g., older SunOS releases.
>
> What I'd like to do is fully qualify the paths to those commands in
> the SYNOPSIS section, where that makes sense.  E.g. for the mail.*(8)
> entries, 'mail.*' becomes '/usr/libexec/mail.*' under SYNOPSIS (only).
>
> For entries that have a *sbin command shadowing a /usr/libexec program,
> nothing changes.
>
> If people think this makes sense I'll sendbug a patch.
>
> --lyndon
>

Reply | Threaded
Open this post in threaded view
|

Re: Full path in SYNOPSIS for /usr/libexec programs

Lyndon Nerenberg (VE6BBM/VE7TFX)
Theo de Raadt writes:
> Disagree on this.
>
> Those programs are intentionally not in the path, since you don't
> run them by hand.

That's what I was getting at.  It's not clear they are 'libexec's.
That's what confuses people.  I just thought this might be a way
to make it clear(er) that you don't run these directly, but that
they are invoked by other things.

I.e. it's easy to explain the concept of /usr/libexec to people
once, so they recognize it when they see the path spelled out.  But
when we're bringing in people from Linux, their first reaction upon
not finding the documented command is to start installing packages
from hell to breakfast until something works.  From an indoctrination
standpoint, there's a lot less pain (and cleanup work) if they know
right away that /usr/libexec/foo(8) is not something you run from
the shell.

I won't push this any further, but experience shows this change
really helps guide people into the BSD filesystem hierarchy
conventions.

--lyndon

Reply | Threaded
Open this post in threaded view
|

Re: Full path in SYNOPSIS for /usr/libexec programs

Theo de Raadt-2
Lyndon Nerenberg <[hidden email]> wrote:

> Theo de Raadt writes:
> > Disagree on this.
> >
> > Those programs are intentionally not in the path, since you don't
> > run them by hand.
>
> That's what I was getting at.  It's not clear they are 'libexec's.
> That's what confuses people.  I just thought this might be a way
> to make it clear(er) that you don't run these directly, but that
> they are invoked by other things.

Which people does it confuse?

> I.e. it's easy to explain the concept of /usr/libexec to people
> once, so they recognize it when they see the path spelled out.  But
> when we're bringing in people from Linux, their first reaction upon
> not finding the documented command is to start installing packages
> from hell to breakfast until something works.  From an indoctrination
> standpoint, there's a lot less pain (and cleanup work) if they know
> right away that /usr/libexec/foo(8) is not something you run from
> the shell.

They are installing packages for a command that has a manual page
already?  Look I really doubt that is happening.

> I won't push this any further, but experience shows this change
> really helps guide people into the BSD filesystem hierarchy
> conventions.

We do not include paths in SYNOPSIS, because it isn't important
(and in some cases, it would be dangerous to do so)