commit 6a585109cd20d01edb3c76cd80849fae4b541990
parent 4892f24a05bd9c6466faa19bdcc99f5f4647661e
Author: nibo <nibo@relim.de>
Date: Sat, 25 Jan 2025 11:14:18 +0100
Write some documentation
Diffstat:
| M | lorid.1 | | | 65 | +++++++++++++++++++++++++++++++++++++++++++++++++++-------------- |
| A | lorid_config.5 | | | 212 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
2 files changed, 263 insertions(+), 14 deletions(-)
diff --git a/lorid.1 b/lorid.1
@@ -3,19 +3,29 @@
lorid \- convert chordpro to pdf
.SH SYNOPSIS
.B lorid
-[-p] [-c \fI\,FILE\/\fR] [-v] [-h] [-o \fI\,path\/\fR] [\fI\,FILE\/\fR ...]
+[-o
+.IR PATH ]
+[-c
+.IR CONFIGFILE ]
+[-pvVh]
+.RI [ FILE
+\&...]
.SH DESCRIPTION
.PP
.B lorid
-reads text from one or more \fI\,FILE\/\fR's
+reads text from one or more
+.IR FILE 's
and if no
.I FILE
was provided then from stdin.
The text will be parsed according to the chordpro specification
and then converted to pdf. These two steps can be altered by
changing the configuration file.
-.TP
-\fB\,-o\/\fR, \fB\,--output\/\fR
+
+.BR -o ,
+.B --output
+.I PATH
+.RS 7
Specify an output file or folder.
If you specify a file the generated pdf file will be saved
@@ -35,23 +45,50 @@ song title in kebab case.
If lorid finds more than one song it will use the
filename 'collection-of-songs.pdf'.
+.RE
-.TP
-\fB\,-p\/\fR, \fB\,--print-default-config\/\fR
-Print the default configuration as TOML.
-.TP
-\fB\,-c\/\fR, \fB\,--config\/\fR \fI\,FILE\/\fR
+.BR -c ,
+.B --config
+.I CONFIGFILE
+.RS 7
Specify a configuration file.
By default the file
.B ~/.config/lorid/config.toml
will be used as the configuration file.
-.TP
-\fB\,-v\/\fR, \fB\,--version\/\fR
+.RE
+
+.BR -p ,
+.B --print-default-config
+.RS 7
+Print the default configuration as TOML.
+.RE
+
+.BR -v ,
+.B --verbose
+.RS 7
+Print INFO messages to stderr.
+
+By default only WARN and ERR messages are printed to stderr.
+.RE
+
+.BR -V ,
+.B --version
+.RS 7
Print the program version.
-.TP
-\fB\,-h\/\fR, \fB\,--help\/\fR
-Print a short message to help use the program.
+.RE
+
+.BR -h ,
+.B --help
+.RS 7
+Open
+.BR lorid 's
+man page.
+.RE
+
+.SH SEE ALSO
+.BR lorid_config (5)
+
.SH CHORDPRO
.PP
You can find the chordpro specification at https://www.chordpro.org/chordpro/.
diff --git a/lorid_config.5 b/lorid_config.5
@@ -0,0 +1,212 @@
+.TH LORID_CONFIG "5" "January 2025" "File Formats Manual"
+.SH NAME
+.B ~/.config/lorid/config.toml
+- lorid configuration file
+.SH DESCRIPTION
+The config file has the TOML file format.
+
+Run
+.RB ` lorid
+.BR --print-default-config `
+for an example config.
+.SS [notes]
+In this section you can define custom notation systems.
+A few notation systems are predefined. These are:
+.BR common ,
+.BR german ,
+.BR scandinavian ,
+.BR latin ,
+.BR roman
+and
+.BR nashville .
+A notation system is an array of exactly seven tables.
+Each table has the key 'note' and depending on the array position also has the keys 'sharp' and/or 'flat'.
+To see the predefined notation systems execute
+.B lorid
+.BR --print-default-config .
+
+Example:
+
+.RS 4
+.EX
+common = [
+ { note = "C", sharp = "C#", },
+ { note = "D", sharp = "D#", flat = "Db" },
+ { note = "E", flat = "Eb" },
+ { note = "F", sharp = "F#", },
+ { note = "G", sharp = "G#", flat = "Gb" },
+ { note = "A", sharp = "A#", flat = "Ab" },
+ { note = "B", flat = "Bb" },
+]
+.EE
+.RE
+.SS [parser]
+.SS [parser.chords]
+mode = String
+
+=> allowed values: "strict", "relaxed"
+
+.RS 4
+Currently this setting doesn't have any effect.
+.RE
+
+system = String
+
+=> allowed values: "common", "german", "scandinavian", "latin", "roman", "nashville", "<custom>"
+
+.RS 4
+Specify a predefined or custom notation system from the [notes] section.
+When parsing chordpro text only chords from this selected notation system are recognized. Notice that unrecognized chords are only problematic if you want to transpose them or show their chord diagrams.
+.RE
+.SS [output]
+system = String
+
+=> allowed values: "common", "german", "scandinavian", "latin", "roman", "nashville", "<custom>"
+
+.RS 4
+Specify a predefined or custom notation system from the [notes] section.
+When generating the PDF file chords from this selected notation system will be printed.
+.RE
+
+page_no_position = String
+
+=> allowed values: "left", "center", "right"
+
+.RS 4
+At the bottom of each PDF page a page number will be shown.
+This controls the page number's alignment.
+.RE
+
+.SS [output.toc]
+show = Boolean
+
+.RS 4
+Control whether to show the table of contents.
+.RE
+
+title = String
+
+=> allowed values: any
+
+.RS 4
+The specified string will be shown centered and above the table of contents.
+.RE
+
+.SS [output.chord_diagram]
+show = Boolean
+
+.RS 4
+Control whether to show chord diagrams of recognized chords at the bottom of the first page of the song.
+.RE
+
+instrument = String
+
+=> allowed values: "guitar", "keyboard", "mandolin", "ukulele"
+
+.RS 4
+The instrument controls which style the chord diagram has.
+
+In case of "guitar", "mandolin" or "ukulele" the chord diagram shows part of a fretboard.
+The number of strings shown is controlled by the number of frets that the chord diagram defines.
+Every instrument comes with a few predefined chord diagrams.
+Predefined guitar chord diagrams have six frets.
+Predefined mandolin chord diagrams have four frets.
+Predefined ukulele chord diagrams have also four frets.
+
+In case of "keyboard" the chord diagram shows part of a fingerboard.
+.RE
+
+.SS [output.chorus]
+
+This section controls the output of the {chorus} directive.
+
+label = String
+
+=> allowed values: any
+
+.RS 4
+If you didn't specify a directive label this is the default label text.
+.RE
+
+quote = Boolean
+
+.RS 4
+Control whether to print the last previously defined chorus.
+.RE
+
+.SS [output.styles]
+
+In this section you can control the style of various parts of the song or the PDF page. The following styles are available:
+.BR chord ,
+.BR annotation ,
+.BR chorus , \" .BR footer ,
+.BR grid ,
+.BR tab ,
+.BR toc ,
+.BR toc_title ,
+.BR text ,
+.BR title ,
+.BR subtitle ,
+.BR label ,
+.BR comment ,
+.BR comment_italic ,
+.BR comment_box .
+
+If you set the color of something you can provide a hex color code or one of the following predefined color values:
+.BR \e"red" ,
+.BR "green" ,
+
+.SS [output.styles.<style>]
+
+foreground_color = String
+
+=> allowed values: 4 or 7 characters long hex color code, "red", "green", "blue", "yellow", "magenta", "cyan", "white", "grey", "black"
+
+background_color = String
+
+=> allowed values: 4 or 7 characters long hex color code, "red", "green", "blue", "yellow", "magenta", "cyan", "white", "grey", "black"
+
+underline_style = String
+
+=> allowed values: "single", "double", "none"
+
+underline_color = String
+
+=> allowed values: 4 or 7 characters long hex color code, "red", "green", "blue", "yellow", "magenta", "cyan", "white", "grey", "black"
+
+overline_style = String
+
+=> allowed values: "single", "double", "none"
+
+overline_color = String
+
+=> allowed values: 4 or 7 characters long hex color code, "red", "green", "blue", "yellow", "magenta", "cyan", "white", "grey", "black"
+
+strikethrough = Boolean
+
+strikethrough_color = String
+
+=> allowed values: 4 or 7 characters long hex color code, "red", "green", "blue", "yellow", "magenta", "cyan", "white", "grey", "black"
+
+boxed = Boolean
+
+.RS 4
+Control whether a rectangle is drawn around the text.
+.RE
+
+boxed_color = String
+
+=> allowed values: 4 or 7 characters long hex color code, "red", "green", "blue", "yellow", "magenta", "cyan", "white", "grey", "black"
+
+rise = Float
+
+href = String
+
+=> allowed values: any
+
+.RS 4
+Clicking on the corresponding text tries to open the provided href in a browser.
+.RE
+
+.SH SEE ALSO
+.BR lorid (1)