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

[Elvis Stansvik]

2011/7/31 Dave Reisner <d at falconindy.com>:
> 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

I'm preparing a patch to incorporate these suggestions (minus the
"list <daemons>" thing as I saw that was reverted, right?).

Anyone know how I can get a newline in the synopsis, because I guess
there are two distinct synopsises now:

rc.d <action> [daemons]
rc.d list [started|stopped]

Or?

The '+' to get a newline didn't work for manpage output of a2x.

Elvis