wip: man pages

CMakeLists.txt

@@ -113,6 +113,7 @@ set(enabled_modules "")
 set(enabled_particles "")
 set(enabled_decorations "")
 
+add_subdirectory(doc)
 add_subdirectory(modules)
 add_subdirectory(particles)
 add_subdirectory(decorations)

doc/CMakeLists.txt

@@ -0,0 +1,30 @@
+cmake_minimum_required(VERSION 3.13)
+
+find_program(SCDOC_EXECUTABLE scdoc)
+find_program(GZIP_EXECUTABLE gzip)
+
+function(add_man_pages)
+  foreach (src ${ARGN})
+    string(REPLACE ".scd" ".gz" man "${src}")
+    string(REGEX MATCH "\.[0-9]+\.scd" man_target "${src}")
+    string(REGEX MATCH "[0-9]+" man_target "${man_target}")
+
+    add_custom_command(
+      OUTPUT ${man}
+      COMMENT "Generating man page ${man}"
+      COMMAND ${SCDOC_EXECUTABLE} < ${CMAKE_CURRENT_SOURCE_DIR}/${src} |
+      ${GZIP_EXECUTABLE} > ${man}
+      VERBATIM
+      MAIN_DEPENDENCY ${CMAKE_CURRENT_SOURCE_DIR}/${src}
+      )
+
+    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${man}
+      DESTINATION share/man/man${man_target})
+  endforeach()
+
+  string(REPLACE ".scd" ".gz" out "${ARGN}")
+  list(TRANSFORM out PREPEND "${CMAKE_CURRENT_BINARY_DIR}/")
+  add_custom_target(man-pages ALL SOURCES ${ARGN} DEPENDS ${out})
+endfunction()
+
+add_man_pages(f00bar.1.scd f00bar.5.scd)

doc/f00bar.1.scd

@@ -0,0 +1,32 @@
+f00bar(1)
+
+# NAME
+f00bar - modular status panel for X11 and Wayland
+
+# SYNOPSIS
+*f00bar*
+
+# DESCRIPTION
+*f00bar* is a light-weight and configurable status panel (_bar_, for
+short) for *X* and *Wayland*.
+
+It has a number of _modules_ that provide information in the form of
+_tags_. For example, the _clock_ module has a _date_ tag that contains
+the current date.
+
+The modules do not know how to present the information though. This is
+instead done by _particles_. And the user, you, decides which
+particles (and thus how to present the data) to use.
+
+Furthermore, each particle can have a _decoration_. These are things
+like a different background, or an graphical underline.
+
+There is *no* support for images or icons. use an icon font
+(e.g. *Font Awesome*, or *Material Icons*) if you want a graphical
+representation.
+
+There are a number of modules and particles builtin. More can be added
+as plugins. You can even write your own!
+
+# CONFIGURATION
+See *f00bar*(5)

doc/f00bar.5.scd

@@ -0,0 +1,143 @@
+f00bar(5)
+
+# NAME
+f00bar - configuration file
+
+# DESCRIPTION
+
+A f00bar configuration file is a yaml formatted document containing an
+associative array named _bar_. You may define other top-level entities
+and reference them using anchors.
+
+Besides the normal yaml types, there are a couple of f00bar specific
+types that are frequently used:
+
+- *font*: this is a string in _fontconfig_ format. Example of valid values:
+	- Font Awesome 5 Brands
+	- Font Awesome 5 Free:style=solid
+	- Dina:pixelsize=10:slant=italic
+	- Dina:pixelsize=10:weight=bold
+- *color*: an rgba hexstring; _RRGGBBAA_. Examples:
+	- ffffffff: white, no transparency
+	- 000000ff: black, no transparency
+	- 00ff00ff: green, no transparency
+	- ff000099: red, semi-transparent
+
+# FORMAT
+[[ *Name*
+:[ *Type*
+:[ *Req*
+:[ *Description*
+|  height
+:  int
+:  yes
+:  The height of the bar, in pixels (*not* including border)
+|  location
+:  enum
+:  yes
+:  one of _top_ or _bottom_
+|  background
+:  color
+:  yes
+:  Background color
+|  monitor
+:  string
+:  no
+:  Monitor to place the bar on. If not specified, the primary monitor will be
+   used
+|  left-spacing
+:  int
+:  no
+:  Space, in pixels, added *before* each module
+|  right-spacing
+:  int
+:  no
+:  Space, in pixels, added *after* each module
+|  spacing
+:  int
+:  no
+:  Short-hand for setting both _left-spacing_ and _right-spacing_
+|  left-margin
+:  int
+:  no
+:  Left-side margin, in pixels
+|  right-margin
+:  int
+:  no
+:  Right-side margin, in pixels
+|  margin
+:  int
+:  no
+:  Short-hand for setting both _left-margin_ and _right-margin_
+|  border
+:  associative array
+:  no
+:  Configures the border around the status bar
+|  border.width
+:  int
+:  no
+:  Width, in pixels, of the border
+|  border.color
+:  color
+:  no
+:  The color of the border
+|  border.left-margin
+:  int
+:  no
+:  Left-side margin, in pixels, from screen edge to bar
+|  border.right-margin
+:  int
+:  no
+:  Right-side margin, in pixels, from screen edge to bar
+|  border.top-margin
+:  int
+:  no
+:  Top margin, in pixels, from screen edge to bar
+|  border.bottom-margin
+:  int
+:  no
+:  Bottom margin, in pixels, from screen edge to bar
+|  border.margin
+:  int
+:  no
+:  Short-hand for setting _border.left/right/top/bottom-margin_
+|  font
+:  font
+:  no
+:  Default font to use in modules and particles
+|  foreground
+:  color
+:  no
+:  Default foreground (text) color to use
+|  left
+:  list
+:  no
+:  Left-aligned modules (see *f00bar-modules*(5))
+|  center
+:  list
+:  no
+:  Center-aligned modules (see *f00bar-modules*(5))
+|  right
+:  list
+:  no
+:  Right-aligned modules (see *f00bar-modules*(5))
+
+# EXAMPLES
+
+Top-oriented bar with a single, right-aligned, module: the *clock*,
+rendered as a simple string displaying only the time (not date).
+
+```
+bar:
+  location: top
+  height: 26
+  background: 00000066
+
+  right:
+    - clock:
+      content:
+        - string: {text: "{time}"}
+```
+
+# FILES
+_$HOME/.config/f00bar/config.yml_