Obligatory dotfiles repo
git clone git://
Log | Files | Refs

commit f87ecfadafaf1ba57fff764e76fd4b549224b7ae
parent 5b4913ef722d434ddce084ed59e0ce6aa054f680
Author: Daniel Moch <>
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.

A.local/man/man1/my.1 | 200+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
A.local/man/man5/my-open.config.5 | 47+++++++++++++++++++++++++++++++++++++++++++++++
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 +2. urxvtc (if urxvtd is available) +3. urxvt +4. xterm +5. xfce4-terminal +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)