From 37ae26f3382bb9f040399930cd5b1ee15a7cfba8 Mon Sep 17 00:00:00 2001 From: Mischa POSLAWSKY Date: Tue, 29 Nov 2022 03:41:03 +0100 Subject: [PATCH] bold option item titles in pod Follow recommended man page formatting as described by groff_man_style(7), in particular bold for command-line options and literal input, italics for variables and constants, instead of syntax resembling git documentation but without the semantics from asciidoc. --- barcat | 106 +++++++++++++++++++++++----------------------- reformat-podusage | 11 ++--- 2 files changed, 59 insertions(+), 58 deletions(-) diff --git a/barcat b/barcat index 3eb004e..fe8c11d 100755 --- a/barcat +++ b/barcat @@ -476,7 +476,7 @@ barcat - concatenate texts with graph to visualize values =head1 SYNOPSIS -B [] [... | ] +B [I] [I... | I] =head1 DESCRIPTION @@ -495,68 +495,68 @@ you'll need a larger animal like I. =over -=item -a, --[no-]ascii +=item B<-a>, B<-->[B]B Restrict user interface to ASCII characters, replacing default UTF-8 by their closest approximation. Input is always interpreted as UTF-8 and shown as is. -=item -C, --[no-]color +=item B<-C>, B<-->[B]B Force colored output of values and bar markers. Defaults on if output is a tty, disabled otherwise such as when piped or redirected. -Can also be disabled by setting I<-M> +Can also be disabled by setting B<-M> or the I environment variable. -=item -f, --field=([+] | ) +=item B<-f>, B<--field>=([B<+>]I | I) Compare values after a given number of whitespace separators, or matching a regular expression. -Unspecified or I<-f0> means values are at the start of each line. -With I<-f1> the second word is taken instead. +Unspecified or B<-f0> means values are at the start of each line. +With B<-f1> the second word is taken instead. A string can indicate the starting position of a value -(such as I<-f:> if preceded by colons), +(such as B<-f:> if preceded by colons), or capture the numbers itself, -for example I<-f'(\d+)'> for the first digits anywhere. -A shorthand for this is I<+0>, or I<+N> to find the Nth number. +for example B<-f'(\d+)'> for the first digits anywhere. +A shorthand for this is C<+0>, or C<+N> to find the Nth number. -=item --header +=item B<--header> Prepend a chart axis with minimum and maximum values labeled. -=item -H, --human-readable +=item B<-H>, B<--human-readable> Format values using SI unit prefixes, -turning long numbers like I<12356789> into I<12.4M>. -Also changes an exponent I<1.602176634e-19> to I<160.2z>. +turning long numbers like C<12356789> into C<12.4M>. +Also changes an exponent C<1.602176634e-19> to C<160.2z>. Short integers are aligned but kept without decimal point. -=item --sexagesimal +=item B<--sexagesimal> Convert seconds to HH:MM:SS time format. -=item -t, --interval[=( | -)] +=item B<-t>, B<--interval>[=(I | B<->I)] Output partial progress every given number of seconds or input lines. An update can also be forced by sending a I alarm signal. -=item -l, --length=[-][%] +=item B<-l>, B<--length>=[B<->]I[B<%>] Trim line contents (between number and bars) to a maximum number of characters. The exceeding part is replaced by an abbreviation sign, -unless C<--length=0>. +unless B<--length=0>. Prepend a dash (i.e. make negative) to enforce padding regardless of encountered contents. -=item -L, --limit=[ | [-](-[] | +)] +=item B<-L>, B<--limit>=[I | [B<->]I(B<->[I] | B<+>I)] Select a range of lines to display. -A single integer indicates the last line number (like C), -or first line counting from the bottom if negative (like C). +A single integer indicates the last line number (like I), +or first line counting from the bottom if negative (like I). A range consists of a starting line number followed by either a dash C<-> to an optional end, or plus sign C<+> with count. @@ -564,87 +564,87 @@ a dash C<-> to an optional end, or plus sign C<+> with count. All hidden input is still counted and analyzed for statistics, but disregarded for padding and bar size. -=item -e, --log +=item B<-e>, B<--log> -Logarithmic (Ixponential) scale instead of linear +Logarithmic (Bxponential) scale instead of linear to compare orders of magnitude. -=item --graph-format= +=item B<--graph-format>=I Glyph to repeat for the graph line. Defaults to a dash C<->. -=item -m, --markers= +=item B<-m>, B<--markers>=I Statistical positions to indicate on bars. A single indicator glyph precedes each position: =over 2 -=item +=item I Exact value to match on the axis. -A vertical bar at the zero crossing is displayed by I<|0> +A vertical bar at the zero crossing is displayed by C<|0> for negative values. -For example I<π3.14> would locate pi. +For example C<π3.14> would locate pi. -=item I +=item BI Repeated at every multiple of a number. -For example I<:/1> for a grid at every integer. +For example C<:/1> for a grid at every integer. -=item I +=item IB Ranked value at the given percentile. -The default shows I<+> at I<50v> for the mean or median; +The default shows C<+> at C<50v> for the mean or median; the middle value or average between middle values. -One standard deviation right of the mean is at about I<68.3v>. -The default includes I<< >31.73v <68.27v >> -to encompass all I results, or 68% of all entries, by B<< <--> >>. +One standard deviation right of the mean is at about C<68.3v>. +The default includes C<< >31.73v <68.27v >> +to encompass all I results, or 68% of all entries, by I<< <--> >>. -=item I +=item B Matches the average; the sum of all values divided by the number of counted lines. -Indicated by default as I<=>. +Indicated by default as C<=>. =back -=item --min=, --max= +=item B<--min>=I, B<--max>=I Bars extend from 0 or the minimum value if lower, to the largest value encountered. These options can be set to customize this range. -=item --palette=( | ...) +=item B<--palette>=(I | I...) Override colors of parsed numbers. -Can be any CSI escape, such as I<90> for default dark grey, -or alternatively I<1;30> for bright black. +Can be any CSI escape, such as C<90> for default dark grey, +or alternatively C<1;30> for bright black. In case of additional colors, the last is used for values equal to the maximum, the first for minima. -If unspecified, these are green and red respectively (I<31 90 32>). +If unspecified, these are green and red respectively (C<31 90 32>). Multiple intermediate colors will be distributed relative to the size of values. Predefined color schemes are named I and I, or I and I for 256-color variants. -=item -_, --spark +=item B<-_>, B<--spark> Replace lines by I, -single characters (configured by C<--indicators>) +single characters (configured by B<--indicators>) corresponding to input values. -=item --indicators[=] +=item B<--indicators>[=I] Prefix a unicode character corresponding to each value. The first specified character will be used for non-values, the remaining sequence will be distributed over the range of values. Unspecified, block fill glyphs U+2581-2588 will be used. -=item -s, --stat +=item B<-s>, B<--stat> Total statistics after all data. @@ -652,32 +652,32 @@ While processing (possibly a neverending pipe), intermediate results are also shown on signal I if available (control+t on BSDs) or I otherwise (ctrl+\ on linux). -=item -u, --unmodified +=item B<-u>, B<--unmodified> Do not reformat values, keeping leading whitespace. Keep original value alignment, which may be significant in some programs. -=item --value-length= +=item B<--value-length>=I Reserved space for numbers. -=item -w, --width= +=item B<-w>, B<--width>=I Override the maximum number of columns to use. Appended graphics will extend to fill up the entire screen, otherwise determined by the environment variable I -or by running the C command. +or by running the I command. -=item -h, --usage +=item B<-h>, B<--usage> Overview of available options. -=item --help +=item B<--help> Full pod documentation as rendered by perldoc. -=item -V, --version +=item B<-V>, B<--version> Version information. diff --git a/reformat-podusage b/reformat-podusage index c40363d..4fe82a3 100755 --- a/reformat-podusage +++ b/reformat-podusage @@ -5,24 +5,25 @@ use utf8; use open qw( :std :utf8 ); use re '/msx'; -our $VERSION = '1.00'; +our $VERSION = '1.01'; local $/ = undef; # slurp my $source = readline; my $pod = $source; $pod =~ s/^=over\K/ 25/; # indent options list +$pod =~ s/[BC]<([^>]+)>/$1/g; # unbolden $pod =~ s{ ^=item \h \N*\n\n \N*\n \K # first line (?: (?: ^=over .*? ^=back\n )? (?!=) \N*\n )* }{\n}g; # abbreviate options -$pod =~ s/[.,](?=\n)//g; # trailing punctuation $pod =~ s/^=item\ \K(?=--)/____/g; # align long options # abbreviate indicators $pod =~ s/\Q>.../s>/g; -$pod =~ s/<(?:number|count|seconds)>/N/g; -$pod =~ s//\Uchar$1/g; +$pod =~ s/I<(?:number|count|seconds)>/N/g; +$pod =~ s/I/\Uchar$1/g; $pod =~ s/\Q | /|/g; -$pod =~ s/(?/\U$1/g; # uppercase +$pod =~ s/I<([a-z]+)> (?![.,])/\U$1/g; # uppercase +$pod =~ s/[.,](?=\n)//g; # trailing punctuation require Pod::Usage; my $parser = Pod::Usage->new(USAGE_OPTIONS => { -- 2.30.0