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

[Dave Reisner]

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.
> -- 
> 1.7.6
>