From 3273ed689fcf02528e32305174dbe36758004b61 Mon Sep 17 00:00:00 2001 From: Michael Carlberg Date: Thu, 30 Jun 2016 04:56:58 +0200 Subject: [PATCH] build: Include man pages in build --- CMakeLists.txt | 1 + man/CMakeLists.txt | 8 ++++ man/Makefile | 27 +++++++++--- man/lemonbuddy.1 | 17 +++++--- man/lemonbuddy_config.5 | 87 ++++++++++++++++++++++---------------- man/lemonbuddy_terminate.1 | 2 +- man/lemonbuddy_wrapper.1 | 2 +- 7 files changed, 95 insertions(+), 49 deletions(-) create mode 100644 man/CMakeLists.txt diff --git a/CMakeLists.txt b/CMakeLists.txt index 47bafc1b..a81faf2b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -154,6 +154,7 @@ message(STATUS " Enable mpd support ${ENABLE_MPD}") message(STATUS " Enable network support ${ENABLE_NETWORK}") message(STATUS "---------------------------") +add_subdirectory("${PROJECT_SOURCE_DIR}/man") add_subdirectory("${PROJECT_SOURCE_DIR}/src" EXCLUDE_FROM_ALL) link_directories(${PROJECT_LINK_DIRS}) include_directories(${PROJECT_BINARY_DIR} ${PROJECT_SOURCE_DIR} ${PROJECT_INCL_DIRS}) diff --git a/man/CMakeLists.txt b/man/CMakeLists.txt new file mode 100644 index 00000000..df598cd4 --- /dev/null +++ b/man/CMakeLists.txt @@ -0,0 +1,8 @@ +set(MAN_PAGES_1 + lemonbuddy.1 + lemonbuddy_terminate.1 + lemonbuddy_wrapper.1) +set(MAN_PAGES_5 lemonbuddy_config.5) + +INSTALL(FILES ${MAN_PAGES_1} DESTINATION ${CMAKE_INSTALL_PREFIX}/share/man/man1 COMPONENT doc) +INSTALL(FILES ${MAN_PAGES_5} DESTINATION ${CMAKE_INSTALL_PREFIX}/share/man/man5 COMPONENT doc) diff --git a/man/Makefile b/man/Makefile index bb6963fa..fae7d7f3 100644 --- a/man/Makefile +++ b/man/Makefile @@ -1,8 +1,9 @@ -.PHONY: all pdf release update-versions clean +.PHONY: all pdf release update-dates update-versions clean # Constant declarations PROGRAM_NAME = lemonbuddy VERSION = $(shell git describe --tags) +DATE = $(shell date +%Y-%m-%d) # Sources MAN_SOURCES = $(wildcard *.1 *.5) @@ -11,13 +12,16 @@ PS_FILES = $(addsuffix .ps,$(MAN_SOURCES)) PDF_TARGET = $(PROGRAM_NAME).pdf # Targets -all: $(GZ_FILES) $(PDF_TARGET) +all: $(GZ_FILES) pdf: $(PDF_TARGET) -release: clean update-versions all +release: clean update-dates update-versions # Program targets update-versions: - @sed -i '1 s/"$(PROGRAM_NAME) [^"]*?"/"$(PROGRAM_NAME) VERSION"/' $(MAN_SOURCES) + @sed -i '1 s/"$(PROGRAM_NAME) [^"]*"/"$(PROGRAM_NAME) $(VERSION)"/' $(MAN_SOURCES) + +update-dates: + @sed -i '1 s/[0-9]{4}\-[0-9]{2}\-[0-9]{2}/$(DATE)/' $(MAN_SOURCES) # Documentation targets %.1.gz: %.1 @@ -39,9 +43,22 @@ update-versions: $(PDF_TARGET): $(PS_FILES) @echo '[PDF] $(notdir $@)' @gs -q -sPAPERSIZE=letter -dNOPAUSE -dBATCH -sDEVICE=pdfwrite \ - -sOutputFile=$@ $^ + -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) +# vim:ts=2 sw=2 noet nolist diff --git a/man/lemonbuddy.1 b/man/lemonbuddy.1 index f5146baa..c53aebb8 100644 --- a/man/lemonbuddy.1 +++ b/man/lemonbuddy.1 @@ -1,9 +1,9 @@ -.TH LEMONBUDDY 1 2016-06-22 "lemonbuddy 1.2.1" "lemonbuddy Manual" +.TH lemonbuddy 1 2016-06-22 "lemonbuddy 1.4.1-9-gc72ba27" "User 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] +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] .P lemonbuddy [\fB\-h\fR | \fB\-\-help\fR] .SH DESCRIPTION @@ -16,7 +16,7 @@ Mandatory arguments to long options are mandatory for short options too. \fB\-h\fR, \fB\-\-help\fR Show help and program options. .TP -\fB\-c\fR, \fB\-\-config\fR=\fICONFIG\-FILE\fR +\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 @@ -26,13 +26,20 @@ Specify an alternate input pipe. This pipe is used by \fBlemonbuddy\fR to commun 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. +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. .SH SEE ALSO .TP -\fBlemonbar\fR(1), \fBlemonbuddy_terminate\fR(1), \fBlemonbuddy_wrapper\fR(1), \fBlemonbar_config\fR(5) +\fBlemonbar\fR(1), \fBlemonbuddy_terminate\fR(1), \fBlemonbuddy_wrapper\fR(1), \fBlemonbuddy_config\fR(5) +.RE +.SH HOMEPAGE +.sp +https://github.com/jaagr/lemonbuddy diff --git a/man/lemonbuddy_config.5 b/man/lemonbuddy_config.5 index d08edc94..f8051dd7 100644 --- a/man/lemonbuddy_config.5 +++ b/man/lemonbuddy_config.5 @@ -1,4 +1,4 @@ -.TH LEMONBUDDY_CONFIG 5 2016-06-22 "lemonbuddy 1.2.1" "lemonbuddy Manual" +.TH lemonbuddy_config 5 2016-06-22 "lemonbuddy 1.4.1-9-gc72ba27" "User Configuration" .SH NAME .\" This man page will need lots of updating as documentation about lemonbuddy .\" configuration improves. @@ -8,49 +8,62 @@ .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 +.TP +The configuration syntax is based on the \fIini\fR file format. +.TP +A sample config section with various field types: + [section/name] str = My string -str = " My string" ; Quote the value +; Quote the value to keep surrounding spaces +str = " My string" bool = true bool = on int = 10 float = 10.0 +.TP +Values defined in another section can be referenced using: -; Values for a defined bar can be referenced using: -key = ${bar/top.foreground} +key = \fI${bar/top.foreground}\fR +.TP +Use BAR to target the section of the current bar: -; Values for the current bar can be referenced using: -key = ${BAR.foreground} +key = \fI${BAR.foreground}\fR +.TP +Most modules define a format-N field. The formats define a set of tags. For example, the mpd module defines the following formats: + +\fIformat-online\fR = ... ... +\fIformat-offline\fR = the server is offline +.TP +The modules will toggle between the formats and only show the one defined for the current module state. +.TP +Each format contains the following fields: + +format[-NAME]-padding = N (unit: whitespaces) +format[-NAME]-margin = N (unit: whitespaces) +format[-NAME]-spacing = N (unit: whitespaces) +format[-NAME]-offset = N (unit: pixels) +format[-NAME]-foreground = #aa[rrggbb] +format[-NAME]-background = #aa[rrggbb] +format[-NAME]-underline = #aa[rrggbb] +format[-NAME]-overline = #aa[rrggbb] +.TP +The rest of the drawtypes follow the same pattern. + +.\" TODO: Describe the drawtypes +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)] = -; 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. @@ -58,7 +71,7 @@ These settings should exist in the `settings' section within the configuration f \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. +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'. @@ -76,7 +89,7 @@ If this boolean is set to `true', then \fBlemonbar\fR(1) will be instructed to r 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. +This integer value is used as a multiplier when adding spaces between elements. .TP .BR lineheight How high underlines and overlines should be. @@ -97,7 +110,7 @@ Here you can specify which fonts you wish to use. You need to set \fIid\fR to be 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'. +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. diff --git a/man/lemonbuddy_terminate.1 b/man/lemonbuddy_terminate.1 index e18de3c4..dc3879d7 100644 --- a/man/lemonbuddy_terminate.1 +++ b/man/lemonbuddy_terminate.1 @@ -1,4 +1,4 @@ -.TH LEMONBUDDY_TERMINATE 1 2016-06-22 "lemonbuddy 1.2.1" "lemonbuddy Manual" +.TH lemonbuddy_terminate 1 2016-06-22 "lemonbuddy 1.4.1-9-gc72ba27" "User Manual" .SH NAME \fBlemonbuddy_terminate\fR \- Terminate a previous \fBlemonbuddy\fR(1) bar. .SH SYNOPSIS diff --git a/man/lemonbuddy_wrapper.1 b/man/lemonbuddy_wrapper.1 index 6fe51531..d63db7ae 100644 --- a/man/lemonbuddy_wrapper.1 +++ b/man/lemonbuddy_wrapper.1 @@ -1,4 +1,4 @@ -.TH LEMONBUDDY_WRAPPER 1 2016-06-22 "lemonbuddy 1.2.1" "lemonbuddy Manual" +.TH lemonbuddy_wrapper 1 2016-06-22 "lemonbuddy 1.4.1-9-gc72ba27" "User Manual" .SH NAME \fBlemonbuddy_wrapper\fR \- Start a \fBlemonbuddy\fR(1) process and connect it to a \fBlemonbar\fR(1) process. .SH SYNOPSIS