From 20ca75462942b6c3f2cff1d43c8781447510db55 Mon Sep 17 00:00:00 2001 From: Michael Carlberg Date: Tue, 18 Oct 2016 18:40:47 +0200 Subject: [PATCH] wip: Rewrite manpages for 2.0 --- man/CMakeLists.txt | 5 +---- man/Makefile | 27 ++--------------------- man/lemonbuddy.1 | 31 +++++++++++++++------------ man/lemonbuddy_config.5 | 44 +++++++++++++++++++++----------------- man/lemonbuddy_terminate.1 | 14 ------------ man/lemonbuddy_wrapper.1 | 18 ---------------- 6 files changed, 44 insertions(+), 95 deletions(-) delete mode 100644 man/lemonbuddy_terminate.1 delete mode 100644 man/lemonbuddy_wrapper.1 diff --git a/man/CMakeLists.txt b/man/CMakeLists.txt index df598cd4..16cf4231 100644 --- a/man/CMakeLists.txt +++ b/man/CMakeLists.txt @@ -1,7 +1,4 @@ -set(MAN_PAGES_1 - lemonbuddy.1 - lemonbuddy_terminate.1 - lemonbuddy_wrapper.1) +set(MAN_PAGES_1 lemonbuddy.1) set(MAN_PAGES_5 lemonbuddy_config.5) INSTALL(FILES ${MAN_PAGES_1} DESTINATION ${CMAKE_INSTALL_PREFIX}/share/man/man1 COMPONENT doc) diff --git a/man/Makefile b/man/Makefile index fae7d7f3..b9b4ed11 100644 --- a/man/Makefile +++ b/man/Makefile @@ -1,4 +1,4 @@ -.PHONY: all pdf release update-dates update-versions clean +.PHONY: all release update-dates update-versions clean # Constant declarations PROGRAM_NAME = lemonbuddy @@ -8,12 +8,8 @@ DATE = $(shell date +%Y-%m-%d) # 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: $(PDF_TARGET) release: clean update-dates update-versions # Program targets @@ -32,33 +28,14 @@ update-dates: @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=$@ $^ - lemonbuddy: lemonbuddy.1 mandoc -a $< -lemonbuddy_wrapper: lemonbuddy_wrapper.1 - mandoc -a $< - -lemonbuddy_terminate: lemonbuddy_terminate.1 - mandoc -a $< - lemonbuddy_config: lemonbuddy_config.5 mandoc -a $< clean: @echo '[CLEAN]' - @rm -f $(GZ_FILES) $(PS_FILES) $(PDF_TARGET) + @rm -f $(GZ_FILES) # vim:ts=2 sw=2 noet nolist diff --git a/man/lemonbuddy.1 b/man/lemonbuddy.1 index b90bfc09..7e3fcced 100644 --- a/man/lemonbuddy.1 +++ b/man/lemonbuddy.1 @@ -1,9 +1,9 @@ -.TH lemonbuddy 1 2016-06-22 "lemonbuddy 1.4.2" "User Manual" +.TH lemonbuddy 1 2016-10-18 "lemonbuddy 2.0.0" "User Manual" .SH NAME -\fBlemonbuddy\fR \- A fast and easy-to-use tool for Lemonbar. +\fBlemonbuddy\fR \- A fast and easy-to-use tool status bar. .SH SYNOPSIS .P -lemonbuddy \fIBAR-NAME\fR [\fB\-c\fR \fICONFIG\fR|\fB\-p\fR \fIPIPE\fR|\fB\-l\fR \fILOG_LEVEL\fR|\fB\-d\fR \fIPARAM\fR|\fB\-x\fR|\fB\-w\fR] +lemonbuddy \fIBAR-NAME\fR [\fB\-c\fR \fICONFIG\fR|\fB\-l\fR \fILOG_LEVEL\fR|\fB\-d\fR \fIPARAM\fR|\fB\f-q\fR|\fB\-r\fR|\fB\f-s\fR|\fB\-w\fR] .P lemonbuddy [\fB\-h\fR | \fB\-\-help\fR] .SH DESCRIPTION @@ -16,29 +16,32 @@ Mandatory arguments to long options are mandatory for short options too. \fB\-h\fR, \fB\-\-help\fR Show help and program options. .TP +\fB\-v\fR, \fB\-\-version\fR +Print version information. +.TP +\fB\-l\fR, \fB\-\-log\fR=\fILEVEL\fR +Set how verbose \fBlemonbuddy\fR's logging is. \fILEVEL\fR must be one of: `warning` or `info`. +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Be quiet (will override -l). +.TP \fB\-c\fR, \fB\-\-config\fR=\fICONFIG\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'. +\fB\-r\fR, \fB\-\-reload\fR +Reload the application when the config file has been modified. (NOTE: Its recommended to only use this when setting up the bar). .TP \fB\-d\fR, \fB\-\-dump\fR=\fIPARAM\fR Show the value of the specified parameter \fIPARAM\fR in the section [bar/\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. .TP -\fB\-v\fR, \fB\-\-version\fR -Print version information. +\fB\-s\fR, \fB\-\-stdout\fR +Dump content to stdout instead of rendering an X window. .SH SEE ALSO .TP -\fBlemonbar\fR(1), \fBlemonbuddy_terminate\fR(1), \fBlemonbuddy_wrapper\fR(1), \fBlemonbuddy_config\fR(5) +\fBlemonbuddy_config\fR(5) .RE .SH HOMEPAGE .sp diff --git a/man/lemonbuddy_config.5 b/man/lemonbuddy_config.5 index 3ca25564..6eba5744 100644 --- a/man/lemonbuddy_config.5 +++ b/man/lemonbuddy_config.5 @@ -1,4 +1,4 @@ -.TH lemonbuddy_config 5 2016-06-22 "lemonbuddy 1.4.2" "User Configuration" +.TH lemonbuddy_config 5 2016-10-18 "lemonbuddy 2.0.0" "User Configuration" .SH NAME .\" This man page will need lots of updating as documentation about lemonbuddy .\" configuration improves. @@ -27,6 +27,10 @@ Values defined in another section can be referenced using: key = \fI${bar/top.foreground}\fR .TP +Read the value of an environment variable using: + +key = \fI${env:MYVAR}\fR +.TP Use BAR to target the section of the current bar: key = \fI${BAR.foreground}\fR @@ -52,7 +56,7 @@ format[-NAME]-overline = #aa[rrggbb] The rest of the drawtypes follow the same pattern. .\" TODO: Describe the drawtypes -label-NAME[-(foreground|background|(under|over)line|font|padding)] = ? +label-NAME[-(foreground|background|(under|over)line|font|padding|maxlen|ellipsis)] = ? 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)] = ? @@ -64,29 +68,32 @@ 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. +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. +\fBthrottle-limit\fR and \fBthrottle-ms\fR +Limit the amount of update events within a set timeframe. Allow at most \fIthrottle-limit\fR updates within \fIthrottle-ms\fR milliseconds. .SH BAR SETTINGS These settings should be defined in the [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'. +Which display to output the bar to. You can get a list of available outputs by using the command `xrandr -q | grep " connected" | cut -d ' ' -f1`. +If unspecified, the application will pick the first one it finds. .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. +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 +\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. +Put the bar at the bottom of the screen. .TP .BR dock -If this boolean is set to `true', then require \fBlemonbar\fR(1) to dock itself. +If this boolean is set to `true`, then force the X window to dock itself. +If you are using \fBi3\fR(1) it is recommended to use the default value. .TP .BR spacing This integer value is used as a multiplier when adding spaces between elements. @@ -95,22 +102,19 @@ This integer value is used as a multiplier when adding spaces between elements. How high underlines and overlines should be. .TP \fBbackground\fR, \fBforeground\fR, \fBlinecolor\fR -Specify the colors used by \fBlemobar\fR(1). +Specify the colors used to draw the bar. .TP -\fBpadding_left\fR, \fBpadding_right\fR +\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 +\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'. +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-NAME\fR_\fIMONITOR\fR'. +.BR wm-name +The value to set \fIWM_NAME\fR to when running. This defaults to `lemonbuddy\-\fIBAR-NAME\fR_\fIMONITOR\fR`. .TP .BR locale Which locale to use. @@ -122,4 +126,4 @@ Define which modules to use in the bar. There are no examples yet. .SH SEE ALSO .TP -\fBlemonbar\fB(1), \fBlemonbuddy\fR(1) +\fBlemonbuddy\fR(1) diff --git a/man/lemonbuddy_terminate.1 b/man/lemonbuddy_terminate.1 deleted file mode 100644 index 706f4068..00000000 --- a/man/lemonbuddy_terminate.1 +++ /dev/null @@ -1,14 +0,0 @@ -.TH lemonbuddy_terminate 1 2016-06-22 "lemonbuddy 1.4.2" "User 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 deleted file mode 100644 index 8110a05a..00000000 --- a/man/lemonbuddy_wrapper.1 +++ /dev/null @@ -1,18 +0,0 @@ -.TH lemonbuddy_wrapper 1 2016-06-22 "lemonbuddy 1.4.2" "User 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)