Properly tag monospaced text in man pages. (Improves HTML rendering) (#3509)
This would be immediately useful to improve the rendering of the man pages in third-party websites such as manned.org and the arch man pagesk - https://mankier.com/1/task - https://man.archlinux.org/man/task.1 The regular console output, or websites which render the manpage in monospaced fonts, will not be affected by this change. This change could also help with eventually rendering the manpages in the documentation website, and having a mix of monospaced and variable width fonts. To test the HTML output: ```bash git clone git@github.com:jacksonp/manner.git # used by ManKier ./manner/manner.php task.1.in >| task.1.html && $BROWSER task.1.html ``` Co-authored-by: Sebastian Carlos <sebastiancarlos@gmail.com>
This commit is contained in:
Sebastian Carlos
GitHub
@@ -8,14 +8,18 @@ It should be mentioned that Taskwarrior is aware of whether its output is going
|
||||
to a terminal, or to a file or through a pipe. When Taskwarrior output goes to
|
||||
a terminal, color is desirable, but consider the following command:
|
||||
|
||||
.nf
|
||||
$ task list > file.txt
|
||||
.fi
|
||||
|
||||
Do we really want all those color control codes in the file? Taskwarrior
|
||||
assumes that you do not, and temporarily sets color to 'off' while generating
|
||||
the output. This explains the output from the following command:
|
||||
|
||||
.nf
|
||||
$ task show | grep '^color '
|
||||
color off
|
||||
.fi
|
||||
|
||||
it always returns 'off', no matter what the setting, because the output is being
|
||||
sent to a pipe.
|
||||
@@ -23,20 +27,26 @@ sent to a pipe.
|
||||
If you wanted those color codes, you can override this behavior by setting the
|
||||
_forcecolor variable to on, like this:
|
||||
|
||||
.nf
|
||||
$ task config _forcecolor on
|
||||
$ task config | grep '^color '
|
||||
color on
|
||||
.fi
|
||||
|
||||
or by temporarily overriding it like this:
|
||||
|
||||
.nf
|
||||
$ task rc._forcecolor=on config | grep '^color '
|
||||
color on
|
||||
.fi
|
||||
|
||||
.SH AVAILABLE COLORS
|
||||
Taskwarrior has a 'color' command that will show all the colors it is capable of
|
||||
displaying. Try this:
|
||||
|
||||
.nf
|
||||
$ task color
|
||||
.fi
|
||||
|
||||
The output cannot be replicated here in a man page, but you should see a set of
|
||||
color samples. How many you see depends on your terminal program's ability to
|
||||
@@ -48,7 +58,9 @@ You should at least see the Basic colors and Effects - if you do, then you have
|
||||
.SH 16-COLOR SUPPORT
|
||||
The basic color support is provided through named colors:
|
||||
|
||||
.nf
|
||||
black, red, blue, green, magenta, cyan, yellow, white
|
||||
.fi
|
||||
|
||||
Foreground color (for text) is simply specified as one of the above colors, or
|
||||
not specified at all to use the default terminal text color.
|
||||
@@ -56,37 +68,49 @@ not specified at all to use the default terminal text color.
|
||||
Background color is specified by using the word 'on', and one of the above
|
||||
colors. Some examples:
|
||||
|
||||
.nf
|
||||
green # green text, default background color
|
||||
green on yellow # green text, yellow background
|
||||
on yellow # default text color, yellow background
|
||||
.fi
|
||||
|
||||
These colors can be modified further, by making the foreground bold, or by
|
||||
making the background bright. Some examples:
|
||||
|
||||
.nf
|
||||
bold green
|
||||
bold white on bright red
|
||||
on bright cyan
|
||||
.fi
|
||||
|
||||
The order of the words is not important, so the following are equivalent:
|
||||
|
||||
.nf
|
||||
bold green
|
||||
green bold
|
||||
.fi
|
||||
|
||||
But the 'on' is important - colors before the 'on' are foreground, and colors
|
||||
after 'on' are background.
|
||||
|
||||
There is an additional 'underline' attribute that may be used:
|
||||
|
||||
.nf
|
||||
underline bold red on black
|
||||
.fi
|
||||
|
||||
And an 'inverse' attribute:
|
||||
|
||||
.nf
|
||||
inverse red
|
||||
.fi
|
||||
|
||||
Taskwarrior has a command that helps you visualize these color combinations.
|
||||
Try this:
|
||||
|
||||
.nf
|
||||
$ task color underline bold red on black
|
||||
.fi
|
||||
|
||||
You can use this command to see how the various color combinations work. You
|
||||
will also see some sample colors displayed, like the ones above, in addition to
|
||||
@@ -103,11 +127,13 @@ Using 256 colors follows the same form, but the names are different, and some
|
||||
colors can be referenced in different ways. First there is by color ordinal,
|
||||
which is like this:
|
||||
|
||||
.nf
|
||||
color0
|
||||
color1
|
||||
color2
|
||||
...
|
||||
color255
|
||||
.fi
|
||||
|
||||
This gives you access to all 256 colors, but doesn't help you much. This range
|
||||
is a combination of 8 basic colors (color0 - color7), then 8 brighter variations
|
||||
@@ -119,31 +145,43 @@ be addressed via RGB values from 0 to 5 for each component color. A value of 0
|
||||
means none of this component color, and a value of 5 means the most intense
|
||||
component color. For example, a bright red is specified as:
|
||||
|
||||
.nf
|
||||
rgb500
|
||||
.fi
|
||||
|
||||
And a darker red would be:
|
||||
|
||||
.nf
|
||||
rgb300
|
||||
.fi
|
||||
|
||||
Note that the three digits represent the three component values, so in this
|
||||
example the 5, 0 and 0 represent red=5, green=0, blue=0. Combining intense red
|
||||
with no green and no blue yields red. Similarly, blue and green are:
|
||||
|
||||
.nf
|
||||
rgb005
|
||||
rgb050
|
||||
.fi
|
||||
|
||||
Another example - bright yellow - is a mix of bright red and bright green, but
|
||||
no blue component, so bright yellow is addressed as:
|
||||
|
||||
.nf
|
||||
rgb550
|
||||
.fi
|
||||
|
||||
A soft pink would be addressed as:
|
||||
|
||||
.nf
|
||||
rgb515
|
||||
.fi
|
||||
|
||||
See if you agree, by running:
|
||||
|
||||
.nf
|
||||
$ task color black on rgb515
|
||||
.fi
|
||||
|
||||
You may notice that the large color block is represented as 6 squares. All
|
||||
colors in the first square have a red value of 0. All colors in the 6th square
|
||||
@@ -163,7 +201,9 @@ will be disappointed, perhaps even appalled.
|
||||
There is some limited color mapping - for example, if you were to specify this
|
||||
combination:
|
||||
|
||||
.nf
|
||||
red on gray3
|
||||
.fi
|
||||
|
||||
you are mixing a 16-color and 256-color specification. Taskwarrior will map red
|
||||
to color1, and proceed. Note that red and color1 are not quite the same tone.
|
||||
@@ -175,7 +215,9 @@ colors, but there is still underline available.
|
||||
Taskwarrior will show examples of all defined colors used in your .taskrc, or
|
||||
theme, if you run this command:
|
||||
|
||||
.nf
|
||||
$ task color legend
|
||||
.fi
|
||||
|
||||
This gives you an example of each of the colors, so you can see the effect,
|
||||
without necessarily creating a set of tasks that meet each of the rule criteria.
|
||||
@@ -185,20 +227,26 @@ Taskwarrior supports colorization rules. These are configuration values that
|
||||
specify a color, and the conditions under which that color is used. By example,
|
||||
let us add a few tasks:
|
||||
|
||||
.nf
|
||||
$ task add project:Home priority:H pay the bills (1)
|
||||
$ task add project:Home clean the rug (2)
|
||||
$ task add project:Garden clean out the garage (3)
|
||||
.fi
|
||||
|
||||
We can add a color rule that uses a blue background for all tasks in the Home
|
||||
project:
|
||||
|
||||
.nf
|
||||
$ task config color.project.Home 'on blue'
|
||||
.fi
|
||||
|
||||
We use quotes around 'on blue' because there are two words, but they represent
|
||||
one value in the .taskrc file. Now suppose we wish to use a bold yellow text
|
||||
color for all cleaning work:
|
||||
|
||||
.nf
|
||||
$ task config color.keyword.clean 'bold yellow'
|
||||
.fi
|
||||
|
||||
Now what happens to task 2, which belongs to project Home (blue background), and
|
||||
is also a cleaning task (bold yellow foreground)? The colors are combined, and
|
||||
@@ -219,7 +267,9 @@ color blending.
|
||||
The precedence for the color rules is determined by the configuration
|
||||
variable 'rule.precedence.color', which by default contains:
|
||||
|
||||
.nf
|
||||
deleted,completed,active,keyword.,tag.,project.,overdue,scheduled,due.today,due,blocked,blocking,recurring,tagged,uda.
|
||||
.fi
|
||||
|
||||
These are just the color rules with the 'color.' prefix removed. The
|
||||
rule 'color.deleted' has the highest precedence, and 'color.uda.' the lowest.
|
||||
@@ -238,50 +288,38 @@ be included.
|
||||
To get a good idea of what a color theme looks like, try adding this entry to
|
||||
your .taskrc file:
|
||||
|
||||
.RS
|
||||
include dark-256.theme
|
||||
.RE
|
||||
.nf
|
||||
include dark-256.theme
|
||||
.fi
|
||||
|
||||
You can use any of the standard Taskwarrior themes:
|
||||
|
||||
.RS
|
||||
dark-16.theme
|
||||
.br
|
||||
dark-256.theme
|
||||
.br
|
||||
dark-blue-256.theme
|
||||
.br
|
||||
dark-gray-256.theme
|
||||
.br
|
||||
dark-green-256.theme
|
||||
.br
|
||||
dark-red-256.theme
|
||||
.br
|
||||
dark-violets-256.theme
|
||||
.br
|
||||
dark-yellow-green.theme
|
||||
.br
|
||||
light-16.theme
|
||||
.br
|
||||
light-256.theme
|
||||
.br
|
||||
solarized-dark-256.theme
|
||||
.br
|
||||
solarized-light-256.theme
|
||||
.br
|
||||
dark-default-16.theme
|
||||
.br
|
||||
dark-gray-blue-256.theme
|
||||
.br
|
||||
no-color.theme
|
||||
.RE
|
||||
.nf
|
||||
dark-16.theme
|
||||
dark-256.theme
|
||||
dark-blue-256.theme
|
||||
dark-gray-256.theme
|
||||
dark-green-256.theme
|
||||
dark-red-256.theme
|
||||
dark-violets-256.theme
|
||||
dark-yellow-green.theme
|
||||
light-16.theme
|
||||
light-256.theme
|
||||
solarized-dark-256.theme
|
||||
solarized-light-256.theme
|
||||
dark-default-16.theme
|
||||
dark-gray-blue-256.theme
|
||||
no-color.theme
|
||||
.fi
|
||||
|
||||
Bear in mind that if you are using a terminal with a dark background, you will
|
||||
see better results using a dark theme.
|
||||
|
||||
You can also see how the theme will color the various tasks with the command:
|
||||
|
||||
.nf
|
||||
$ task color legend
|
||||
.fi
|
||||
|
||||
Better yet, create your own, and share it. We will gladly host the theme file
|
||||
on <https://taskwarrior.org>.
|
||||
|
||||
Reference in New Issue
Block a user