Author: Daniel Moch <firstname.lastname@example.org>
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.
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"
+my \- utility functions for use across dotfiles and elsewhere
+\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.
+Command synopsis: \fBmy\fR \fBmailto\fR [\fIaddress\fR]\fR [\fIsubject\fR]
+Search DuckDuckGo in the terminal.
+Command synopsis: \fBmy\fR \fBsearch\fR [\fIterm\fR] (shell quoting rules apply)
+Open an X terminal window. This subcommand follows an order of preference for which
+terminal emulator is used.
+The current order is:
+2. urxvtc (if urxvtd is available)
+Lock the X session.
+Set the xroot color and, if available, set the wallpaper using the feh .fehbg command.
+Put the machine into hybrid-sleep mode.
+Shut down the machine.
+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.
+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
+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.
+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.
+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).
+Set X keyboard options.
+Set screen options. This is more or less deprecated in favor of autorandr(1).
+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).
+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
+Print an embeddable status message showing the remaining battery percentage, the current
+weather, and the time.
+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.
+An os-independent way to copy text from the terminal into the system clipboard.
+An os-independent way to paste text from the system clipboard into the terminal.
+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]
+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.
+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.
+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
+Recall that \fBinit\fR will either place an entry in the user crontab or create a user
+systemd timer to call \fBmy cron\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
+Calls \fBmy login_async\fR as a background job.
+List's the current users running processes.
+.SH EXIT STATUS
+\fISUBCOMMAND\fR executed successfully.
+Error executing \fISUBCOMMAND\fR.
+.SH SEE ALSO
+feh(1), chmod(1), my-open.config(5), pactl(1), autorandr(1), xbacklight(1), crontab(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"
+my-open.config \- terminal MIME handler database
+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
+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> ...]:
+\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.
+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
+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:
+.SH SEE ALSO