From fcb7ab641cc974d26b419658bf740dbc1168f935 Mon Sep 17 00:00:00 2001 From: Roy Marples Date: Mon, 24 Dec 2007 11:48:33 +0000 Subject: Add a man page for einfo.3 --- man/Makefile | 15 ++++- man/einfo.3 | 191 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ man/runscript.8 | 3 +- 3 files changed, 206 insertions(+), 3 deletions(-) create mode 100644 man/einfo.3 (limited to 'man') diff --git a/man/Makefile b/man/Makefile index ddc38a9b..70d4e1b8 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 00000000..7ea12d27 --- /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 31ddc59f..7dbaeed3 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 , -- cgit v1.2.3