fix the documentation Add missing manpages, update README, document the format now being TSV. - ploot - simple plotting tools
HTML git clone git://bitreich.org/ploot git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/ploot
DIR Log
DIR Files
DIR Refs
DIR Tags
DIR README
DIR LICENSE
---
DIR commit 18a41de0122bffc4889534a5a4cb27e2e875291c
DIR parent 50aea1263cf0d68aa2403894b92eb9584958af36
HTML Author: Josuah Demangeon <me@josuah.net>
Date: Wed, 7 Sep 2022 12:37:18 +0200
fix the documentation
Add missing manpages, update README, document the format now being TSV.
Diffstat:
M README.md | 68 +++++++++++++++++++++++++++----
M font8.c | 24 +++++++++++++++++++++++-
A ploot-braille.1 | 87 +++++++++++++++++++++++++++++++
M ploot-farbfeld.1 | 50 ++++++++++++++-----------------
M ploot-feed.1 | 26 ++++++++++++++++----------
M ploot-tsv.5 | 28 +++++++++++++++++-----------
6 files changed, 225 insertions(+), 58 deletions(-)
---
DIR diff --git a/README.md b/README.md
@@ -1,18 +1,57 @@
ploot
=====
+A collection of utilities plotting TSV data or text in various ways.
-ploot-ffplot
+ploot-text
+----------
+A small tool for plotting ASCII text with braille characters.
+Two font sizes available.
+
+```
+$ ploot-text -1 "$(date)"
+⡇⡀⡇⣠⣤⢀⠤⡇⠀⠐⢍⠁⣠⣤⢠⠤⡀⠀⠀⠀⠉⡝⠀⠀⢺⠀⠊⡱⠀⠄⠐⢉⠆⢺⠀⠠⠀⠯⢍⠐⢉⠆⠀⢸⣉⠆⡗⠔⡇⠀⢰⠉⠁⡯⠍⠐⢍⠁⠉⡏⠁⠀⠐⢉⠆⣎⢵⠐⢉⠆⠊⡱
+⠑⠑⠁⠑⠒⠈⠒⠃⠀⠐⠒⠁⠑⠒⢸⠒⠁⠀⠀⠀⠘⠀⠀⠀⠚⠂⠚⠒⠀⠂⠐⠓⠂⠚⠂⠐⠀⠒⠊⠐⠓⠂⠀⠘⠀⠀⠃⠀⠃⠀⠈⠒⠂⠓⠒⠐⠒⠁⠀⠃⠀⠀⠐⠓⠂⠑⠊⠐⠓⠂⠚⠒
+$ ploot-text -2 "$(date)"
+⠀⠀⠀⠀⠀⠀⠀⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+⡇⠀⡇⡠⠤⡀⡠⠤⡇⠀⠀⠀⡎⠉⠂⡠⠤⡀⡤⠤⡀⠀⠀⠀⠀⠀⠀⠉⢉⠇⠀⠀⠀⠠⡇⠀⠎⠉⡆⠀⡄⠀⠎⠉⡆⠎⠉⡆⠀⡄⠀⡎⠉⡆⡎⠉⡆⠀⠀⠀⡏⠉⡆⡷⡰⡇⠀⠀⠀⡎⠉⠂⡏⠉⠁⡎⠉⠂⠉⡏⠁
+⣧⢣⡇⡗⠒⠃⡇⠀⡇⠀⠀⠀⡈⠉⡆⡗⠒⠃⡇⠀⡇⠀⠀⠀⠀⠀⠀⢀⠎⠀⠀⠀⠀⠀⡇⠀⡠⠊⠀⠀⡀⠀⡠⠊⠀⡠⠊⠀⠀⡀⠀⡇⠁⡇⡇⠁⡇⠀⠀⠀⡗⠒⠁⡇⠁⡇⠀⠀⠀⡇⠀⡀⡏⠉⠀⡈⠉⡆⠀⡇⠀
+⠁⠀⠁⠈⠉⠀⠈⠉⠁⠀⠀⠀⠈⠉⠀⠈⠉⠀⡏⠉⠀⠀⠀⠀⠀⠀⠀⠈⠀⠀⠀⠀⠀⠈⠉⠀⠉⠉⠁⠀⠁⠀⠉⠉⠁⠉⠉⠁⠀⠁⠀⠈⠉⠀⠈⠉⠀⠀⠀⠀⠁⠀⠀⠁⠀⠁⠀⠀⠀⠈⠉⠀⠉⠉⠁⠈⠉⠀⠀⠁⠀
+```
+
+[1]: https://github.com/asciimoo/drawille
+
+ploot-braille
--------------
-*ploot-ffplot* reads collectd-style comma separated values (TSV) and produces a plot
-in the ffplot [1] image format (pipe it to ff2png). It is an alternative to
-RRDtool [2].
+*ploot-braille* reads tab separated values (TSV) and produces a plot
+in the drawille [1] text/image format. It is an alternative to gnuplot [2]
+in text mode.
It is targetting at generating monitoring graph, and it always read unix
timestamp as first column on standard input. The first line determines the
-name of the curves.
+name of the plots, all aligned vertically.
-[1]: https://tools.suckless.org/ffplot/
-[2]: https://oss.oetiker.ch/rrdtool/
+```
+$ ploot-braille <load-average.tsv
+ shortterm
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀├ 0.600
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣧⣾⡀⠀├ 0.400
+⠀⠀⠀⠀⠀⠀⡀⠀⡀⠀⡀⠀⢀⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⠀⢀⣰⣆⠀⠀⠀⠀⠀⠀⠀⠀⣰⣀⡆⠀⠀⢠⣆⠀⢀⢀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣷⣧├ 0.200
+⠀⠚⠛⠓⠛⠛⠓⠚⠓⠚⠛⠓⠛⠛⠓⠓⠛⠛⠛⠛⠓⠒⠒⠒⠚⠛⠛⠛⠛⠛⠚⠒⠓⠓⠚⠒⠚⠒⠛⠛⠛⠒⠒⠛⠛⠛⠛⠛⠓⠚⠚⠛⠒⠒⠛⠛⠛⠛⠛⠛├ 0.000
+ midterm
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀├ 0.600
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣤⣾⡄⠀├ 0.400
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⠀⠀⠀⣠⡄⠀⠀⠀⠀⠀⠀⠀⠀⢀⠀⡀⠀⠀⢀⡄⠀⠀⠀⡀⠀⠀⠀⠀⠀⠀⢰⣿⣿⣷⣧├ 0.200
+⠀⠛⠛⠛⠛⠛⠓⠚⠓⠒⠛⠛⠓⠛⠓⠓⠛⠛⠛⠛⠓⠒⠒⠒⠛⠛⠛⠚⠛⠛⠛⠒⠒⠛⠚⠓⠚⠓⠛⠛⠛⠛⠓⠛⠛⠛⠛⠚⠛⠛⠒⠛⠒⠒⠛⠛⠛⠛⠛⠛├ 0.000
+ longterm
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀├ 0.600
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⡄⠀├ 0.400
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⠀⠀⠀⢀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣿⣿⣿⣶├ 0.200
+⠀⠒⠛⠛⠛⠛⠒⠚⠓⠒⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠓⠒⠒⠒⠛⠛⠛⠛⠛⠛⠛⠓⠒⠒⠒⠒⠒⠓⠚⠛⠛⠛⠓⠛⠛⠛⠛⠓⠛⠛⠒⠒⠒⠒⠛⠛⠛⠛⠛⠛├ 0.000
+ ^00:00:00 ^10:00:00 ^20:00:00
+```
+
+[1]: https://github.com/asciimoo/drawille
+[2]: http://www.gnuplot.info/
ploot-feed
----------
@@ -21,7 +60,7 @@ a plain text continuous waterfall chart for live monitoring in the terminal. it
is an alternative to grafana [1].
```
-% plootxt 1 1 1 <load-average.tsv
+$ ploot-feed 1 1 1 <load-average.tsv
│shortterm │midterm │longterm │
17:34:00 _│⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│⣯⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│⣇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│
18/05/01 │⣟⡁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│⣿⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│⣿⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│
@@ -55,3 +94,16 @@ is an alternative to grafana [1].
```
[1]: https://grafana.com/
+
+ploot-farbfeld
+--------------
+*ploot-farbfeld* reads tab separated values (TSV) and produces a plot
+in the farbfeld [1] image format (pipe it to ff2png). It is an alternative to
+RRDtool [2] and other simple time series plotting tools.
+
+It is targetting at generating monitoring graph, and it always read unix
+timestamp as first column on standard input. The first line determines the
+name of the curves.
+
+[1]: https://tools.suckless.org/farbfeld/
+[2]: https://oss.oetiker.ch/rrdtool/
DIR diff --git a/font8.c b/font8.c
@@ -927,6 +927,28 @@ C(underscore) = {
_,_,_,
0};
+C(column) = {
+ _,_,_,
+ _,_,_,
+ _,X,_,
+ _,_,_,
+ _,_,_,
+ _,X,_,
+ _,_,_,
+ _,_,_,
+0};
+
+C(semicolumn) = {
+ _,_,_,
+ _,_,_,
+ _,X,_,
+ _,_,_,
+ _,_,_,
+ _,X,_,
+ _,X,_,
+ X,_,_,
+0};
+
struct font font8 = { 8, {
glyph_error, glyph_error, glyph_error, glyph_error,
glyph_error, glyph_error, glyph_error, glyph_error,
@@ -942,7 +964,7 @@ struct font font8 = { 8, {
glyph_coma, glyph_minus, glyph_dot, glyph_slash,
glyph_0, glyph_1, glyph_2, glyph_3,
glyph_4, glyph_5, glyph_6, glyph_7,
- glyph_8, glyph_9, glyph_error, glyph_error,
+ glyph_8, glyph_9, glyph_column, glyph_semicolumn,
glyph_error, glyph_error, glyph_error, glyph_error,
glyph_error, glyph_A, glyph_B, glyph_C,
glyph_D, glyph_E, glyph_F, glyph_G,
DIR diff --git a/ploot-braille.1 b/ploot-braille.1
@@ -0,0 +1,87 @@
+.Dd $Mdocdate: August 08 2018$
+.Dt PLOOT-BRAILLE 1
+.Os
+.
+.
+.Sh NAME
+.
+.Nm ploot-braille
+.Nd produce a drawille image of tsv input
+.
+.
+.Sh SYNOPSIS
+.
+.Nm ploot-braille
+.Op Fl r Ar rows
+.Op Fl c Ar cols
+.
+.
+.Sh DESCRIPTION
+.
+The
+.Nm
+utility plots tsv values coming from stdin into a text-based 2d plot out of braille characters.
+This is the same technique used by the drawille set of programs.
+.
+.Bl -tag -width 6n
+.
+.It Fl c Ar cols
+Set the total number of columns the output should have.
+.
+.It Fl r Ar rows
+Set the number of rows per chart to display.
+.
+.El
+.
+.Pp
+The input format is documented in the
+.Xr ploot-tsv 7
+manual page.
+.
+.
+.Sh EXIT STATUS
+.Ex -std
+.
+.
+.Sh EXAMPLES
+.
+.Bd -literal -offset indent
+$ cat <<EOF >sample.txt
+epoch used_memory free_memory
+1533752053 160 401
+1533752054 180 381
+1533752055 301 260
+1533752056 303 258
+EOF
+$ ploot-braille <sample.txt
+.Ed
+.
+.
+.Sh SEE ALSO
+.
+.Xr ploot-braille 1 ,
+.Xr ploot-tsv 7
+.
+.Pp
+The
+.Xr braille 7
+image format:
+.Lk https://tools.suckless.org/braille/
+.
+.
+.Sh HISTORY
+.
+.Nm
+is developped at
+.Bl -ohang
+.It
+.Lk gopher://bitreich.org/1/scm/ploot/ "Bitreich project index"
+.It
+.Lk git://bitreich.org/1/ploot/ "Bitreich public repo"
+.El
+.
+.
+.Sh AUTHORS
+.
+.An Josuah Demangeon
+.Aq Mt me@josuah.net
DIR diff --git a/ploot-farbfeld.1 b/ploot-farbfeld.1
@@ -1,17 +1,17 @@
.Dd $Mdocdate: August 08 2018$
-.Dt PLOOT-FF 1
+.Dt PLOOT-FARBFELD 1
.Os
.
.
.Sh NAME
.
-.Nm ploot-ffplot
-.Nd produce a ffplot image of tsv input
+.Nm ploot-farbfeld
+.Nd produce a farbfeld image of tsv input
.
.
.Sh SYNOPSIS
.
-.Nm ploot-ffplot
+.Nm ploot-farbfeld
.Op Fl t Ar title
.Ar colors...
.
@@ -20,7 +20,7 @@
.
The
.Nm
-utility plots an image in the ffplot format out of tsv values coming from stdin.
+utility plots an image in the farbfeld format out of tsv values coming from stdin.
.
.Bl -tag -width 6n
.
@@ -49,26 +49,26 @@ manual page.
.
.Bd -literal -offset indent
$ cat <<EOF >sample.txt
-epoch,used_memory,free_memory
-1533752053,160,401
-1533752054,180,381
-1533752055,301,260
-1533752056,303,258
+epoch used_memory free_memory
+1533752053 160 401
+1533752054 180 381
+1533752055 301 260
+1533752056 303 258
EOF
-$ ploot-ffplot -t demo -u MB red yellow <sample.txt
+$ ploot-farbfeld -t demo -u MB red yellow <sample.txt
.Ed
.
.
.Sh SEE ALSO
.
-.Xr ploot-ffplot 1 ,
+.Xr ploot-farbfeld 1 ,
.Xr ploot-tsv 7
.
.Pp
The
-.Xr ffplot 7
+.Xr farbfeld 7
image format:
-.Lk https://tools.suckless.org/ffplot/
+.Lk https://tools.suckless.org/farbfeld/
.
.
.Sh HISTORY
@@ -78,22 +78,16 @@ earned its author a bitreich.org medal of misspelled program name.
.
.Pp
.Nm
-was written at
-.Lk gopher://bitreich.org/1/scm/ploot/ "Bitreich"
+is developped at
+.Bl -ohang
+.It
+.Lk gopher://bitreich.org/1/scm/ploot/ "Bitreich project index"
+.It
+.Lk git://bitreich.org/1/ploot/ "Bitreich public repo"
+.El
.
.
.Sh AUTHORS
.
.An Josuah Demangeon
-.Aq Mt mail@josuah.net
-.
-.
-.Sh BUGS
-.
-.Nm
-does not make any math on the input: if the timestamps are not at regular
-interval, ploot will still print one output line every 4 lines read,
-regardless of the time interval.
-.
-.Pp
-However, the timestamp printed on the left is always exact.
+.Aq Mt me@josuah.net
DIR diff --git a/ploot-feed.1 b/ploot-feed.1
@@ -48,11 +48,11 @@ manual page.
.
.Bd -literal -offset indent
$ cat <<EOF >sample.txt
-epoch,free_memory,process_count
-1533752053,16.3,45
-1533752054,18.7,42
-1533752055,40.1,39
-1533752056,40.1,39
+epoch free_memory process_count
+1533752053 16.3 45
+1533752054 18.7 42
+1533752055 40.1 39
+1533752056 40.1 39
EOF
$ ploot-feed -w 80 1 1 <sample.txt
.Ed
@@ -60,8 +60,9 @@ $ ploot-feed -w 80 1 1 <sample.txt
.
.Sh SEE ALSO
.
-.Xr ploot-ffplot 1 ,
-.Xr ploot-format 7
+.Xr ploot-farbfeld 1 ,
+.Xr ploot-braille 1 ,
+.Xr ploot-tsv 5
.
.
.Sh HISTORY
@@ -71,14 +72,19 @@ earned its author a bitreich.org medal of misspelled program name.
.
.Pp
.Nm
-was written at
-.Lk gopher://bitreich.org/1/scm/ploot/ "Bitreich"
+is developped at
+.Bl -ohang
+.It
+.Lk gopher://bitreich.org/1/scm/ploot/ "Bitreich project index"
+.It
+.Lk git://bitreich.org/1/ploot/ "Bitreich public repo"
+.El
.
.
.Sh AUTHORS
.
.An Josuah Demangeon
-.Aq Mt mail@josuah.net
+.Aq Mt me@josuah.net
.
.
.Sh BUGS
DIR diff --git a/ploot-tsv.5 b/ploot-tsv.5
@@ -12,9 +12,9 @@
.Sh SYNOPSIS
.
.Bd -literal
-epoch,column-name-1,column-name-2
-timestamp,value1,value2
-timestamp,value1,value2
+epoch column-name-1 column-name-2
+timestamp value1 value2
+timestamp value1 value2
\&...
.Ed
.
@@ -39,7 +39,7 @@ The first column is always
Then there are the actual column names.
.
.Bd -literal -offset indent
-epoch,free_memory,process_count
+epoch free_memory process_count
.Ed
.
.
@@ -52,23 +52,29 @@ The remaining columns are values parsed as floating point numbers by
.Xr strtod 3 :
.
.Bd -literal -offset indent
-1533752053,16.3,45
-1533752054,18.7,42
-1533752055,40.1,39
-1533752056,40.1,39
+1533752053 16.3 45
+1533752054 18.7 42
+1533752055 40.1 39
+1533752056 40.1 39
.Ed
.
.
.Sh SEE ALSO
.
+.Xr ploot-braille 1 ,
+.Xr ploot-farbfeld 1 ,
.Xr ploot-feed 1 ,
-.Xr ploot-farbfeld 1
.
.Sh HISTORY
.
.Nm
-was defined at
-.Lk gopher://bitreich.org/1/scm/ploot/ "Bitreich"
+is developped at
+.Bl -ohang
+.It
+.Lk gopher://bitreich.org/1/scm/ploot/ "Bitreich project index"
+.It
+.Lk git://bitreich.org/1/ploot/ "Bitreich public repo"
+.El
.
.
.Sh AUTHORS