changeset 18:480352307d89

docs: add initial documentation
author David Demelier <markand@malikania.fr>
date Thu, 09 Nov 2017 16:43:46 +0100
parents 33b2c65b64ea
children ea81d5b2c72e
files INSTALL.md Makefile doc/dmenu_bg.md doc/dmenu_filesel.md doc/dmenu_mpc.md doc/dmenu_power.md doc/dmenu_ssh.md doc/dmenutools.md
diffstat 8 files changed, 294 insertions(+), 7 deletions(-) [+]
line wrap: on
line diff
--- a/INSTALL.md	Thu Nov 09 15:40:05 2017 +0100
+++ b/INSTALL.md	Thu Nov 09 16:43:46 2017 +0100
@@ -6,7 +6,8 @@
 Requirements
 ------------
 
-  - POSIX compatible shell.
+  - POSIX compatible shell,
+  - Pandoc for the documentation.
 
 Basic installation
 ------------------
--- a/Makefile	Thu Nov 09 15:40:05 2017 +0100
+++ b/Makefile	Thu Nov 09 16:43:46 2017 +0100
@@ -15,10 +15,42 @@
 #
 
 PREFIX=/usr/local
+MANDIR=share/man
+DOCSRC=	doc/dmenu_bg.md		\
+	doc/dmenu_filesel.md	\
+	doc/dmenu_mpc.md	\
+	doc/dmenu_power.md	\
+	doc/dmenu_ssh.md	\
+	doc/dmenutools.md
+DOCOBJ=	${DOCSRC:.md=.1}
 
-install:
-	install -D -m 0755 bin/dmenu_bg ${PREFIX}/bin
-	install -D -m 0755 bin/dmenu_filesel ${PREFIX}/bin
-	install -D -m 0755 bin/dmenu_power ${PREFIX}/bin
-	install -D -m 0755 bin/dmenu_ssh ${PREFIX}/bin
-	install -D -m 0644 libexec/dmenutools/dmenu.subr ${PREFIX}/libexec/dmenutools/dmenu.subr
+all: docs
+
+%.1: %.md
+	@echo "  MAN $@"
+	@pandoc -s -f markdown -t man $< -o $@
+
+docs: ${DOCOBJ}
+
+install: ${DOCOBJ}
+	@install -D -m 0644 doc/dmenutools.1 ${PREFIX}/${MANDIR}/man1
+	@install -D -m 0644 libexec/dmenutools/dmenu.subr ${PREFIX}/libexec/dmenutools/dmenu.subr
+	@echo "  INSTALL dmenu_bg"
+	@install -D -m 0755 bin/dmenu_bg ${PREFIX}/bin
+	@install -D -m 0644 doc/dmenu_bg.1 ${PREFIX}/${MANDIR}/man1
+	@echo "  INSTALL dmenu_filesel"
+	@install -D -m 0755 bin/dmenu_filesel ${PREFIX}/bin
+	@install -D -m 0644 doc/dmenu_filesel.1 ${PREFIX}/${MANDIR}/man1
+	@echo "  INSTALL dmenu_mpc"
+	@install -D -m 0755 bin/dmenu_mpc ${PREFIX}/bin
+	@install -D -m 0644 doc/dmenu_mpc.1 ${PREFIX}/${MANDIR}/man1
+	@echo "  INSTALL dmenu_power"
+	@install -D -m 0755 bin/dmenu_power ${PREFIX}/bin
+	@install -D -m 0644 doc/dmenu_power.1 ${PREFIX}/${MANDIR}/man1
+	@echo "  INSTALL dmenu_ssh"
+	@install -D -m 0755 bin/dmenu_ssh ${PREFIX}/bin
+	@install -D -m 0644 doc/dmenu_ssh.1 ${PREFIX}/${MANDIR}/man1
+
+
+clean:
+	@rm -f ${DOCOBJ}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/dmenu_bg.md	Thu Nov 09 16:43:46 2017 +0100
@@ -0,0 +1,35 @@
+% DMENU_BG(1)
+% David Demelier <markand@malikania.fr>
+% November 2017
+
+# NAME
+
+dmenu_bg - select a background
+
+# SYNOPSIS
+
+**dmenu\_bg** [directory]
+
+# DESCRIPTION
+
+Open `dmenu_filesel` to select a file and apply it as background.
+
+# CONFIGURATION
+
+The following options are available in **dmenutools.conf**:
+
+**bg_directory**
+:	Select a directory, by default the script will check for `XDG_PICTURES_DIR`
+	environment variable and `$HOME` if none are set.
+
+**bg_cmd**
+:	Configure the tool to apply the wallpaper. If empty `dmenu_bg` will try
+    `feh`, `hsetroot` and `fbsetbg`.
+
+**bg_lines**
+:	How many lines to print for each files (Default: 16).
+
+# SEE ALSO
+
+`dmenutools`(1),
+`dmenu`(1).
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/dmenu_filesel.md	Thu Nov 09 16:43:46 2017 +0100
@@ -0,0 +1,32 @@
+% DMENU_FILESEL(1)
+% David Demelier <markand@malikania.fr>
+% November 2017
+
+# NAME
+
+dmenu_filesel - convenient dmenu file selector
+
+# SYNOPSIS
+
+**dmenu_filesel** [-l lines] [-t file|directory] [-p pattern] [directory]
+
+# DESCRIPTION
+
+Opens a dmenu tree to walk around the file system hierarchy.
+
+The following options are available:
+
+**-l lines**:
+:	Specify the amount of lines to show (Default: 16).
+
+**-t type**:
+:	Specify a type of file to select, if directory is specified, files will not
+	be displayed (Default: file).
+
+**-p pattern**:
+:	Set a file pattern to match. This option uses `egrep` to check matches.
+
+# SEE ALSO
+
+`dmenutools`(1),
+`dmenu`(1).
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/dmenu_mpc.md	Thu Nov 09 16:43:46 2017 +0100
@@ -0,0 +1,44 @@
+% DMENU_MPD(1)
+% David Demelier <markand@malikania.fr>
+% November 2017
+
+# NAME
+
+dmenu_mpc - control music player daemon
+
+# SYNOPSIS
+
+**dmenu_mpc**
+
+# DESCRIPTION
+
+This dmenu tool let you control your music player daemon.
+
+You can control the song queue with basic functions such as, play, pause, stop,
+previous, next. You can also add songs using a dmenu tree selector.
+
+To select a whole directory, opens it and use '.' on it like this:
+
+    a
+    a/.
+    a/..
+    a/b
+    a/b/.   # select this line if you want to play the whole 'b' tree.
+    a/b/..
+    a/b/c
+
+# CONFIGURATION
+
+The following options are available in **dmenutools.conf**:
+
+**mpc_host**
+:	Hostname to connect, checked after `MPD_HOST` environment variable.
+
+**mpc_port**
+:	Port to use, checked after `MPD_PORT` environment variable.
+
+# SEE ALSO
+
+`dmenutools`(1),
+`dmenu`(1),
+`mpc`(1).
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/dmenu_power.md	Thu Nov 09 16:43:46 2017 +0100
@@ -0,0 +1,57 @@
+% DMENU_POWER(1)
+% David Demelier <markand@malikania.fr>
+% November 2017
+
+# NAME
+
+dmenu_power - turn off the system
+
+# SYNOPSIS
+
+**dmenu_power**
+
+# DESCRIPTION
+
+Show a menu to turn off the system and execute predefined actions.
+
+# CONFIGURATION
+
+By default, `dmenu_power` will propose to hibernate, shutdown, suspend and
+reboot. All these action can be disabled with the following options:
+
+**power_hibernate_enable**
+:	Set to 0 to disable this menu entry (Default: 1).
+
+**power_shutdown_enable**
+:	Set to 0 to disable this menu entry (Default: 1).
+
+**power_suspend_enable**
+:	Set to 0 to disable this menu entry (Default: 1).
+
+**power_reboot_enable**
+:	Set to 0 to disable this menu entry (Default: 1).
+
+All commands use defaults on appropriate system if available, it's possible to
+override them with the following options:
+
+**power_hibernate_cmd**
+:	Command to execute for hibernation.
+
+**power_shutdown_cmd**
+:	Command to execute to poweroff the system.
+
+**power_suspend_cmd**
+:	Command to execute to suspend the system.
+
+**power_reboot_cmd**
+:	Command to execute to reboot the system.
+
+# SECURITY
+
+This script uses `sudo -A` to execute commands, see `dmenutools(1)` to specify
+an optional sudo agent.
+
+# SEE ALSO
+
+`dmenutools`(1),
+`dmenu`(1).
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/dmenu_ssh.md	Thu Nov 09 16:43:46 2017 +0100
@@ -0,0 +1,30 @@
+% DMENU_SSH(1)
+% David Demelier <markand@malikania.fr>
+% November 2017
+
+# NAME
+
+dmenu_ssh - open a ssh session
+
+# SYNOPSIS
+
+**dmenu\_ssh**
+
+# DESCRIPTION
+
+This dmenu tool shows a list of configured ssh hosts in your
+**$HOME/.ssh/config** file and open a terminal to connect to it.
+
+You need to specify some hostnames in your **$HOME/.ssh/config** like this:
+
+    Host foo.org
+	Host example.org
+
+# CONFIGURATION
+
+The **dmenu_ssh** use the `term` option in **dmenutools.conf**.
+
+# SEE ALSO
+
+`dmenutools`(1),
+`dmenu`(1).
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/dmenutools.md	Thu Nov 09 16:43:46 2017 +0100
@@ -0,0 +1,56 @@
+% DMENUTOOLS(1)
+% David Demelier <markand@malikania.fr>
+% November 2017
+
+# NAME
+
+dmenutools - a set of dmenu utilities
+
+# DESCRIPTION
+
+A collection of utilities for `dmenu` to complete your window manager
+installation.
+
+# CONFIGURATION
+
+The dmenutools collection can be configured through a **dmenutools.conf** file
+read from the following paths:
+
+  - $XDG_CONFIG_HOME/dmenutools.conf
+  - $HOME/.config/dmenutools.conf
+
+The file is sourced from shell scripts so it can contain valid shell code. All
+modules may specify additional options, see their documentation.
+
+The following options are common to all:
+
+**term**
+:	A terminal to use, if empty several terminals are tested including xterm,
+	urxvt, gnome-terminal, st.
+
+# SUDO AGENT
+
+Some scripts may use `sudo -A` which can use an external tool to ask for user
+password. This means that you can use `dmenu` to prompt for a password to
+execute root commands.
+
+If you use sudo without a password, you have nothing else to do, otherwise, you
+can read the following section to enable a dmenu prompt.
+
+Create a `dmenu_sudo` script like this:
+
+	#!/bin/sh
+	# Use same color for foreground/background to hide your prompt.
+    dmenu -nb "black" -nf "black" <&- && echo
+
+Don't forget to make it executable:
+
+	chmod +x dmenu_sudo
+
+Then, fill the `SUDO_ASKPASS` variable to point to this executable:
+
+	export SUDO_ASKPASS=/usr/local/bin/dmenu_sudo
+
+# SEE ALSO
+
+`dmenu`(1).