[arch-projects] [initscripts] Add manpage for rc.d script

[Seblu]

On Sun, Jul 31, 2011 at 3:18 PM, Dave Reisner <d at falconindy.com> wrote:
> On Sun, Jul 31, 2011 at 03:03:18PM +0200, Seblu wrote:
>> On Sun, Jul 31, 2011 at 2:30 PM, Dave Reisner <d at falconindy.com> wrote:
>> > On Wed, Jul 27, 2011 at 12:09:10PM +0200, Elvis Stansvik wrote:
>> >> As suggested by Tom at [1], I'm sending this patch here (see
>> >> attachment). Please proof-read and give comments.
>> >>
>> >> Cheers,
>> >> Elvis
>> >>
>> >> [1] https://bugs.archlinux.org/task/25269
>> >
>> >> From 2a7c154db87ce92c825802507d6e74762a344df1 Mon Sep 17 00:00:00 2001
>> >> From: Elvis Stansvik <elvstone at gmail.com>
>> >> Date: Wed, 27 Jul 2011 12:06:18 +0200
>> >> Subject: [PATCH] Add manpage for rc.d script.
>> >>
>> >> ---
>> >>  Makefile   |   13 +++++++++--
>> >>  rc.d.8.txt |   65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>> >>  2 files changed, 75 insertions(+), 3 deletions(-)
>> >>  create mode 100644 rc.d.8.txt
>> >>
>> >> diff --git a/Makefile b/Makefile
>> >> index 9fd2347..4c850c2 100644
>> >> --- a/Makefile
>> >> +++ b/Makefile
>> >> @@ -8,27 +8,34 @@ DIRS := \
>> >>       /usr/lib/tmpfiles.d \
>> >>       /usr/lib/initscripts \
>> >>       /etc/bash_completion.d \
>> >> -     /usr/share/zsh/site-functions
>> >> +     /usr/share/zsh/site-functions \
>> >> +     /usr/share/man/man8
>> >>
>> >>  minilogd: minilogd.o
>> >>
>> >>  installdirs:
>> >>       install -dm755 $(foreach DIR, $(DIRS), $(DESTDIR)$(DIR))
>> >>
>> >> -install: minilogd installdirs
>> >> +install: minilogd installdirs doc
>> >>       install -m644 -t $(DESTDIR)/etc inittab rc.conf
>> >>       install -m755 -t $(DESTDIR)/etc rc.local rc.local.shutdown rc.multi rc.shutdown rc.single rc.sysinit
>> >>       install -m644 -t $(DESTDIR)/etc/logrotate.d bootlog
>> >>       install -m644 -t $(DESTDIR)/etc/rc.d functions
>> >>       install -m755 -t $(DESTDIR)/etc/rc.d hwclock network netfs
>> >>       install -m755 -t $(DESTDIR)/sbin minilogd rc.d
>> >> +     install -m644 -t ${DESTDIR}/usr/share/man/man8 rc.d.8
>> >>       install -m755 -t $(DESTDIR)/usr/lib/initscripts arch-tmpfiles
>> >>       install -m644 tmpfiles.conf $(DESTDIR)/usr/lib/tmpfiles.d/arch.conf
>> >>       install -m644 -T bash-completion $(DESTDIR)/etc/bash_completion.d/rc.d
>> >>       install -m644 -T zsh-completion $(DESTDIR)/usr/share/zsh/site-functions/_rc.d
>> >>
>> >> +rc.d.8: rc.d.8.txt
>> >> +     a2x -d manpage -f manpage rc.d.8.txt
>> >> +
>> >> +doc: rc.d.8
>> >> +
>> >>  clean:
>> >> -     rm -f minilogd minilogd.o
>> >> +     rm -f minilogd minilogd.o rc.d.8
>> >>
>> >>  release:
>> >>       git archive HEAD --prefix=initscripts-$(VER)/ | xz > initscripts-$(VER).tar.xz
>> >> diff --git a/rc.d.8.txt b/rc.d.8.txt
>> >> new file mode 100644
>> >> index 0000000..2b5a25b
>> >> --- /dev/null
>> >> +++ b/rc.d.8.txt
>> >> @@ -0,0 +1,65 @@
>> >> +/////
>> >> +vim:set ts=4 sw=4 syntax=asciidoc noet:
>> >> +/////
>> >> +rc.d(8)
>> >> +=======
>> >> +
>> >> +Name
>> >> +----
>> >> +rc.d - Control and list daemons
>> >> +
>> >> +Synopsis
>> >> +--------
>> >> +*rc.d (action daemon...|list|help)*
>> >
>> > I'd like to see this in a more canonical format, e.g.
>> >
>> >  rc.d <action> [daemons]
>> >
>> > list is an action, too.
>> >
>> >> +Description
>> >> +-----------
>> >> +The *rc.d* script controls and lists daemons on the system. An action may be
>> >> +invoked on one or more daemons using *rc.d action daemon...*. See <<A,Actions>>
>> >> +below for more information. Use *rc.d list* to get the status of all daemons on
>> >> +the system.
>> >
>> > Not sure I like this paragraph. It'd a bit repetitious in context with
>> > the above synopsis and makes no mention of /etc/rc.d. Maybe something
>> > like...
>> >
>> >  rc.d controls and shows the status of programs which install a control
>> >  script in /etc/rc.d. Actions will vary between daemons, but are
>> >  typically one of 'start', 'start', or 'restart'. See <<A,Actions>>
>> >  below for more information. The 'list' action will display the status
>> >  of the given daemons, displaying all if no daemons are given.
>> >
>> > I'm sending a patch shortly to make this last part about 'list' accurate.
>> >
>> >> +
>> >> +Actions[[A]]
>> >> +------------
>> >> +The actions supported by a daemon may be different from daemon to daemon, but
>> >> +commonly supported actions include
>> >> +
>> >> +*start*::
>> >> +     Starts the daemon if it's not already running.
>> >> +
>> >> +*stop*::
>> >> +     Stops a running daemon.
>> >> +
>> >> +*restart*::
>> >> +     Restarts a running daemon.
>> >> +
>> >> +More uncommon actions are
>> >> +
>> >> +*reload*::
>> >> +     Signals the daemon to reload its configuration.
>> >
>> > It might just be me, but I don't like the usage of the word 'signal'
>> > here, as it might imply that a signal is sent, which isn't always the
>> > case.
>> >
>> >> +
>> >> +*status*::
>> >> +     Shows the status of the daemon.
>> >
>> > This whole section should be pluralized wrt daemons, no?
>> >
>> > dave
>> >
>> >> +
>> >> +Examples
>> >> +--------
>> >> +*rc.d stop crond*::
>> >> +     Stops the *crond* daemon.
>> >> +
>> >> +*rc.d start crond cupsd*::
>> >> +     Starts the *crond* and *cupsd* daemon.
>> >
>> > daemons.
>> >
>> >> +
>> >> +*rc.d restart crond*::
>> >> +     Restarts the *crond* daemon.
>> >> +
>> >> +*rc.d list*::
>> >> +     List all daemons and their status.
>> >> +
>> >> +Files
>> >> +-----
>> >> +'/etc/rc.d'::
>> >> +     Directory containing available daemons on the system.
>> >> +
>> >> +Authors
>> >> +-------
>> >> +*rc.d* is created by the Arch Linux Developer community.
>>
>> I'm not a good english writer/speaker but i believe its: was created.
>
> 'is created' is better, since we usually speak in the present tense
> about code (e.g. git commits), and this is also in line with what
> mkinitcpio uses in its manpage. 'was created' is also proper, just not
> in this context.
thanks for explanation!

>
>>
>> List action take 2 arguments (started/stopped). It should take place
>> in the man page.
>>
>> I'm not sure status is can be classified as "standard", few package in
>> official repo use it !
>>
>
> Maybe it should be ;)
>
:)

-- 
Sébastien Luttringer
www.seblu.net