Init user documentaton

README.md

+===================================================================
+                                                                   
+                             i3csstatus                            
+                             ==========                            
+                                                                   
+        Alternative generator of i3 status bar written in c#       
+                                                                   
+                        Sample configuration file                  
+                        -------------------------                  
+                                                                   
+       (c)   2022 Jiri Kalvoda <jirikalvoda@kam.mff.cuni.cz>       
+                                                                   
+===================================================================
+
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+===================================================================
+
+User documentation
+==================
+
+See output of `i3csstatus -h` and documented configuration file at
+`sample.conf`.

sample.conf

+#####################################################################
+#                                                                   #
+#                             i3csstatus                            #
+#                             ==========                            #
+#                                                                   #
+#        Alternative generator of i3 status bar written in c#       #
+#                                                                   #
+#                     Sample configuration file                     #
+#                     -------------------------                     #
+#                                                                   #
+#       (c)   2022 Jiri Kalvoda <jirikalvoda@kam.mff.cuni.cz>       #
+#                                                                   #
+#####################################################################
+
+# This file (not whole i3csstatus) is licences under:
+#
+# |            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+# |                    Version 2, December 2004
+# | 
+# | Copyright (C) 2022 Jiri Kalvoda <jirikalvoda@kam.mff.cuni.cz>
+# | 
+# | Everyone is permitted to copy and distribute verbatim or modified
+# | copies of this license document, and changing it is allowed as long
+# | as the name is changed.
+# | 
+# |            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+# |   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+# | 
+# |  0. You just DO WHAT THE FUCK YOU WANT TO.
+
+
+# This is sample configuration file. All possibilities how to configure i3csstatus should be written here.
+
+# Configuration file syntax:
+# ==========================
+
+# Every line starting with `#` after any sequence of white characters is comment.
+# However part-line comments are not allowed.
+
+# Format of this configuration file is simple. File is divided to sections started with [NAME_OF_THE_SECTION] lines.
+# Every section describe one module of i3csstatus. Names of sections should be unique.
+# Before first section could be global options.
+
+# Each option has format:
+#
+#  a) KEY = VALUE
+#
+#  or
+#
+#  b) KEY = VALUE
+#         SECOND LINE OF VALUE
+#         THIRD LINE OF VALUE
+#             LINE STARTING WITH SOME SPACES
+#
+#  or
+#
+#  c) KEY
+#       FIRST LINE OF VALUE
+#           LINE STARTING WITH SOME SPACES
+#
+#  or
+#
+#  d) KEY << STRING NOT CONTAINED IN VALUE
+#     VALUE
+#     STRING NOT CONTAINED IN VALUE
+#
+# or
+#
+# e) KEY         (for true in boolean context)
+#
+# Notice, that no `"` is needed (and will not be removed)
+# KEY should not contain `=` and should not start wit `[`.
+# White characters on begin/end will be trimmed.
+# VALUE in a, b option will be trimmed too.
+# White characters on end of LINES in b, c will be removed (not from the begin).
+# However SECOND LINE in b and FIRST LINE in c should not contain any tiling tabs or spaces
+# Most generic is e option. There should be lines starting with `#` and no processing will be applied.
+# Last end-line character will not be a part of value.
+
+# Value types in config:
+# ======================
+# string: written as it is without quoting
+# int: in decimal format eg. `10`
+# number: with decimal dot (`1.23`) or in scientific notation (`1e3`)
+# time: number in section (eg. 60 for one minute)
+# bool: true/yes/use/1 or flase/no/unuse/0
+#         only key without value is true as well
+# path: string with simple expansion of ~ on the begin and environment variable
+#           ( $HOME or ${HOME})
+# format: string for expansion
+#           `{key}` will be expanded
+#           escape for `{` and `}` is `{{` and `}}`
+# color: in HTML form (eg `red` or `#FF0000`)
+# config: The value is interpreted recursively as config (with the same syntax)
+
+# Allowed global options:
+# =======================
+
+refresh = 1
+# <time> (default 1)
+# Refresh the status bar at lees once per this time
+# (some modules could do extra refresh by their own)
+
+
+# Modules:
+# ========
+
+# You can specify module type in section name or by `_type` option (if you need other section name).
+
+[i3status]
+# this module could cooperate with i3status program and get a part of status bar from them
+# Notice, that only one i3status is running for whole status bar.
+# Due to technical limitation of i3status should be option `name` unique.
+name=ethernet _first_
+# mandatory <string>
+config
+     format_up = "E: %ip (%speed)"
+     format_down = "E: down"
+# <string>
+
+# This will be translated to i3config:
+# | order += "ethernet _first_"
+# | ethernet _first_ {
+# |         format_up = "E: %ip (%speed)"
+# |         format_down = "E: down"
+# | }
+
+# For possible usage see i3status man page
+
+global_cache = 1
+# <time> default 0
+# If status bar is refreshed more than once per this time it will be used old
+# values without fetching new data from i3status.
+# This option is valid across all i3status modules. Do not specify two different values.
+
+[time]
+format = HH:mm:ss
+# <string> default yyyy-MM-dd HH:mm:ss
+short_format = HH:mm
+# <string>
+# Format of date/time to show, expanded by C# DateTime.ToString
+# (https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings)
+# Short format will be used if there is no enough space in status bar (and it is defined).
+round = 60
+# <time> 1
+refresh
+# <bool> default false
+# Round time value and refresh status bar every change of rounded value.
+
+[battery]
+instance = BAT2
+# <string> default BAT1
+# Battery identification
+
+path = /sys/class/power_supply/BAT1/uevent
+# <path> default /sys/class/power_supply/{instance}/uevent
+# Source uevent file path.
+
+time_window = 300
+# <time> default 60
+# Derivation and reaming time will be calculated from last `time_window` seconds.
+
+format = {status} {percent}
+# <format>
+short_format = {percent}
+# <format>
+# String to expand. (Short version will be shown if there is no more space).
+# Expanded values: 
+#            status - Charging, Discharging, Full ...
+#            percent - how full is battery in percent
+#            derivation - how much is changing percent (number of percent per hour)
+#            reaming - time to reach full or empty state
+
+[constant]
+# Just show some text
+text = Hi!
+color = red
+
+
+[file]
+# read file context every refresh of status bar
+path = $HOME/file/to/show
+# mandatory <path>
+not_found_handler = [constant]
+        color = red
+        text = NFound
+# <config> default see above
+error_handler = [constant]
+        color = red
+        text = ERR
+# <config> default see above
+
+# If file is not found or some other error with read is raised,
+# status bar described in this config will be shown.
+# Often it contain only one constant module or is empty.
+
+parser = text
+# see below for explanation
+
+[pipe]
+# Read data from named pipe and process it by parser (see above).
+# Pipe will be opened (file created) on startup. If the file yet exist,
+# it will be unlinked (deleted).
+# Pipe will be opened for booth, read and write, so it will not close
+# itself, if you close your file descriptor.
+
+path = /tmp/pipe
+# mandatory <path>
+# Path to the input pipe for the module
+
+separator = 10
+# <int> default 0
+# number of ASCI character which separate messages coming trow pipe
+
+delay = 0
+# <time> default 0.01
+# Bar will be redrawn no later than this time after new messages
+# If come lot's of messages is some small time, this option will safe some resources
+
+show_old = 10
+# <time>
+# If messages is older than this time, it will be shown how old it is.
+
+max_old = 30
+# <time>
+# Do not show messages older than this time.
+
+no_data_handler = [constant]
+        text = No data
+# <config> default empty
+# If there is no data (or it is too old)  status bar
+# described in this config will be shown.
+
+parser = text
+# see below for explanation
+
+[exec]
+# Create new process and reed message from their stdout
+
+separator = 10
+delay = 0
+show_old = 10
+max_old = 30
+no_data_handler = [constant]
+        text = No data
+# The same as in pipe module
+
+program = python3
+# mandatory <string>
+arguments = -u
+# <string>
+# program with this arguments will be execute
+
+stdin
+    import time
+    i = 0
+    while True:
+        print(i)
+        time.sleep(1)
+        i+= 1
+# <string>
+# This string will be putted to program stdin
+
+[http]
+# Fetch message from http(s) (for example some json api).
+
+error_handler = [constant]
+        color = red
+        text = ERR
+# The same as in file module
+
+delay = 0
+show_old = 10
+max_old = 30
+no_data_handler = [constant]
+        text = No data
+parser = text
+# The same as in pipe module
+
+url = http://kam.mff.cuni.cz/~jirikalvoda/x
+# mandatory <string>
+
+period = 20
+# <time> default 10
+# Delay between two asks.
+
+timeout = 10
+# <time> default 10
+# Timeout of each HTTP request.
+
+
+# Parsers:
+# ========
+
+# Some of modules use parsers. It is part of module, that is responsible for processing text oriented message to part of status bar.
+# You can specify which parser you would like to use by `parser` option.
+# Parsers could have some extra options additionally to module options.
+
+# Parser: text
+# ------------
+# Each line will be one segment of status bar.
+# 
+# color = red
+# <color>
+
+# Parser: osdd_last
+# ------------
+# Parser for reading messages from On-Screen display daemon 
+# (which is simple linux notification server).
+# First line of message contain unix time when message was shown
+# (time duration will be shown on begin of message).
+# Next lines contains color (in HEX format) and text to show.
+# 
+# Example usage:
+[osdd_last]
+_type = file
+path = ~/.osdd_last
+parser = osdd_last
+# or
+[osdd_last_pipe]
+_type = pipe
+path = $XDG_RUNTIME_DIR/osdd_to_i3csstatus
+parser = osdd_last
+
+# Parser: checkmail_status
+# ------------------------
+# Show number of new mail and connection status from checkmail.
+#
+# Example usage:
+[checkmail_status]
+_type = file
+path = ~/.cm
+parser = checkmail_status
+
+# Parser: offlineimap_status
+# --------------------------
+# Show the status of offlineimap daemon.
+#
+# Example usage:
+[offlineimap_status]
+_type = file
+path = ~/.offlineimap.log
+parser = offlineimap_status
+
+# Parser: ICE_speed and ICE_next_stop
+# -----------------------------------
+# Show information of speed or next stop and delay for Deutsche bahn ICE trains.
+# Example usage:
+[ICE_speed]
+_type=http
+url = https://iceportal.de/api1/rs/status
+parser = ICE_speed
+period = 5
+show_old = 20
+max_old = 120
+error_handler =
+
+[ICE_next_stop]
+_type=http
+url = https://iceportal.de/api1/rs/tripInfo/trip 
+parser = ICE_next_stop
+error_handler = 
+period = 20
+show_old = 60
+max_old = 300