commit f87ecfadafaf1ba57fff764e76fd4b549224b7ae
parent 5b4913ef722d434ddce084ed59e0ce6aa054f680
Author: Daniel Moch <daniel@danielmoch.com>
Date: Sun, 22 Sep 2019 06:49:15 -0400
Add My manual pages
I had been documenting these in a weak form in shell completion
scripts. But this ends up being easier and more portable.
Diffstat:
2 files changed, 247 insertions(+), 0 deletions(-)
diff --git a/.local/man/man1/my.1 b/.local/man/man1/my.1
@@ -0,0 +1,200 @@
+.TH MY 1 "September 2019" "djmoch 0.0" "DJMOCH Commands Manual"
+.SH NAME
+my \- utility functions for use across dotfiles and elsewhere
+.SH SYNOPSIS
+.B my
+\fI\,SUBCOMMAND\/\fR [\fI\,ARGS\/\fR]
+.SH DESCRIPTION
+\fBmy\fR runs the subcommand specified by \fISUBCOMMAND\/\fR, passing any provided
+\fIARGS\/\fR along. Many of the available subcommands amount to a list of providers
+which are searched in the $PATH, with the first one found being executed. This
+design allows for dotfiles to port across machines with relative ease.
+.SH SUBCOMMANDS
+.PP
+.TP
+\fBmailto\fR
+Send email.
+
+Command synopsis: \fBmy\fR \fBmailto\fR [\fIaddress\fR]\fR [\fIsubject\fR]
+.TP
+\fBsearch\fR
+Search DuckDuckGo in the terminal.
+
+Command synopsis: \fBmy\fR \fBsearch\fR [\fIterm\fR] (shell quoting rules apply)
+.TP
+\fBterm\fR
+Open an X terminal window. This subcommand follows an order of preference for which
+terminal emulator is used.
+
+The current order is:
+
+1. st
+.br
+2. urxvtc (if urxvtd is available)
+.br
+3. urxvt
+.br
+4. xterm
+.br
+5. xfce4-terminal
+.br
+6. gnome-terminal
+.TP
+\fBlock\fR
+Lock the X session.
+.TP
+\fBwallpaper\fR
+Set the xroot color and, if available, set the wallpaper using the feh .fehbg command.
+.TP
+\fBstandby\fR
+Put the machine into hybrid-sleep mode.
+.TP
+\fBshutdown\fR
+Shut down the machine.
+.TP
+\fBperms\fR
+Search for all of the files in \fIHOME\fR beginning with a dot (i.e., a dotfile) and
+sets its permissions via chmod to be inaccessible to everyone except the file owner.
+.TP
+\fBinit\fR
+Perform initializations necessary for "moving in."
+
+Command synopsis: \fBmy\fR \fBinit\fR [\fI\-f\fR][\fI\-c\fR]
+
+When run with \fI\-f\fR, the command is forced to run completely, even if it has
+already been run. When run with \fI\-c\fR, the user crontab is also initialized.
+
+In addition to optionally initializing the crontab, init initializes custom termcaps, .less, ensures
+the login shell is set to /bin/sh, creates an autostart entry for an available screen locker based
+on a preference list and availability in \fIPATH\fR, and initializes gpg-agent.conf to point to the
+correct pinentry program. Finally, init creates several folders required for proper behavior of
+dotfiles.
+
+When complete, init touches the file $HOME/._.djmoch to act as a flag for the last time the dotfiles
+where updated/initialized. See the \fBlogin\fR subcommand for more details of how this file is used.
+.TP
+\fBopen\fR
+Open a file in the configured XDG handler specific to the file's MIME type, or, optionally, in a
+configured terminal handler.
+
+Command synopsis: \fBmy\fR \fBopen\fR [\fI\-T\fR] \fIFILE\fR
+
+When the \fI\-T\fR flag is provided, the file is opened in a terminal handler configured in a
+different file. See my-open.config(5) for more information an how to configure terminal handlers.
+.TP
+\fBsound\fR
+Adjust the sound settings or display sound status.
+
+Command synopsis: \fBmy\fR \fBsound\fR [\fIstatus\fR] ...
+
+If the \fIstatus\fR action is provided, then the current status of the sound sinks and sources
+is put out. If the status is not requested, then other command arguments should be provided
+according to pactl(1).
+.TP
+\fBkbopts\fR
+Set X keyboard options.
+.TP
+\fBscreen\fR
+Set screen options. This is more or less deprecated in favor of autorandr(1).
+.TP
+\fBbrightness\fR
+Sets the brightness of the provided monitor using the xbacklight(1) utility.
+
+Command synopsis: \fBmy\fR \fBbrightness\fR \fICTRL\fR ...
+
+The \fICTRL\fR argument should be the name of an attached display device, or the generic
+argument "monitor," which simply looks determines the name of the (only) attached display
+device. The remaider of the command arguments follow the description in xbacklight(1).
+.TP
+\fBbattery\fR
+Show information about the battery.
+
+Command synopsis: \fBmy\fR \fBbattery\fR [\fIremaining\fR][\fItotal\fR][\fIpercent\fR]
+
+The \fIpercent\fR argument will probably be the only one of any interest. The others are
+used internally to calculate the percent, and their representation is dependent on the
+operating system.
+.TP
+\fBstatus\fR
+Print an embeddable status message showing the remaining battery percentage, the current
+weather, and the time.
+.TP
+\fBi3status\fR
+Same as status, but automatically prints the status to stdout every 15 seconds, allowing
+it to be used in the status bar of the i3 window manager.
+.TP
+\fBcopy\fR
+An os-independent way to copy text from the terminal into the system clipboard.
+.TP
+\fBpaste\fR
+An os-independent way to paste text from the system clipboard into the terminal.
+.TP
+\fBnetrc\fR
+Parses netrc to return username/password information for use in configuration files or
+anywhere a service credential might be required. Note that this subcommand calls out
+to a handler written in Python.
+
+Command synopsis: \fBmy\fR \fBnetrc\fR \fI<server>\fR [\fIlogin\fR][\fIaccount\fR]
+[\fIpassword\fR]
+
+The \fIserver\fR argument should be the fully-qualified domian name of the server whose
+credential is being requested. One of the three optional arguments, \fIlogin\fR,
+\fIaccount\fR, or \fIpassword\fR may also be provided, in which case only that portion
+of the credential will be provided. If none of the optional arguments are provided, then
+all three will be returned. All responses are provided on stdout.
+.TP
+\fBdotfiles\fR
+Perform one of several maintanence actions on the dotfiles.
+
+Command synopsis: \fBmy\fR \fBdotfiles\fR <\fIargument\fR>
+
+\fIargument\fR may be one of \fIcheck\fR, in which case the ._.djmoch file in consulted
+to see when the dotfiles were last updated, or \fIupdate\fR, in which case the dotfiles
+are actually updated. Whether or not \fIupdate\fR actually does anything is conditioned
+on whether the dotfiles are sourced from a tarfile. If the dotfiles are sourced from a
+Git repository, then \fIupdate\fR does nothing.
+.TP
+\fBcron\fR
+Run configured cron tasks. This subcommand should be called either from a user crontab
+or a user systemd timer.
+
+Command synopsis: \fBmy\fR \fBcron\fR [\fIsystemd\fR]
+
+If the \fIsystemd\fR argument is provided, then the job output is sent to stdout,
+otherwise no output is given.
+
+Any script located in $HOME/.local/lib/cron.d (either physically or via link) will be
+executed. Note that cron scripts that are included in the dotfiles are located in
+$HOME/.local/lib/cron.avail and must be linked into cron.d before they will be
+activated.
+
+Recall that \fBinit\fR will either place an entry in the user crontab or create a user
+systemd timer to call \fBmy cron\fR.
+.TP
+\fBlogin_async\fR
+This should really be called login_sync, since it is the synchronous (i.e. blocking)
+version of the login command (see \fBmy login\fR to run as a background job).
+
+\fBlogin_async\fR will attempt to contact the dotfiles server for up to two minutes
+from the point it is called. If it is able to make contact, it consults the ._.djmoch
+file to see if the dotfiles have to updated in the past week. If not, it calls \fBmy
+dotfiles update\fR.
+.TP
+\fBlogin\fR
+Calls \fBmy login_async\fR as a background job.
+.TP
+\fBprocesses\fR
+List's the current users running processes.
+.PP
+.SH EXIT STATUS
+.PP
+.TP
+\fB0\fR
+\fISUBCOMMAND\fR executed successfully.
+.TP
+\fB1\fR
+Error executing \fISUBCOMMAND\fR.
+.PP
+.SH SEE ALSO
+feh(1), chmod(1), my-open.config(5), pactl(1), autorandr(1), xbacklight(1), crontab(5),
+systemd.timer(5)
diff --git a/.local/man/man5/my-open.config.5 b/.local/man/man5/my-open.config.5
@@ -0,0 +1,47 @@
+.TH MY-OPEN.CONFIG 5 "September 2019" "djmoch 0.0" "DJMOCH Programmers Manual"
+.SH NAME
+my-open.config \- terminal MIME handler database
+.SH DESCRIPTION
+When \fBmy open\fR is called with the \fI-T\fR flag, the my-open.config file
+is consulted to determine which handler to use for the requested file's
+MIME type.
+
+The file is assumed to contain multiple rows, with each row constituting one
+entry, that is, one MIME type. Similar to the mailcap(4) file, the second
+element of a MIME type may be a wildcard, while the first element may not.
+
+Each entry in my-open.config should follow the format:
+
+<\fImimetype\fR>:<\fIdefault\fR> [<\fIfallback1\fR> <\fIfallback2\fR> ...]:
+\fIfmt\fR
+
+\fImimtype\fR specifies the MIME type of the file. \fIdefault\fR specifies the
+default handler for the given MIME type. The optional \fIfallback\fR arguments
+specify fallback handlers to use if the default is not available. \fIfmt\fR
+describes how the arguments provided to \fBmy open\fR should be passed along
+to the handler. A value of %s for \fIfmt\fR passes the provided file name along
+with no additional arguments.
+
+.SH EXAMPLES
+.PP
+.TP
+text/html:w3m:-T text/html %s
+For files of text/html MIME type, use w3m to open the file in the terminal. The
+resulting command line will look like:
+
+w3m -T text/html \fIfilename\fR
+.TP
+x-scheme-handler/*:w3m lynx:%s
+For files of any x-scheme-handler MIME type, use either w3m or lynx to open the
+file in the terminal (preferring w3m). The resulting command line will look like:
+
+w3m|lynx \fIfilename\fR
+.PP
+.SH FILES
+$XDG_CONFIG_HOME/my-open/config
+
+or
+
+$HOME/.config/my-open/config
+.SH SEE ALSO
+my(1)
