[systemd-devel] [v3 1/4] man: these binaries are internal APIs

[Lennart Poettering]

On Sun, 15.03.15 17:59, Zbigniew Jędrzejewski-Szmek (zbyszek at in.waw.pl) wrote:

> On Fri, Feb 27, 2015 at 05:04:21PM -0800, Shawn Landden wrote:
> > ---
> >  man/systemd-halt.service.xml      | 1 -
> >  man/systemd-shutdownd.service.xml | 1 -
> >  man/systemd-suspend.service.xml   | 1 -
> >  3 files changed, 3 deletions(-)
> > 
> > diff --git a/man/systemd-halt.service.xml b/man/systemd-halt.service.xml
> > index c94e2a1..7e7f8f2 100644
> > --- a/man/systemd-halt.service.xml
> > +++ b/man/systemd-halt.service.xml
> > @@ -56,7 +56,6 @@
> >      <para><filename>systemd-poweroff.service</filename></para>
> >      <para><filename>systemd-reboot.service</filename></para>
> >      <para><filename>systemd-kexec.service</filename></para>
> > -    <para><filename>/usr/lib/systemd/systemd-shutdown</filename></para>
> >    </refsynopsisdiv>
> Hm, I was going back and forth on this patch... You are certainly right that
> the user should never call those binaries directly. But we do list other
> binaries in the documentation in similar circumstances. And I think we should
> continue to do so, for two reasons:
> 1. when trying to understand how everythig works it makes it easier to start
> with the documentation and see what binaries are used to do various things.
> 2. when looking for something related, it makes it easier to distinguish
> various commands with a similar name. ("This systemd-sleep binary is not
> the binary you're looking for." :))
> 
> Maybe we should move the binary to FILES section and mention that it should
> not be called directly. But then this should be done also for systemd-journald
> and others which are never called directly.

I am pretty sure we should document the binary paths, even if these
binaries are nothing that normal users should ever invoke
directly. The reason is simply that "ps" will show these binaries with
these paths, and I think it's good to provide explanations in man
pages for them hence. "ps" is about discovering what's running, and we
should help with our documentation to make useful what it shows there.

Lennart

-- 
Lennart Poettering, Red Hat