Documentation cleanups for github release.

veripool · Oct 26, 2019 · c368a94 · c368a94
1 parent 68ff5b6
commit c368a94
Show file tree

Hide file tree

Showing 21 changed files with 138 additions and 190 deletions.
diff --git a/Changes b/Changes
@@ -2,6 +2,10 @@ Revision history for Perl extension IPC::Locker
 
 The contributors that suggested a given feature are shown in [].
 
+* IPC::Locker 1.500 devel
+
+****  Documentation cleanups for github release.
+
 
 * IPC::Locker 1.496 2017-04-26
 
@@ -35,7 +39,7 @@ The contributors that suggested a given feature are shown in [].
 
 * IPC::Locker 1.487 2010-07-01
 
-****	Fix documentation on ::Server, bug252.  [Dennis McCoy]
+****	Fix documentation on ::Server, issue5.  [Dennis McCoy]
 
 ****	Use Test::More to simplify test failure debugging.
 
@@ -45,7 +49,7 @@ The contributors that suggested a given feature are shown in [].
 **	Add 3 automatic retries on connection failures.  [Krishna Subramanian]
 	Override using IPC::Locker->new()'s connect_tries and connect_sleep.
 
-***	Fix repeating locks to one client, bug237.  [by Krishna Subramanian]
+***	Fix repeating locks to one client, issue4.  [by Krishna Subramanian]
 
 ****	Fix "waiting" messages to show first lock name, not last.
 

diff --git a/MANIFEST b/MANIFEST
@@ -13,8 +13,7 @@ MANIFEST.SKIP
 META.yml			Module meta-data (added by MakeMaker)
 nagios/check_lockerd
 nagios/check_pidstatd
-README
-readme.texi
+README.pod
 script/lockerd
 script/lockersh
 script/pidstat

diff --git a/META.yml b/META.yml
@@ -8,8 +8,8 @@ installdirs:  site
 author:
     - Wilson Snyder <wsnyder@wsnyder.org>
 resources:
-    homepage: http://www.veripool.org/ipc-locker
-    bugtracker: http://www.veripool.org/ipc-locker-bugs
+    homepage: https://www.veripool.org/ipc-locke
+    bugtracker: https://www.veripool.org/ipc-locker
 requires:
     Net::Domain:                   0
     Pod::Usage:                    1.34

diff --git a/Makefile.PL b/Makefile.PL
@@ -10,10 +10,6 @@ use Carp;
 
 sub MY::postamble {
     q{
-README: readme.texi
-	-$(RM_RF) $@
-	makeinfo $< --output $@ --no-headers --no-validate
-
 install::
 	@echo
 	@echo '-NOTE: You may want to'
@@ -28,7 +24,6 @@ install-here::
 ## Maintainer use:
 preexist:
 	svnorcvs nexists $(DISTNAME)_$(VERSION_SYM)
-	test -s README
 
 tag:
 	svnorcvs tag  $(DISTNAME)_$(VERSION_SYM)
@@ -65,7 +60,7 @@ WriteMakefile(
 				script/uriexec )],
 	      'dist'    => {COMPRESS => 'gzip -9f',
 			    SUFFIX   => '.gz',
-			    DIST_DEFAULT => 'README all tardist',
+			    DIST_DEFAULT => 'all tardist',
 			},
 	      );
 
diff --git a/README.pod b/README.pod
@@ -0,0 +1,113 @@
+=pod
+
+=head1 SUMMARY
+
+IPC::Locker provides a server for locks and a Perl package for clients to
+access that server.  The result is that clients can access named locks on a
+Internet wide basis, solving critical section problems without the mess of
+NFS or other file locking techniques.
+
+The latest version is available from CPAN and from
+L<https://www.veripool.org/ipc-locker>.
+
+=head1 EXAMPLE
+
+   use IPC::Locker;
+   # ...
+   my $lock = IPC::Locker->lock(host=>'example.std.com');
+   # ... Critical section ...
+   $lock->unlock;
+
+=head1 INSTALLATION
+
+=head2 Build and Install the Package
+
+=head3 Install from CPAN:
+
+   cpan install IPC::Locker
+
+=head3 Or, build from sources:
+
+   # Obtain distribution kit
+   git clone git@github.com:veripool/IPC-Locker.git
+   # Build
+   cd IPC-Locker
+   git pull
+   perl Makefile.PL
+   make
+   make test
+   make install
+
+=head2 Install the Daemons
+
+You may wish to install C<lockerd> and C<pidstatd> in a init.rc file so
+that it is run at system startup.  Depending on your distribution, you may
+be able to just:
+
+   cp init.d/lockerd   /etc/init.d/lockerd  # On one server only
+   cp init.d/pidstatd  /etc/init.d/pidstatd  # On all machines
+
+Edit paths in above to point to /usr/bin instead of /usr/local/bin, if needed.
+
+   service lockerd start  # On one server only
+   service pidstatd start  # On all machines
+   chkconfig lockerd on  # On one server only
+   chkconfig pidstatd on  # On all machines
+
+If you get "This account is currently not available."  you need to change
+the daemon account from a shell of /sbin/nologin to /sbin/bash.
+
+=head2 Nagios
+
+If you are using Nagios http://www.nagios.org, sample scripts to check the
+daemons are included in the nagios subdirectory.
+
+=head1 DOCUMENTATION
+
+IPC::Locker provides the following programs/packages:
+
+=head2 lockerd
+
+C<lockerd> is the daemon that supports IPC::Locker. See C<man
+lockerd> after installation.
+
+=head2 IPC::PidStat
+
+C<IPC::PidStat> is a Perl package which answers the question, "is pid X
+running on host Y?".  See C<man IPC::PidStat> after installation.
+
+=head2 pidstat
+
+C<pidstat> is a program which answers the question, "is pid X running on
+host Y?".  See C<man pidstat> after installation.
+
+=head2 pidstatd
+
+C<pidstat> is the daemon that supports C<IPC::PidStat> and C<pidstat>. See
+C<man pidstatd> after installation.
+
+=head2 pidwatch
+
+C<pidwatch> is a program which starts other programs, and kill that program
+when another job exists.  See C<man pidwatch> after installation.
+
+=head2 uriexec
+
+C<uriexec> is a simple wrapper which allows executing a command which is
+quoted using URI escapes.  This prevents layered shells from interpreting
+special characters.  See C<man uriexec> after installation.
+
+=head2 check_lockerd and check_pidstatd
+
+C<check_lockerd> and C<check_pidstatd> are Nagios plugins to check
+C<lockerd> and C<pidstatd>.  See the Nagios documentation at
+https://www.nagios.org for information on installing plugins.
+
+=head1 LICENSE
+
+This package is Copyright 1999-2019 by Wilson Snyder <wsnyder@wsnyder.org>.
+
+This program is free software; you can redistribute it and/or modify it
+under the terms of either the GNU Lesser General Public License Version 3
+or the Perl Artistic License Version 2.0.  This code is provided with no
+warranty of any kind, and is used entirely at your own risk.
diff --git a/lib/IPC/Locker.pm b/lib/IPC/Locker.pm
@@ -209,7 +209,7 @@ The port number (INET) or name (UNIX) of the lock server.  Defaults to
 
 =head1 DISTRIBUTION
 
-The latest version is available from CPAN and from L<http://www.veripool.org/>.
+The latest version is available from CPAN and from L<https://www.veripool.org/ipc-locker>.
 
 Copyright 1999-2017 by Wilson Snyder.  This package is free software; you
 can redistribute it and/or modify it under the terms of either the GNU

diff --git a/lib/IPC/Locker/Server.pm b/lib/IPC/Locker/Server.pm
@@ -47,7 +47,7 @@ The port number (INET) or name (UNIX) of the lock server.  Defaults to
 
 =head1 DISTRIBUTION
 
-The latest version is available from CPAN and from L<http://www.veripool.org/>.
+The latest version is available from CPAN and from L<https://www.veripool.org/ipc-locker>.
 
 Copyright 1999-2017 by Wilson Snyder.  This package is free software; you
 can redistribute it and/or modify it under the terms of either the GNU

diff --git a/lib/IPC/PidStat.pm b/lib/IPC/PidStat.pm
@@ -321,7 +321,7 @@ looked up via /etc/services, else 1752.
 
 =head1 DISTRIBUTION
 
-The latest version is available from CPAN and from L<http://www.veripool.org/>.
+The latest version is available from CPAN and from L<https://www.veripool.org/ipc-locker>.
 
 Copyright 2002-2017 by Wilson Snyder.  This package is free software; you
 can redistribute it and/or modify it under the terms of either the GNU

diff --git a/lib/IPC/PidStat/PidServer.pm b/lib/IPC/PidStat/PidServer.pm
@@ -139,7 +139,7 @@ The port number (INET) or name (UNIX) of the lock server.  Defaults to
 
 =head1 DISTRIBUTION
 
-The latest version is available from CPAN and from L<http://www.veripool.org/>.
+The latest version is available from CPAN and from L<https://www.veripool.org/ipc-locker>.
 
 Copyright 2002-2017 by Wilson Snyder.  This package is free software; you
 can redistribute it and/or modify it under the terms of either the GNU

diff --git a/nagios/check_lockerd b/nagios/check_lockerd
@@ -129,7 +129,7 @@ Specifies the port number to contact the "lockerd" on.  (default 1752)
 
 =head1 DISTRIBUTION
 
-The latest version is available from CPAN and from L<http://www.veripool.org/>.
+The latest version is available from CPAN and from L<https://www.veripool.org/ipc-locker>.
 
 Copyright 2006-2017 by Wilson Snyder.  This package is free software; you
 can redistribute it and/or modify it under the terms of either the GNU

diff --git a/nagios/check_pidstatd b/nagios/check_pidstatd
@@ -124,7 +124,7 @@ Specifies the port number to contact the "pidstatd" on.  (default 1752)
 
 =head1 DISTRIBUTION
 
-The latest version is available from CPAN and from L<http://www.veripool.org/>.
+The latest version is available from CPAN and from L<https://www.veripool.org/ipc-locker>.
 
 Copyright 2006-2017 by Wilson Snyder.  This package is free software; you
 can redistribute it and/or modify it under the terms of either the GNU

diff --git a/nodist/locker_perf b/nodist/locker_perf
@@ -196,7 +196,7 @@ Minute-hand time to start at, to insure all jobs are simultanious.
 
 =head1 DISTRIBUTION
 
-The latest version is available from CPAN and from L<http://www.veripool.org/>.
+The latest version is available from CPAN and from L<https://www.veripool.org/ipc-locker>.
 
 Copyright 2008-2017 by Wilson Snyder.  This package is free software; you
 can redistribute it and/or modify it under the terms of either the GNU

diff --git a/nodist/locker_stress b/nodist/locker_stress
@@ -371,7 +371,7 @@ Minute-hand time to start at, to insure all jobs are simultanious.
 
 =head1 DISTRIBUTION
 
-The latest version is available from CPAN and from L<http://www.veripool.org/>.
+The latest version is available from CPAN and from L<https://www.veripool.org/ipc-locker>.
 
 Copyright 2008-2017 by Wilson Snyder.  This package is free software; you
 can redistribute it and/or modify it under the terms of either the GNU

diff --git a/nodist/pidstat_local b/nodist/pidstat_local
@@ -60,7 +60,7 @@ Debug tool to check local pid status
 
 =head1 DISTRIBUTION
 
-The latest version is available from CPAN and from L<http://www.veripool.org/>.
+The latest version is available from CPAN and from L<https://www.veripool.org/ipc-locker>.
 
 Copyright 2008-2017 by Wilson Snyder.  This package is free software; you
 can redistribute it and/or modify it under the terms of either the GNU

diff --git a/nodist/pidstat_perf b/nodist/pidstat_perf
@@ -191,7 +191,7 @@ Minute-hand time to start at, to insure all jobs are simultanious.
 
 =head1 DISTRIBUTION
 
-The latest version is available from CPAN and from L<http://www.veripool.org/>.
+The latest version is available from CPAN and from L<https://www.veripool.org/ipc-locker>.
 
 Copyright 2008-2017 by Wilson Snyder.  This package is free software; you
 can redistribute it and/or modify it under the terms of either the GNU