commit d1d4abb2fb37e87cc5bcb83c41cc9939b91c4197
parent a42e277a4aafa71735fa109e8668b45fc618516c
Author: Jacob R. Edwards <jacob@jacobedwards.org>
Date: Fri, 26 May 2023 09:06:34 -0700
Add manuals for aps and apc
Diffstat:
7 files changed, 298 insertions(+), 2 deletions(-)
diff --git a/apc/Makefile b/apc/Makefile
@@ -2,5 +2,6 @@ name = apc
src = apc.c
ldlibs = ../lib/ap/libap.a
cflags = -I../lib
+man = ../man/apc.1
.include "../mk/exe.mk"
diff --git a/aps/Makefile b/aps/Makefile
@@ -4,6 +4,7 @@ src = aps.c arg.c buf.c bug.c command.c find.c log.c main.c player.c \
inc = ${src:.c=.h} util.h
ldlibs = ../lib/ap/libap.a
cflags = -I../lib
+man = ../man/aps.1
.include "../mk/exe.mk"
diff --git a/config.mk b/config.mk
@@ -4,3 +4,4 @@ CFLAGS = -Wall -Wno-write-strings ${cflags}
LDFLAGS = ${ldflags}
LDLIBS = ${ldlibs}
PREFIX = /usr/local
+MANPREFIX = ${PREFIX}/man
diff --git a/man/apc.1 b/man/apc.1
@@ -0,0 +1,65 @@
+.Dd May 26, 2023
+.Dt APC 1
+.Os
+.Sh NAME
+.Nm apc
+.Nd audio player client
+.Sh SYNOPSIS
+.Nm apc
+.Op Ar command Op Ar arguments ...
+.Sh DESCRIPTION
+The
+.Nm
+utility connects to
+.Xr aps 1
+and sends the given commands, printing their output (with the
+exception of the status line which, if
+.Sq ok ,
+is suppressed.)
+.Pp
+A command passed as arguments to
+.Nm
+is processed as described in
+.Sx "Caret Handling" ,
+if no command is given as an argument,
+.Nm
+reads commands from the standard input until EOF occurs.
+.Ss Caret Handling
+If caret
+.Sq ( ^ )
+is the first character that appears in the final argument given to
+.Nm apc ,
+it is removed. If there are no more characters in the argument, the
+argument is replaced by arguments taken from the standard input,
+one per line, until EOF is encountered. (It is an error to have no
+arguments from stdin in this case.)
+.Sh ENVIRONMENT
+.Bl -tag -width apsock
+.It Ev apsock
+The path to the socket used to connect to
+.Xr aps 1 .
+If
+.Ev apsock
+is not set,
+.Pa /tmp/aps
+is used.
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+Sort the items in the queue:
+.Dl $ apc list | sort | apc truncate ^
+.Pp
+Reorder items matching
+.Sq regex
+to come next in the queue:
+.Dl $ apc remove /regex | apc add ^
+.Pp
+Add
+.Sq ^caret
+to the queue:
+.Dl $ apc add ^^caret
+.Sh SEE ALSO
+.Xr aps 1
+.Sh AUTHORS
+.An Jacob R. Edwards Aq Mt jacob@jacobedwards.org
diff --git a/man/aps.1 b/man/aps.1
@@ -0,0 +1,216 @@
+.Dd May 26, 2023
+.Dt APS 1
+.Os
+.Sh NAME
+.Nm aps
+.Nd audio player server
+.Sh SYNOPSIS
+.Nm aps
+.Sh DESCRIPTION
+.\" Items can be added to or removed from the queue using commands
+The
+.Nm
+server maintains a queue of names and manages the player. When the
+first item is added to the queue, the player is executed with that
+item as it's final argument, if the player then exits with a status
+of zero, the player is executed again on the next item in the queue.
+This loop goes on until the player fails or a command like
+.Sx stop
+is issued: the queue is circularly linked.
+.Pp
+.Nm
+listens for clients on a UNIX socket bound to
+.Pa /tmp/aps
+(but see
+.Sx ENVIRONMENT ) .
+Once
+.Nm
+is fully initialized and listening for clients, it will
+.Xr fork 2
+and
+.Xr exit 2 .
+Utilizing this, it's easy to know when you can issue commands as
+shown in the
+.Sx EXAMPLES .
+.Pp
+After a client is accepted,
+.Nm
+waits for a command (as described in
+.Sx "Command Syntax" )
+to be sent, and, once received, executes responds with it's output
+and return status, detailed in
+.Sx Responses .
+.Pp
+The available commands, their arguments, and their functions are
+listed below:
+.Bl -tag -width indent
+.It Cm add Op Ar name ...
+Add the given names to the queue.
+.It Cm close
+Prevent new clients from connecting by removing the bound socket
+and close down the server when all existing clients disconnect.
+This is equivalent to manually removing the socket with a tool such
+as
+.Xr rm 1 .
+.It Cm commands
+List all the commands the server supports.
+.It Cm list Op Ar pattern
+List items in the queue. If
+.Ar pattern
+is present, only list items which match the pattern (see
+.Sx Patterns ) .
+.It Cm log Oo Ar "" "!" Oc Oo Ar level ... Oc
+Only log entries of the given log levels, or only log entries that
+are not the given log levels if the negation operator is provided
+.Sq ( "!" ) .
+This command is likely to change significantly in the future.
+.It Cm name
+Returns the name of the current item in the queue. Equivalent to
+.Do
+.Sx list
+0
+.Dc .
+May be removed in the future.
+.It Cm next
+Play the next item in the queue.
+.It Cm pause
+Pause the player (by sending
+.Dv SIGSTOP ) .
+.It Cm play Op Ar pattern
+Play the current item (by either spawning a new one, or by sending
+.Dv SIGCONT
+if one already exists). If
+.Ar pattern
+is given, first seek to the first item
+.Ar pattern
+matches.
+.It Cm player Op Ar player Op Ar argument ...
+Get or set the player. With no arguments, the current player command
+is returned, otherwise the player is set to the given arguments.
+.It Cm previous
+Play the previous item in the queue.
+.It Cm remove Op Ar pattern
+Remove the items matching
+.Ar pattern
+from the queue, returning the items removed. If no pattern is
+given, remove only the current item.
+.It Cm seek Ar pattern
+Seek to the first item which matches
+.Ar pattern .
+.It Cm status
+Return the player status. (See
+.Sx "Player Status" ) .
+.It Cm stop
+Stop the player by sending
+.Dv SIGTERM .
+After the signal is sent, the player process may continue to exist,
+but is ignored.
+.It Cm terminate
+Forcefully close down the server giving clients no warning.
+.It Cm toggle
+If the player is running, pause it; otherwise play it. The player
+status is returned on success. (See
+.Sx "Player Status" ) .
+.It Cm truncate Op Ar name ...
+Replace all the items in the queue with the names specified, or,
+if no names are specified, the current item.
+.El
+.Ss Command Syntax
+Commands are line delimited; command arguments are whitespace
+separated, but may be quoted as described in
+.Sx Quoting
+to include whitespace.
+.Ss Responses
+Responses consist of zero or more lines (the command output) followed
+by a status line. A status line can either be
+.Sq ok ,
+for successful completion of the command, or
+.Sq error:
+followed by an error message if there was an issue.
+.Pp
+If a line which would be interpreted as a status line is output by
+the command, it will be quoted before being sent. (See
+.Sx Quoting . )
+.Pp
+Multi-word lines are currently possible, but only occur in the
+player command and may be removed in the future.
+.Ss Quoting
+Quoting works as in the
+.Xr rc 1
+shell from plan9/9front: Single quotes surround the string. To
+insert a single quote into the string, put two together.
+.Ss Patterns
+There are three types of patterns: numeric, regex, and string.
+.Pp
+Numeric patterns begin with a digit or minus. A single number or a
+comma separated range may be provided. Numbers refer to the offset
+from the current item, making zero the current item. Ranges are
+inclusive.
+.Pp
+Regular expression patterns begin with a slash
+.Sq ( "/" )
+(forward-searching) or a question mark
+.Sq ( "?" )
+(backward-searching), or an exclamation point
+.Sq ( "!" )
+followed by a slash or question mark to negate the result. The
+regular expression is extended and ignores case distinctions,
+additionally, if prefixed
+.Pp
+String expressions begin with a double quote
+.Sq ( \\" )
+and only match items which match it exactly.
+.Ss Player Status
+The player status can be one of
+.Bl -tag -width suspended
+.It off
+The player is not alive, but will be started when possible.
+.It running
+The player is currently running.
+.It stopped
+The player is not alive, and will not be started without manual
+intervention (such as with
+.Sx play ) .
+.It suspended
+The player is alive, but not running; the result of receiving
+.Dv SIGTSTP
+or
+.Dv SIGSTOP .
+.It failure
+The player either exited non-zero or terminated abnormally due to
+a signal.
+.It complete
+Like the off status, but indicates that the previous process had
+an exit status of 0.
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width apsock
+.It Ev apsock
+The path to the socket used to connect to
+.Xr aps 1 .
+If
+.Ev apsock
+is not set,
+.Pa /tmp/aps
+is used.
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+Log to
+.Pa /tmp/apslog :
+.Dl $ aps 2>/tmp/apslog
+.Pp
+Add items to the queue once
+.Nm
+is up and running:
+.Dl $ aps && apc add foo bar baz
+.Sh SECURITY CONSIDERATIONS
+The player can be changed to be any program using the
+.Sx player
+command, so anyone with access to the socket can execute an arbitrary
+program as the server.
+.Sh SEE ALSO
+.Xr apc 1
+.Sh AUTHORS
+.An Jacob R. Edwards Aq Mt jacob@jacobedwards.org
diff --git a/mk/exe.mk b/mk/exe.mk
@@ -1,12 +1,13 @@
.include "c.mk"
+.include "man.mk"
${name}: ${lib}
${CC} ${LDFLAGS} -o ${name} ${obj} ${LDLIBS}
-install: ${name}
+install: ${name} installman
cp -f ${name} ${PREFIX}/bin/${name}
-uninstall:
+uninstall: uninstallman
rm -f ${PREFIX}/bin/${name}
clean:
diff --git a/mk/man.mk b/mk/man.mk
@@ -0,0 +1,11 @@
+installman:
+ for m in ${man}; do \
+ cp -f "$$m" "${MANPREFIX}/man$${m##*.}/$${m##*/}" ;\
+ done
+
+uninstallman:
+ for m in ${man}; do \
+ rm -f "${MANPREFIX}/man$${m##*.}/$${m##*/}" ;\
+ done
+
+.PHONY: installman uninstallman
