Re: [systemd-devel] [v3 1/4] man: these binaries are internal APIs
On Sun, 15.03.15 17:59, Zbigniew Jędrzejewski-Szmek (zbys...@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 @@ parafilenamesystemd-poweroff.service/filename/para parafilenamesystemd-reboot.service/filename/para parafilenamesystemd-kexec.service/filename/para -parafilename/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 ___ systemd-devel mailing list systemd-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/systemd-devel
Re: [systemd-devel] [v3 1/4] man: these binaries are internal APIs
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 @@ parafilenamesystemd-poweroff.service/filename/para parafilenamesystemd-reboot.service/filename/para parafilenamesystemd-kexec.service/filename/para -parafilename/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. Zbyszek refsect1 diff --git a/man/systemd-shutdownd.service.xml b/man/systemd-shutdownd.service.xml index 756949c..051d2ab 100644 --- a/man/systemd-shutdownd.service.xml +++ b/man/systemd-shutdownd.service.xml @@ -52,7 +52,6 @@ refsynopsisdiv parafilenamesystemd-shutdownd.service/filename/para parafilenamesystemd-shutdownd.socket/filename/para -parafilename/usr/lib/systemd/systemd-shutdownd/filename/para /refsynopsisdiv refsect1 diff --git a/man/systemd-suspend.service.xml b/man/systemd-suspend.service.xml index a8beb86..8e3df5f 100644 --- a/man/systemd-suspend.service.xml +++ b/man/systemd-suspend.service.xml @@ -56,7 +56,6 @@ parafilenamesystemd-suspend.service/filename/para parafilenamesystemd-hibernate.service/filename/para parafilenamesystemd-hybrid-sleep.service/filename/para -parafilename/usr/lib/systemd/system-sleep/filename/para /refsynopsisdiv refsect1 -- 2.2.1.209.g41e5f3a ___ systemd-devel mailing list systemd-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/systemd-devel ___ systemd-devel mailing list systemd-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/systemd-devel
[systemd-devel] [v3 1/4] man: these binaries are internal APIs
--- 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 @@ parafilenamesystemd-poweroff.service/filename/para parafilenamesystemd-reboot.service/filename/para parafilenamesystemd-kexec.service/filename/para -parafilename/usr/lib/systemd/systemd-shutdown/filename/para /refsynopsisdiv refsect1 diff --git a/man/systemd-shutdownd.service.xml b/man/systemd-shutdownd.service.xml index 756949c..051d2ab 100644 --- a/man/systemd-shutdownd.service.xml +++ b/man/systemd-shutdownd.service.xml @@ -52,7 +52,6 @@ refsynopsisdiv parafilenamesystemd-shutdownd.service/filename/para parafilenamesystemd-shutdownd.socket/filename/para -parafilename/usr/lib/systemd/systemd-shutdownd/filename/para /refsynopsisdiv refsect1 diff --git a/man/systemd-suspend.service.xml b/man/systemd-suspend.service.xml index a8beb86..8e3df5f 100644 --- a/man/systemd-suspend.service.xml +++ b/man/systemd-suspend.service.xml @@ -56,7 +56,6 @@ parafilenamesystemd-suspend.service/filename/para parafilenamesystemd-hibernate.service/filename/para parafilenamesystemd-hybrid-sleep.service/filename/para -parafilename/usr/lib/systemd/system-sleep/filename/para /refsynopsisdiv refsect1 -- 2.2.1.209.g41e5f3a ___ systemd-devel mailing list systemd-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/systemd-devel