Add a man page for einfo.3

3 files changed, 206 insertions, 3 deletions

diff --git a/man/Makefile b/man/Makefile
index ddc38a9..70d4e1b 100644
--- a/man/Makefile
+++ b/man/Makefile
@@ -1,5 +1,16 @@
-DIR  = /usr/share/man/man8
-INC = $(CONTENTS) 
+DIR = /usr/share/man
+MAN3 = einfo.3
+MAN8 = start-stop-daemon.8 rc.8 rc-update.8 runscript.8 
 
 TOPDIR = ..
 include $(TOPDIR)/default.mk
+
+install::
+	$(INSTALL) -d $(DESTDIR)/$(DIR)/man3
+	for man in $(MAN3); do \
+		$(INSTALL) -m 0644 "$$man" $(DESTDIR)/$(DIR)/man3 || exit $$?; \
+	done	
+	$(INSTALL) -d $(DESTDIR)/$(DIR)/man8
+	for man in $(MAN8); do \
+		$(INSTALL) -m 0644 "$$man" $(DESTDIR)/$(DIR)/man8 || exit $$?; \
+	done	
diff --git a/man/einfo.3 b/man/einfo.3
new file mode 100644
index 0000000..7ea12d2
--- /dev/null
+++ b/man/einfo.3
@@ -0,0 +1,191 @@
+.\" Copyright 2007 Roy Marples
+.\" All rights reserved
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd Dec 24, 2007
+.Dt EINFO 3 SMM
+.Os OpenRC
+.Sh NAME
+.Nm einfo , ewarn , eerror , ebegin
+.Nm einfon , ewarnn , eerrorn , ebeginn ,
+.Nm einfov , ewarnv , ebeginv ,
+.Nm einfovn , ewarnvn , ebeginvn ,
+.Nm ewarnx , eerrorx ,
+.Nm eend , ewend ,
+.Nm eendv , ewendv ,
+.Nm eindent , eoutdent ,
+.Nm eindentv , eoutdentv ,
+.Nm eprefix
+.Nd colorful informational output
+.Sh LIBRARY
+Enhanced Informatation output library (libeinfo, -leinfo)
+.Sh SYNOPSIS
+.In einfo.h
+.Ft int Fn einfo "const char * restrict format" ...
+.Ft int Fn ewarn "const char * restrict format" ...
+.Ft int Fn eerror "const char * restrict format" ...
+.Ft int Fn ebegin "const char * restrict format" ...
+.Ft int Fn einfon "const char * restrict format" ...
+.Ft int Fn ewarnn "const char * restrict format" ...
+.Ft int Fn eerrorn "const char * restrict format" ...
+.Ft int Fn ebeginn "const char * restrict format" ...
+.Ft int Fn einfov "const char * restrict format" ...
+.Ft int Fn ewarnv "const char * restrict format" ...
+.Ft int Fn ebeginv "const char * restrict format" ...
+.Ft int Fn einfovn "const char * restrict format" ...
+.Ft int Fn ewarnvn "const char * restrict format" ...
+.Ft int Fn ebeginvn "const char * restrict format" ...
+.Ft int Fn ewarnx "const char * restrict format" ...
+.Ft int Fn eerrorx "const char * restrict format" ...
+.Ft int Fn eend "int retval" "const char * restrict format" ...
+.Ft int Fn ewend "int retval" "const char * restrict format" ...
+.Ft int Fn eendv "int retval" "const char * restrict format" ...
+.Ft int Fn ewendv "int retval" "const char * restrict format" ...
+.Ft void Fn eindent void
+.Ft void Fn eoutdent void
+.Ft void Fn eindentv void
+.Ft void Fn eoutdentv void
+.Ft void Fn eprefix "const char * prefix"
+.Sh DESCRIPTION
+The
+.Fn einfo
+family of functions provide a simple informational output that is colorised.
+Basically
+.Fn einfo ,
+.Fn ewarn
+and
+.Fn eerror
+behave exactly like
+.Fn printf
+but prefix the output with a colored *. The function called denotes the color
+used with
+.Fn einfo
+being green,
+.Fn ewarn
+being yellow and
+.Fn eerror
+being red. The number of real characters printed is returned.
+.Fn ebegin
+is identical to
+.Fn einfo
+except that 3 dots are appended to the output.
+.Pp
+.Fn einfov ,
+.Fn ewarnv
+and
+.Fn ebeginv
+work the same way to
+.Fn einfo ,
+.Fn ewarn ,
+and
+.Fn ebegin
+respectively, but only work when
+.Va EINFO_VERBOSE
+is true. You can also make the
+.Fn einfo ,
+.Fn ewarn ,
+and
+.Fn ebegin
+functions silent by setting
+.Va EINFO_QUIET
+to true.
+.Pp
+These functions are designed to output a whole line, so they also
+append a newline to the string. To stop this behaviour, you can use the
+functions
+.Fn einfon , 
+.Fn ewarnn ,
+.Fn eerrorn ,
+.Fn einfovn ,
+.Fn ewarnvn ,
+and
+.Fn ebeginvn .
+.Pp
+.Fn eend ,
+.Fn ewend ,
+.Fn eendv
+and
+.Fn ewendv
+are the counterparts to the above functions. If
+.Fa retval
+is zero then OK in green is printed in a bracket at the end of the prior
+line. Otherwise we print the formatted string using
+.Fn error
+(or
+.Fn ewarn
+if
+.Fn ewend
+is called) !! in red (or yellow if
+.Fn ewend
+is called) is printed in a bracket at the end of the line.
+The value of
+.Fa retval
+is returned.
+.Pp
+.Fn eindent
+indents subsequent calls to the above functions by 3 characters.
+.Fn eoutdent
+removes an
+.Fn eindent .
+.Fn eindentv
+and
+.Fn eoutdentv
+only work when
+.Va EINFO_VERBOSE
+is true.
+.Pp
+.Fn eprefix
+prefixes the string
+.Fa prefix
+to the above functions.
+.Sh IMPLEMENTATION NOTES
+einfo can optionally be linked against the
+.Lb libtermcap
+so that we can correctly query the connected console for our color and
+cursor escape codes.
+If not, then we have a hard coded list of terminals we know about that support
+the commonly used codes for color and cursor position.
+.Sh ENVIRONMENT
+.Va EINFO_QUIET
+when set to true makes the
+.Fn einfo
+and
+.Fn einfon
+family of functions quiet, so nothing is printed.
+.Pp
+.Va EINFO_VERBOSE
+when set to true makes the
+.Fn einfov
+and
+.Fn einfovn
+family of functions work, so they do print.
+.Sh FILES
+.Pa /etc/init.d/functions.sh
+is provided by OpenRC, which allows shell scripts to use the above functions.
+For historical reasons our verbose functions are prefixed with v instead of
+suffixed. So einfov becomes veinfo, einfovn becomes veinfon.
+Rinse and repeat for the other verbose functions.
+.Sh SEE ALSO
+.Xr printf 3 ,
+.Sh AUTHORS
+.An "Roy Marples" Aq roy@marples.name
diff --git a/man/runscript.8 b/man/runscript.8
index 31ddc59..7dbaeed 100644
--- a/man/runscript.8
+++ b/man/runscript.8
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd Dec 20, 2007
+.Dd Dec 24, 2007
 .Dt RUNSCRIPT 8 SMM
 .Os OpenRC
 .Sh NAME
@@ -363,6 +363,7 @@ show() {
 
 .Ed
 .Sh SEE ALSO
+.Xr einfo 3 ,
 .Xr rc 8 ,
 .Xr rc-status 8 ,
 .Xr rc-update 8 ,