Create the dwvsh(1) manual page

This patch adds a cursory man page for the dwvsh binary.

1 files changed, 132 insertions, 0 deletions

diff --git a/dist/man/dwvsh.1 b/dist/man/dwvsh.1
new file mode 100644
index 0000000..8a48043
--- /dev/null
+++ b/dist/man/dwvsh.1
@@ -0,0 +1,132 @@
+.Dd $Mdocdate: April 11 2024 $
+.Dt DWVSH 1
+.Os
+.Sh NAME
+.Nm dwvsh
+.Nd A (mostly) POSIX compliant shell
+.Sh SYNOPSIS
+.Nm
+.Op Ar file ...
+.Nm
+.Op Fl l
+.Sh DESCRIPTION
+.Nm
+is a (mostly) POSIX compliant shell, and tiny functional programming language
+for U**x-like operating systems.
+.Nm
+is designed to be fully compatible with
+.Xr bash 1 .
+See BUGS for more info on this.
+.Ss Builtin commands
+Currently,
+.Nm
+supports the following builtin commands:
+.Bl -tag -width "unalias" -compact
+.It Pa alias
+Allow users to define their own command aliases (i.e. alias vim=nvim).
+.It Pa cd
+Change directory.
+.It Pa exit
+Exit the shell.
+.It Pa export
+Set an environment variable, or list all environment variables.
+.It Pa source
+Run another shell script, retaining it's environment in the current shell.
+.It Pa unalias
+Clear a user defined command alias.
+.It Pa unset
+Clear an environment variable.
+.El
+.Ss Builtin command aliases
+.Bl -tag -width "unalias" -compact
+.It Pa quit
+Aliased to exit.
+.It Pa set
+Aliased to export.
+.El
+.Sh OPTIONS
+.Bl -tag -width 5n
+.It Fl l
+The shell is a login shell (only applicable if
+.Fl l
+is the only flag specified).
+.El
+.Sh FILES
+.Bl -tag -width "/etc/dwvshrc" -compact
+.It Pa /etc/dwvshrc
+Global RC file for
+.Nm ,
+always sourced when launched.
+.It Pa ~/.dwvshrc
+User defined RC file for
+.Nm ,
+may or may not exist.
+.El
+.Sh SEE ALSO
+.Xr bash 1 ,
+.Xr sh 1 ,
+.Sh EXAMPLES
+.Nm
+May be invoked with or without arguments. If ran with arguments, it will
+attempt to read and run the file(s) specified. If ran without arguments it will
+start up an interactive REPL.
+.Ss With arguments
+Imagine a file, hello.sh:
+.Bd -literal -offset indent
+#!/usr/bin/env sh
+echo 'Hello from dwvsh!'
+.Ed
+.Pp
+You can run this file with
+.Nm
+as shown below:
+.Bd -literal -offset indent
+$ dwvsh hello.sh
+Hello from dwvsh!
+.Ed
+.Pp
+Alternatively, you could change the first line of the script to:
+.Bd -literal -offset indent
+#!/usr/bin/env dwvsh
+.Ed
+.Pp
+Then simply call the script directly:
+.Bd -literal -offset indent
+$ chmod +x hello.sh
+$ ./hello.sh
+Hello from dwvsh!
+.Ed
+.Ss Without arguments
+This will start the read-eval-print-loop (REPL).
+The default/fallback prompt for
+.Nm
+is '|> ', but this may be changed by setting the PS1 environment variable, for
+instance:
+.Bd -literal -offset indent
+|> export PS1='$ '
+$ 
+.Ed
+.Sh BUGS
+.Nm
+is still in alpha, so it is missing a lot of functionality compared to
+.Xr bash 1 .
+.Pp
+In particular:
+.Pp
+- No way to redirect STDERR.
+.br
+- No builtin history.
+.br
+- Missing builtin commands (i.e. bind, etc).
+.br
+- No control flow.
+.br
+- No wildcards in paths.
+.br
+- No brace expansion in paths.
+.br
+- No tab autocompletion.
+.br
+- Man page and other documentation are woefully incomplete.
+.Sh AUTHORS
+.An Rory Dudley