Merge pull request #896 from knnniggett/pod2man

Generate man pages for perl scripts & C Binaries in the bin folder

CMakeLists.txt

@@ -663,6 +663,10 @@ configure_file(zoneminder-config.cmake "${CMAKE_CURRENT_BINARY_DIR}/config.h" @O
 configure_file(zmconfgen.pl.in "${CMAKE_CURRENT_BINARY_DIR}/zmconfgen.pl" @ONLY)
 configure_file(zmlinkcontent.sh.in "${CMAKE_CURRENT_BINARY_DIR}/zmlinkcontent.sh" @ONLY)
 
+# Create a target for man pages
+include(Pod2Man)
+ADD_MANPAGE_TARGET()
+
 # Process subdirectories
 add_subdirectory(src)
 add_subdirectory(scripts)

cmake/Modules/Pod2Man.cmake

@@ -0,0 +1,71 @@
+#
+# Copyright (C) 2012	Emmanuel Roullit <emmanuel.roullit@gmail.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or (at
+# your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
+#
+
+# Generate man pages of the project by using the
+# POD header written in the tool source code.
+# To use it, include this file in CMakeLists.txt and
+# invoke POD2MAN(<podfile> <manfile> <section>)
+
+MACRO(POD2MAN PODFILE MANFILE SECTION)
+	FIND_PROGRAM(POD2MAN pod2man)
+	FIND_PROGRAM(GZIP gzip)
+
+	IF(NOT POD2MAN)
+		MESSAGE(FATAL ERROR "Need pod2man installed to generate man page")
+	ENDIF(NOT POD2MAN)
+
+	IF(NOT GZIP)
+		MESSAGE(FATAL ERROR "Need gzip installed to compress man page")
+	ENDIF(NOT GZIP)
+
+	IF(NOT EXISTS ${PODFILE})
+		MESSAGE(FATAL ERROR "Could not find pod file ${PODFILE} to generate man page")
+	ENDIF(NOT EXISTS ${PODFILE})
+
+	ADD_CUSTOM_COMMAND(
+		OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${MANFILE}.${SECTION}
+		DEPENDS ${PODFILE}
+		COMMAND ${POD2MAN}
+		ARGS --section ${SECTION} --center ${CMAKE_PROJECT_NAME} --release --stderr --name ${MANFILE}
+		${PODFILE} > ${CMAKE_CURRENT_BINARY_DIR}/${MANFILE}.${SECTION}
+	)
+
+	ADD_CUSTOM_COMMAND(
+		OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${MANFILE}.${SECTION}.gz
+		COMMAND ${GZIP} --best -c ${CMAKE_CURRENT_BINARY_DIR}/${MANFILE}.${SECTION} > ${CMAKE_CURRENT_BINARY_DIR}/${MANFILE}.${SECTION}.gz
+		DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${MANFILE}.${SECTION}
+	)
+
+	SET(MANPAGE_TARGET "man-${MANFILE}")
+
+	ADD_CUSTOM_TARGET(${MANPAGE_TARGET} DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${MANFILE}.${SECTION}.gz)
+	ADD_DEPENDENCIES(man ${MANPAGE_TARGET})
+
+	INSTALL(
+		FILES ${CMAKE_CURRENT_BINARY_DIR}/${MANFILE}.${SECTION}.gz
+		DESTINATION share/man/man${SECTION}
+    	)
+ENDMACRO(POD2MAN PODFILE MANFILE SECTION)
+
+MACRO(ADD_MANPAGE_TARGET)
+	# It is not possible add a dependency to target 'install'
+	# Run hard-coded 'make man' when 'make install' is invoked
+	INSTALL(CODE "EXECUTE_PROCESS(COMMAND make man)")
+	ADD_CUSTOM_TARGET(man)
+ENDMACRO(ADD_MANPAGE_TARGET)
+

distros/fedora/zoneminder.f20.spec

@@ -24,7 +24,7 @@ Source: ZoneMinder-%{version}.tar.gz
 
 BuildRequires: cmake gnutls-devel systemd-units bzip2-devel
 BuildRequires: community-mysql-devel pcre-devel libjpeg-turbo-devel
-BuildRequires: perl(Archive::Tar) perl(Archive::Zip)
+BuildRequires: perl(Archive::Tar) perl(Archive::Zip) perl-podlators
 BuildRequires: perl(Date::Manip) perl(DBD::mysql)
 BuildRequires: perl(ExtUtils::MakeMaker) perl(LWP::UserAgent)
 BuildRequires: perl(MIME::Entity) perl(MIME::Lite)

distros/fedora/zoneminder.f21.spec

@@ -24,7 +24,7 @@ Source: ZoneMinder-%{version}.tar.gz
 
 BuildRequires: cmake gnutls-devel systemd-units bzip2-devel
 BuildRequires: community-mysql-devel pcre-devel libjpeg-turbo-devel
-BuildRequires: perl(Archive::Tar) perl(Archive::Zip)
+BuildRequires: perl(Archive::Tar) perl(Archive::Zip) perl-podlators
 BuildRequires: perl(Date::Manip) perl(DBD::mysql)
 BuildRequires: perl(ExtUtils::MakeMaker) perl(LWP::UserAgent)
 BuildRequires: perl(MIME::Entity) perl(MIME::Lite)

distros/redhat/zoneminder.el7.spec

@@ -20,7 +20,7 @@ Source: ZoneMinder-%{version}.tar.gz
 
 BuildRequires: cmake gnutls-devel systemd-units bzip2-devel
 BuildRequires: mariadb-devel pcre-devel libjpeg-turbo-devel
-BuildRequires: perl(Archive::Tar) perl(Archive::Zip)
+BuildRequires: perl(Archive::Tar) perl(Archive::Zip) perl-podlators
 BuildRequires: perl(Date::Manip) perl(DBD::mysql)
 BuildRequires: perl(ExtUtils::MakeMaker) perl(LWP::UserAgent)
 BuildRequires: perl(MIME::Entity) perl(MIME::Lite)

scripts/CMakeLists.txt

@@ -24,6 +24,12 @@ endif(NOT ZM_NO_X10)
 configure_file(zm.in "${CMAKE_CURRENT_BINARY_DIR}/zm" @ONLY)
 #configure_file(zmeventdump.in zmeventdump @ONLY)
 
+# Generate man files for the perl scripts destined for the bin folder
+file(GLOB perlscripts RELATIVE "${CMAKE_CURRENT_BINARY_DIR}" "*.pl")
+FOREACH(PERLSCRIPT ${perlscripts})
+    POD2MAN(${CMAKE_CURRENT_BINARY_DIR}/${PERLSCRIPT} zoneminder-${PERLSCRIPT} 8)
+ENDFOREACH(PERLSCRIPT ${perlscripts})
+
 # Install the perl scripts
 install(FILES "${CMAKE_CURRENT_BINARY_DIR}/zmaudit.pl" "${CMAKE_CURRENT_BINARY_DIR}/zmcontrol.pl" "${CMAKE_CURRENT_BINARY_DIR}/zmdc.pl" "${CMAKE_CURRENT_BINARY_DIR}/zmfilter.pl" "${CMAKE_CURRENT_BINARY_DIR}/zmpkg.pl" "${CMAKE_CURRENT_BINARY_DIR}/zmtrack.pl" "${CMAKE_CURRENT_BINARY_DIR}/zmtrigger.pl" "${CMAKE_CURRENT_BINARY_DIR}/zmupdate.pl" "${CMAKE_CURRENT_BINARY_DIR}/zmvideo.pl" "${CMAKE_CURRENT_BINARY_DIR}/zmwatch.pl" "${CMAKE_CURRENT_BINARY_DIR}/zmcamtool.pl" "${CMAKE_CURRENT_BINARY_DIR}/zmsystemctl.pl" DESTINATION "${CMAKE_INSTALL_FULL_BINDIR}" PERMISSIONS OWNER_WRITE OWNER_READ OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE)
 if(NOT ZM_NO_X10)

scripts/zmsystemctl.pl.in

@@ -31,10 +31,15 @@ zmsystemctl.pl - ZoneMinder systemctl wrapper
 
 =head1 DESCRIPTION
 
-This is a wrapper script that allows zoneminder to start and stop itself
+This script allows an unpriveledged user to start, stop, or restart the
-in a manner that keeps it in-sync with systemd.  This script is intended
+zoneminder service on a system running systemd. It does this by redirecting
-to be called internally by zoneminder and may not give the desired results
+commands through pkexec, which checks the available polkit policy files. The
-if run from the command line.
+default policy file grants the system web account user permission. This can be
+changed or expanded by modifying the policy file. See man polkit for details.
+
+=head1 SEE ALSO
+
+polkit(8), pkexec(1)
 
 =cut
 use warnings;

src/CMakeLists.txt

@@ -23,6 +23,11 @@ target_link_libraries(zmf zm ${ZM_EXTRA_LIBS} ${ZM_BIN_LIBS})
 target_link_libraries(zms zm ${ZM_EXTRA_LIBS} ${ZM_BIN_LIBS})
 target_link_libraries(zmstreamer zm ${ZM_EXTRA_LIBS} ${ZM_BIN_LIBS})
 
+# Generate man files for the binaries destined for the bin folder
+FOREACH(CBINARY zma.cpp zmc.cpp zmf.cpp zmu.cpp zmstreamer.cpp)
+    POD2MAN(${CMAKE_CURRENT_BINARY_DIR}/${CBINARY} zoneminder-${CBINARY} 8)
+ENDFOREACH(CBINARY zma.cpp zmc.cpp zmf.cpp zmu.cpp zmstreamer.cpp)
+
 install(TARGETS zmc zma zmu zmf zmstreamer RUNTIME DESTINATION "${CMAKE_INSTALL_FULL_BINDIR}" PERMISSIONS OWNER_WRITE OWNER_READ OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE)
 install(TARGETS zms RUNTIME DESTINATION "${ZM_CGIDIR}" PERMISSIONS OWNER_WRITE OWNER_READ OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE)
 install(CODE "execute_process(COMMAND ln -sf zms nph-zms WORKING_DIRECTORY \"\$ENV{DESTDIR}${ZM_CGIDIR}\")")

src/zma.cpp

@@ -17,6 +17,38 @@
 // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 // 
 
+/*
+
+=head1 NAME
+
+zma - The ZoneMinder Analysis daemon
+
+=head1 SYNOPSIS
+
+ zma -m <monitor_id>
+ zma --monitor <monitor_id>
+ zma -h
+ zma --help
+ zma -v
+ zma --version
+
+=head1 DESCRIPTION
+
+This is the component that goes through the captured frames and checks them
+for motion which might generate an alarm or event. It generally keeps up with
+the Capture daemon but if very busy may skip some frames to prevent it falling
+behind.
+
+=head1 OPTIONS
+
+ -m, --monitor_id                 - ID of the monitor to analyse
+ -h, --help                       - Display usage information
+ -v, --version                    - Print the installed version of ZoneMinder
+
+=cut
+
+*/
+
 #include <getopt.h>
 #include <signal.h>
 

src/zmc.cpp

@@ -17,6 +17,44 @@
 // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 // 
 
+/*
+
+=head1 NAME
+
+zmc - The ZoneMinder Capture daemon
+
+=head1 SYNOPSIS
+
+ zmc -d <device_path>
+ zmc --device <device_path>
+ zmc -r <proto> -H <host> -P <port> -p <path>
+ zmc -f <file_path>
+ zmc --file <file_path>
+ zmc -m <monitor_id>
+ zmc --monitor <monitor_id>
+ zmc -h
+ zmc --help
+ zmc -v
+ zmc --version
+
+=head1 DESCRIPTION
+
+This binary's job is to sit on a video device and suck frames off it as fast as
+possible, this should run at more or less constant speed. 
+
+=head1 OPTIONS
+
+ -d, --device <device_path>               - For local cameras, device to access. e.g /dev/video0 etc
+ -r <proto> -H <host> -P <port> -p <path> - For remote cameras
+ -f, --file <file_path>                   - For local images, jpg file to access.
+ -m, --monitor_id                         - ID of the monitor to analyse
+ -h, --help                               - Display usage information
+ -v, --version                            - Print the installed version of ZoneMinder
+
+=cut
+
+*/
+
 #include <getopt.h>
 #include <signal.h>
 #if defined(__FreeBSD__)

src/zmf.cpp

@@ -17,6 +17,39 @@
 // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 // 
 
+/*
+
+=head1 NAME
+
+zmf - The ZoneMinder Frame daemon
+
+=head1 SYNOPSIS
+
+ zmf -m <monitor_id>
+ zmf --monitor <monitor_id>
+ zmf -h
+ zmf --help
+ zmf -v
+ zmf --version
+
+=head1 DESCRIPTION
+
+This is an optional daemon that can run in concert with the Analysis daemon and
+whose function it is to actually write captured frames to disk. This frees up
+the Analysis daemon to do more analysis (!) and so keep up with the Capture
+daemon better. If it isn’t running or dies then the Analysis daemon just writes
+them itself. 
+
+=head1 OPTIONS
+
+ -m, --monitor_id                 - ID of the monitor to use
+ -h, --help                       - Display usage information
+ -v, --version                    - Print the installed version of ZoneMinder
+
+=cut
+
+*/
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <unistd.h>

src/zmstreamer.cpp

@@ -19,6 +19,52 @@
 // along with this program; if not, write to the Free Software
 // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
+/*
+
+=head1 NAME
+
+zmstreamer - eyeZM video streamer
+
+=head1 SYNOPSIS
+
+ zmstreamer -e <mode>
+ zmstreamer -o <format>
+ zmstreamer -u <buffer size>
+ zmstreamer -f <maximum fps>
+ zmstreamer -s <scale>
+ zmstreamer -b <bitrate in bps>
+ zmstreamer -m <monitor id>
+ zmstreamer -d <debug mode>
+ zmstreamer -i
+ zmstreamer -?
+ zmstreamer -h
+ zmstreamer -v
+
+=head1 DESCRIPTION
+
+*DEPRECIATED* The xml skin and all files associated with the xml skin are now
+depreciated. Please use the ZoneMinder API instead.
+
+This binary works in conjunction with the XML skin to stream video to iPhones
+running the eyeZm app. 
+
+=head1 OPTIONS
+
+ -e <mode>                        - Specify output mode: mpeg/jpg/zip/single/raw.
+ -o <format>                      - Specify output format.
+ -u <buffer size>                 - Specify buffer size in ms.
+ -f <maximum fps>                 - Specify maximum framerate.
+ -s <scale>                       - Specify scale.
+ -b <bitrate in bps>              - Specify bitrate.
+ -m <monitor id>                  - Specify monitor id.
+ -d <debug mode>                  - 0 = off, 1 = no streaming, 2 = with streaming.
+ -i, -?, -h                       - Display usage information
+ -v                               - Print the installed version of ZoneMinder
+
+=cut
+
+*/
+
 #include <stdio.h>
 #include <stdlib.h>
 

src/zmu.cpp

@@ -17,6 +17,75 @@
 // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 // 
 
+/*
+
+=head1 NAME
+
+zmc - The ZoneMinder Utility
+
+=head1 SYNOPSIS
+
+ zmu -d device_path [-v] [function] [-U<username> -P<password>]
+ zmu --device device_path [-v] [function] [-U<username> -P<password>]
+
+ zmu -m monitor_id [-v] [function] [-U<username> -P<password>]
+ zmu --monitor monitor_id [-v] [function] [-U<username> -P<password>]
+
+=head1 DESCRIPTION
+
+This binary is a handy command line interface to several useful functions. It’s
+not really meant to be used by anyone except the web page (there's only limited
+'help' in it so far) but can be if necessary, especially for debugging video
+problems. 
+
+=head1 OPTIONS
+
+General options:
+  -v, --verbose                           - Produce more verbose output
+  -l, --list                              - List the current status of active (or all with -v) monitors
+  -h, --help                               - Display usage information
+  -v, --version                            - Print the installed version of ZoneMinder
+
+Options for use with devices:
+  -d, --device [device_path]              - Get the current video device settings for [device_path] or all devices
+  -V, --version <V4L version>             - Set the Video 4 Linux API version to use for the query, use 1 or 2
+  -q, --query                             - Query the current settings for the device
+
+Options for use with monitors:
+  -m, --monitor <monitor_id>              - Specify which monitor to address, default 1 if absent
+  -q, --query                             - Query the current settings for the monitor
+  -s, --state                             - Output the current monitor state, 0 = idle, 1 = prealarm, 2 = alarm,
+                                            3 = alert, 4 = tape
+  -B, --brightness [value]                - Output the current brightness, set to value if given 
+  -C, --contrast [value]                  - Output the current contrast, set to value if given 
+  -H, --hue [value]                       - Output the current hue, set to value if given 
+  -O, --colour [value]                    - Output the current colour, set to value if given 
+  -i, --image [image_index]               - Write captured image to disk as <monitor_name>.jpg, last image captured
+                                            or specified ring buffer index if given.
+  -S, --scale <scale_%%ge>                - With --image specify any scaling (in %%) to be applied to the image
+  -t, --timestamp [image_index]           - Output captured image timestamp, last image captured or specified
+                                            ring buffer index if given
+  -R, --read_index                        - Output ring buffer read index
+  -W, --write_index                       - Output ring buffer write index
+  -e, --event                             - Output last event index
+  -f, --fps                               - Output last Frames Per Second captured reading
+  -z, --zones                             - Write last captured image overlaid with zones to <monitor_name>-Zones.jpg
+  -a, --alarm                             - Force alarm in monitor, this will trigger recording until cancelled with -c
+  -n, --noalarm                           - Force no alarms in monitor, this will prevent alarms until cancelled with -c
+  -c, --cancel                            - Cancel a forced alarm/noalarm in monitor, required after being enabled with -a or -n
+  -L, --reload                            - Signal monitor to reload settings
+  -E, --enable                            - Enable detection, wake monitor up
+  -D, --disable                           - Disable detection, put monitor to sleep
+  -u, --suspend                           - Suspend detection, useful to prevent bogus alarms when panning etc
+  -r, --resume                            - Resume detection after a suspend
+  -U, --username <username>               - When running in authenticated mode the username and
+  -P, --password <password>               - password combination of the given user
+  -A, --auth <authentication>             - Pass authentication hash string instead of user details
+
+=cut
+
+*/
+
 #include <getopt.h>
 
 #include "zm.h"