From efa999932c739a1c7418d9b45deedf1444a63328 Mon Sep 17 00:00:00 2001 From: Ammon Smith Date: Thu, 23 Jun 2016 01:08:14 -0700 Subject: [PATCH] Add initial man pages. --- man/.gitignore | 7 +++ man/Makefile | 47 ++++++++++++++++ man/lemonbuddy.1 | 38 +++++++++++++ man/lemonbuddy_config.5 | 112 +++++++++++++++++++++++++++++++++++++ man/lemonbuddy_terminate.1 | 14 +++++ man/lemonbuddy_wrapper.1 | 18 ++++++ 6 files changed, 236 insertions(+) create mode 100644 man/.gitignore create mode 100644 man/Makefile create mode 100644 man/lemonbuddy.1 create mode 100644 man/lemonbuddy_config.5 create mode 100644 man/lemonbuddy_terminate.1 create mode 100644 man/lemonbuddy_wrapper.1 diff --git a/man/.gitignore b/man/.gitignore new file mode 100644 index 00000000..3ca51ada --- /dev/null +++ b/man/.gitignore @@ -0,0 +1,7 @@ +*.gz +*.ps +*.pdf + +.*.swp +*~ + diff --git a/man/Makefile b/man/Makefile new file mode 100644 index 00000000..bb6963fa --- /dev/null +++ b/man/Makefile @@ -0,0 +1,47 @@ +.PHONY: all pdf release update-versions clean + +# Constant declarations +PROGRAM_NAME = lemonbuddy +VERSION = $(shell git describe --tags) + +# Sources +MAN_SOURCES = $(wildcard *.1 *.5) +GZ_FILES = $(addsuffix .gz,$(MAN_SOURCES)) +PS_FILES = $(addsuffix .ps,$(MAN_SOURCES)) +PDF_TARGET = $(PROGRAM_NAME).pdf + +# Targets +all: $(GZ_FILES) $(PDF_TARGET) +pdf: $(PDF_TARGET) +release: clean update-versions all + +# Program targets +update-versions: + @sed -i '1 s/"$(PROGRAM_NAME) [^"]*?"/"$(PROGRAM_NAME) VERSION"/' $(MAN_SOURCES) + +# Documentation targets +%.1.gz: %.1 + @echo '[GZ] $(notdir $@)' + @gzip -c $< > $@ + +%.5.gz: %.5 + @echo '[GZ] $(notdir $@)' + @gzip -c $< > $@ + +%.1.ps: %.1 + @echo '[PS] $(notdir $@)' + @groff -Tps -mandoc $< > $@ + +%.5.ps: %.5 + @echo '[PS] $(notdir $@)' + @groff -Tps -mandoc $< > $@ + +$(PDF_TARGET): $(PS_FILES) + @echo '[PDF] $(notdir $@)' + @gs -q -sPAPERSIZE=letter -dNOPAUSE -dBATCH -sDEVICE=pdfwrite \ + -sOutputFile=$@ $^ + +clean: + @echo '[CLEAN]' + @rm -f $(GZ_FILES) $(PS_FILES) $(PDF_TARGET) + diff --git a/man/lemonbuddy.1 b/man/lemonbuddy.1 new file mode 100644 index 00000000..f5146baa --- /dev/null +++ b/man/lemonbuddy.1 @@ -0,0 +1,38 @@ +.TH LEMONBUDDY 1 2016-06-22 "lemonbuddy 1.2.1" "lemonbuddy Manual" +.SH NAME +\fBlemonbuddy\fR \- A fast and easy-to-use tool for Lemonbar. +.SH SYNOPSIS +.P +lemonbuddy [\fIBAR\-NAME\fR] [\fB\-c\fR \fICONFIG\-FILE\fR] [\fB\-p\fR \fIPIPE\fR] [\fB\-l\fR \fILOG\-LEVEL\fR] [\fB\-d\fR \fIPARAM\fR] [\fB\-x\fR] [\fB\-w\fR] +.P +lemonbuddy [\fB\-h\fR | \fB\-\-help\fR] +.SH DESCRIPTION +\fBLemonbuddy\fR aims to help users build beautiful and highly customizable status bars without messing with named pipes, MacGyver-like scripting or non-blocking loops lobotomizing your CPU. +.P +Please not that the project is still in early development, so please report any anomalies by creating an issue on GitHub (\fIhttps://github.com/jaagr/lemonbuddy\fR). +.P +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-h\fR, \fB\-\-help\fR +Show help and program options. +.TP +\fB\-c\fR, \fB\-\-config\fR=\fICONFIG\-FILE\fR +Specify the path to the configuration file. By default, configuration files are read from \fI$XDG_CONFIG_HOME/.config/lemonbuddy\fR. When the \fI$XDG_CONFIG_HOME\fR variable is absent, then \fI~/.config/lemonbuddy\fR directory is used instead. +.TP +\fB\-p\fR, \fB\-\-pipe\fR=\fIPIPE\fR +Specify an alternate input pipe. This pipe is used by \fBlemonbuddy\fR to communicate with \fBlemonbar\fR. For more information on named pipes, see \fBmkfifo\fR(1). +.TP +\fB\-l\fR, \fB\-\-log\fR=\fILEVEL\fR +Set how verbose \fBlemonbuddy\fR's logging is. \fILEVEL\fR must be one of: `warning', `info', `debug', or `trace'. +.TP +\fB\-d\fR, \fB\-\-dump\fR=\fIPARAM\fR +Show the value of the specified parameter \fIPARAM\fR in the section \fIBAR\-NAME\fR inside the configuration file. +.TP +\fB\-x\fR, \fB\-\-print\-exec\fR +Print the generated command line string used to start the \fBlemonbar\fR process. +.TP +\fB\-w\fR, \fB\-\-print\-wmname\fR +Print the generated \fIWM_NAME\fR. +.SH SEE ALSO +.TP +\fBlemonbar\fR(1), \fBlemonbuddy_terminate\fR(1), \fBlemonbuddy_wrapper\fR(1), \fBlemonbar_config\fR(5) diff --git a/man/lemonbuddy_config.5 b/man/lemonbuddy_config.5 new file mode 100644 index 00000000..d08edc94 --- /dev/null +++ b/man/lemonbuddy_config.5 @@ -0,0 +1,112 @@ +.TH LEMONBUDDY_CONFIG 5 2016-06-22 "lemonbuddy 1.2.1" "lemonbuddy Manual" +.SH NAME +.\" This man page will need lots of updating as documentation about lemonbuddy +.\" configuration improves. +\fBlemonbuddy_config\fR \- Configuration for a \fBlemonbuddy\fR(1) bar. +.SH SYNOPSIS +.BR $XDG_CONFIG_HOME/.config/lemonbuddy/config +.P +.BR ~/.config/lemonbuddy/config +.SH SYNTAX +The configuration syntax is based on the \fIini\fR file format. +.\" TODO better explain this section +.LP +.in +4 +.nf +[section/name] +str = My string +str = " My string" ; Quote the value +bool = true +bool = on +int = 10 +float = 10.0 + +; Values for a defined bar can be referenced using: +key = ${bar/top.foreground} + +; Values for the current bar can be referenced using: +key = ${BAR.foreground} + +; Other values can be referenced using: +key = ${section.key} +.\" +.\";format[-NAME] = "" +.\";format[-NAME]-spacing = N (unit: whitespaces) +.\";format[-NAME]-padding = N (unit: whitespaces) +.\";format[-NAME]-margin = N (unit: whitespaces) +.\";format[-NAME]-offset = N (unit: pixels) +.\";format[-NAME]-foreground = #aarrggbb +.\";format[-NAME]-background = #aarrggbb +.\";format[-NAME]-underline = #aarrggbb +.\";format[-NAME]-overline = #aarrggbb +.\"; +.\";label-NAME[-(foreground|background|(under|over)line|font|padding)] = ? +.\";icon-NAME[-(foreground|background|(under|over)line|font|padding)] = ? +.\";ramp-NAME-[0-9]+[-(foreground|background|(under|over)line|font|padding)] = ? +.\";animation-NAME-[0-9]+[-(foreground|background|(under|over)line|font|padding)] = ? +.\"; +.\";bar-NAME-width = N (unit: characters) +.\";bar-NAME-format = (tokens: %fill% %indicator% %empty%) +.\";bar-NAME-foreground-[0-9]+ = #aarrggbb +.\";bar-NAME-indicator[-(foreground|background|(under|over)line|font|padding)] = +.\";bar-NAME-fill[-(foreground|background|(under|over)line|font|padding)] = +.\";bar-NAME-empty[-(foreground|background|(under|over)line|font|padding)] = +.fi +.SH APPLICATION SETTINGS +These settings should exist in the `settings' section within the configuration file. +.TP +\fBthrottle_limit\fR and \fBthrottle_ms\fR +Limit the amount of events sent to \fBlemonbar\fR(1) within a set timeframe. Allow at most \fIthrottle_limit\fR updates within \fIthrottle_ms\fR milliseconds. +.SH BAR SETTINGS +These settings should exist in `bar/\fIBAR\-NAME\fR' section. +.TP +.BR monitor +Which display to have \fBlemonbar\fR(1) exist on. You can get a list of available outputs by using the command `xrandr -q | grep " connected" | cut -d ' ' -f1'. +.TP +\fBwidth\fR, \fBheight\fR +How large the bar should be. You can specify the values as a percentage of the screen, for example `85%', or omit the `%' and give the dimension(s) in pixels. +.TP +\fBoffset_x\fR, \fBoffset_y\fR +The window offset value in pixels. +.TP +.BR bottom +If this boolean is set to `true', then \fBlemonbar\fR(1) will be instructed to render itself on the bottom of the screen. +.TP +.BR dock +If this boolean is set to `true', then require \fBlemonbar\fR(1) to dock itself. +.TP +.BR spacing +This integer values is used as a multiplier when adding spaces between elements. +.TP +.BR lineheight +How high underlines and overlines should be. +.TP +\fBbackground\fR, \fBforeground\fR, \fBlinecolor\fR +Specify the colors used by \fBlemobar\fR(1). +.TP +\fBpadding_left\fR, \fBpadding_right\fR +Specify the number of spaces to add at the start or end of the entire bar. +.TP +\fBmodule_margin_left\fR, \fBmodule_margin_right\fR +Specify the number of spaces to add before or after each module. +.TP +.BR font\-\fIid\fR +Here you can specify which fonts you wish to use. You need to set \fIid\fR to be a positive integer. The font should be specified in the following format: `\fIFONT\-NAME\fR:size=\fIFONT\-SIZE\fR;\fIOFFSET\fR'. For example, you could set `font\-0' to be `NotoSans-Regular:size=8;0'. +.TP +.BR clickareas +This value is used by \fBlemonbar\fR(1) to specify the number of clickable areas available. +.TP +.BR wm_name +The value to set \fIWM_NAME\fR to when running. This defaults to `lemonbuddy\-\fIBAR\fR_\fIMONITOR\fR'. +.TP +.BR locale +Which locale to use. +.TP +\fBmodules-left\fR, \fBmodules-center\fR, \fBmodules-right\fR +Define which modules to use in the bar. +.SH EXAMPLES +.\" TODO add examples +There are no examples yet. +.SH SEE ALSO +.TP +\fBlemonbar\fB(1), \fBlemonbuddy\fR(1) diff --git a/man/lemonbuddy_terminate.1 b/man/lemonbuddy_terminate.1 new file mode 100644 index 00000000..e18de3c4 --- /dev/null +++ b/man/lemonbuddy_terminate.1 @@ -0,0 +1,14 @@ +.TH LEMONBUDDY_TERMINATE 1 2016-06-22 "lemonbuddy 1.2.1" "lemonbuddy Manual" +.SH NAME +\fBlemonbuddy_terminate\fR \- Terminate a previous \fBlemonbuddy\fR(1) bar. +.SH SYNOPSIS +.P +lemonbuddy_terminate [noconfirm] +.SH DESCRIPTION +\fBlemonbuddy_terminate\fR is a shell script that sends \fISIGKILL\fR to any currently running instances of \fBlemonbuddy\fR(1) or \fBlemonbar\fR(1). +.TP +.BR noconfirm +If this argument is passed, then the script will not prompt the user before killing. +.SH SEE ALSO +.TP +\fBlemonbar\fR(1), \fBlemonbuddy\fR(1), \fBlemonbuddy_wrapper\fR(1) diff --git a/man/lemonbuddy_wrapper.1 b/man/lemonbuddy_wrapper.1 new file mode 100644 index 00000000..6fe51531 --- /dev/null +++ b/man/lemonbuddy_wrapper.1 @@ -0,0 +1,18 @@ +.TH LEMONBUDDY_WRAPPER 1 2016-06-22 "lemonbuddy 1.2.1" "lemonbuddy Manual" +.SH NAME +\fBlemonbuddy_wrapper\fR \- Start a \fBlemonbuddy\fR(1) process and connect it to a \fBlemonbar\fR(1) process. +.SH SYNOPSIS +.P +lemonbuddy_wrapper \fIBAR\-NAME\fR +.SH DESCRIPTION +\fBlemonbuddy_wrapper\fR is a shell script that starts \fBlemonbuddy\fR(1) and \fBlemonbar\fR(1) and connects them using a temporary pipe. +.SH ENVIRONMENT +.TP +.BR LEMONBUDDY_EXECUTABLE +Specify an alternate executable to use. The default value is \fIlemonbuddy\fR. +.TP +.BR XDG_CACHE_HOME +The cache directory used by the script. If this variable is not set, then \fI~/.cache\fR is used. +.SH SEE ALSO +.TP +\fBlemonbar\fR(1), \fBlemonbuddy\fR(1), \fBlemonbuddy_terminate\fR(1)