| [ << ] | jpayne@68:[ >> ] | jpayne@68:jpayne@68: | jpayne@68: | jpayne@68: | jpayne@68: | jpayne@68: | [Top] | jpayne@68:[Contents] | jpayne@68:[Index] | jpayne@68:[ ? ] | jpayne@68:
Styled output can viewed fine in a console or terminal emulator window. jpayne@68:
jpayne@68:The stylable program will typically have the following options: jpayne@68:
--colorUse colors and other text attributes always. jpayne@68:
--color=whenUse colors and other text attributes if when. when may be
jpayne@68: always, never, auto, or html.
jpayne@68:
--style=style-fileSpecify the CSS style rule file for --color.
jpayne@68:
For more details, see the sections The --color option and
jpayne@68: The --style option below.
jpayne@68:
If the output does not fit on a screen, you can use ‘less -R’ to jpayne@68: scroll around in the styled output. For example: jpayne@68:
program --color arguments | less -R jpayne@68: |
TERM The environment variable TERM contains a identifier for the text
jpayne@68: window's capabilities. You can get a detailed list of these cababilities
jpayne@68: by using the ‘infocmp’ command (for example: infocmp -L1 xterm),
jpayne@68: using ‘man 5 terminfo’ as a reference.
jpayne@68:
When producing text with embedded color directives, a
jpayne@68: libtextstyle-enabled program looks at the TERM variable.
jpayne@68: Text windows today typically support at least 8 colors. Often, however,
jpayne@68: the text window supports 16 or more colors, even though the TERM
jpayne@68: variable is set to a identifier denoting only 8 supported colors. It
jpayne@68: can be worth setting the TERM variable to a different value in
jpayne@68: these cases.
jpayne@68:
After setting TERM, you can verify how well it works by invoking
jpayne@68: ‘program --color=test’, where program is any
jpayne@68: libtextstyle-enabled program, and seeing whether the output looks
jpayne@68: like a reasonable color map.
jpayne@68:
The following terminal emulator programs support 256 colors and set
jpayne@68: TERM=xterm-256color accordingly:
jpayne@68:
gnome-terminal, tilda.
jpayne@68: rxvt-unicode (sets TERM=rxvt-unicode-256color).
jpayne@68: st (sets TERM=st-256color).
jpayne@68: QTerminal.
jpayne@68: Terminal, iTerm2.
jpayne@68: The following terminal emulator programs support 256 colors. You only
jpayne@68: need to set TERM=xterm-256color or similar; the programs by default
jpayne@68: set TERM to a value that supports only 8 colors.
jpayne@68:
xterm is in many cases built with support for 256 colors. But it
jpayne@68: sets TERM=xterm. You need to set TERM=xterm-256color.
jpayne@68: guake (sets TERM=xterm). You need to set
jpayne@68: TERM=xterm-256color.
jpayne@68: konsole (sets TERM=xterm). You need to set
jpayne@68: TERM=xterm-256color or TERM=konsole-256color.
jpayne@68: yakuake (sets TERM=xterm). You need to set
jpayne@68: TERM=xterm-256color.
jpayne@68: Eterm (sets TERM=Eterm). You need to set
jpayne@68: TERM=Eterm-256color.
jpayne@68: mlterm (sets TERM=mlterm). You need to set
jpayne@68: TERM=mlterm-256color.
jpayne@68: PuTTY (sets TERM=xterm). You need to set
jpayne@68: TERM=xterm-256color or TERM=putty-256color.
jpayne@68: TeraTerm (sets TERM=xterm). You need to set
jpayne@68: TERM=xterm-256color.
jpayne@68: A couple of terminal emulator programs support even the entire RGB color jpayne@68: space (16 million colors). To get this to work, at this date (2019), you jpayne@68: need three things: jpayne@68:
ncurses library version 6.1 or newer must be installed.
jpayne@68: TERM environment variable to the corresponding
jpayne@68: value:
jpayne@68: TERM=xterm-direct instead of
jpayne@68: TERM=xterm or TERM=xterm-256color,
jpayne@68: TERM=konsole-direct in konsole,
jpayne@68: TERM=st-direct in st,
jpayne@68: TERM=mlterm-direct in mlterm,
jpayne@68: or TERM=iterm2-direct in iTerm2 on macOS.
jpayne@68: On OpenBSD 6 consoles, TERM=xterm produces better results than the
jpayne@68: default TERM=vt220.
jpayne@68:
On NetBSD 8 consoles, TERM=netbsd6 produces better results than the
jpayne@68: default TERM=vt100.
jpayne@68:
On Windows consoles, no TERM setting is needed.
jpayne@68:
NO_COLOR The environment variable NO_COLOR can be used to suppress styling
jpayne@68: in the textual output. When this environment variable is set (to any value),
jpayne@68: libtextstyle-enabled programs will not emit colors and other text
jpayne@68: styling.
jpayne@68:
This environment variable can be overridden by passing the command-line option
jpayne@68: ‘--color=always’ (see The --color option).
jpayne@68:
NO_TERM_HYPERLINKS The environment variable NO_TERM_HYPERLINKS can be used to suppress
jpayne@68: hyperlinks in the textual output. When this environment variable is set
jpayne@68: (to any value), libtextstyle-enabled programs will not emit
jpayne@68: hyperlinks. This may be useful for terminal emulators which produce
jpayne@68: garbage output when they receive the escape sequence for a hyperlink.
jpayne@68: Currently (as of 2019), this affects some versions of
jpayne@68: konsole, emacs, lxterminal, guake, yakuake, rxvt.
Emacs has several terminal emulators: M-x shell and
jpayne@68: M-x term. M-x term has good support for styling, whereas
jpayne@68: in M-x shell most of the styling gets lost.
jpayne@68:
--color option The ‘--color=when’ option specifies under which conditions jpayne@68: styled (colorized) output should be generated. The when part can jpayne@68: be one of the following: jpayne@68:
jpayne@68:alwaysyesThe output will be colorized. jpayne@68:
jpayne@68:nevernoThe output will not be colorized. jpayne@68:
jpayne@68:autottyThe output will be colorized if the output device is a tty, i.e. when jpayne@68: the output goes directly to a text screen or terminal emulator window. jpayne@68:
jpayne@68:htmlThe output will be colorized and be in HTML format. This value is only jpayne@68: supported by some programs. jpayne@68:
jpayne@68:testThis is a special value, understood only by some programs. It is
jpayne@68: explained in the section (The environment variable TERM) above.
jpayne@68:
‘--color’ is equivalent to ‘--color=yes’. The default is jpayne@68: ‘--color=auto’. jpayne@68:
jpayne@68:Thus, a command that invokes a libtextstyle-enabled program will
jpayne@68: produce colorized output when called by itself in a command window.
jpayne@68: Whereas in a pipe, such as ‘program arguments | less -R’,
jpayne@68: it will not produce colorized output. To get colorized output in this
jpayne@68: situation nevertheless, use the command
jpayne@68: ‘program --color arguments | less -R’.
jpayne@68:
The ‘--color=html’ option will produce output that can be viewed in jpayne@68: a browser. This can be useful, for example, for Indic languages, jpayne@68: because the renderic of Indic scripts in browsers is usually better than jpayne@68: in terminal emulators. jpayne@68:
jpayne@68:Note that the output produced with the --color option is
jpayne@68: not consumable by programs that expect the raw text. It contains
jpayne@68: additional terminal-specific escape sequences or HTML tags. For example,
jpayne@68: an XML parser will give a syntax error when confronted with a colored XML
jpayne@68: output. Except for the ‘--color=html’ case, you therefore normally
jpayne@68: don't need to save output produced with the --color option in a
jpayne@68: file.
jpayne@68:
--style option The ‘--style=style_file’ option specifies the style file to
jpayne@68: use when colorizing. It has an effect only when the --color
jpayne@68: option is effective.
jpayne@68:
If the --style option is not specified, the program may consider
jpayne@68: the value of an environment variable. It is meant to point to the user's
jpayne@68: preferred style for such output. The name of such an environment
jpayne@68: variable, if supported, is documented in the documentation of the
jpayne@68: libtextstyle-enabled program.
jpayne@68:
You can also design your own styles. This is described in the next jpayne@68: section. jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:The same style file can be used for styling a certain type of output, for jpayne@68: terminal output and for HTML output. It is written in CSS jpayne@68: (Cascading Style Sheet) syntax. See jpayne@68: https://www.w3.org/TR/css2/cover.html for a formal definition of jpayne@68: CSS. Many HTML authoring tutorials also contain explanations of CSS. jpayne@68:
jpayne@68:In the case of HTML output, the style file is embedded in the HTML output.
jpayne@68: In the case of text output, the style file is interpreted by the
jpayne@68: libtextstyle-enabled program.
jpayne@68:
You should avoid @import statements, because
jpayne@68:
@import
jpayne@68: statements would not be embedded in the HTML output. In fact, relative
jpayne@68: file names would be interpreted relative to the resulting HTML file.
jpayne@68: @imports are not supported, due to a
jpayne@68: limitation in libcroco.
jpayne@68: CSS rules are built up from selectors and declarations. The declarations jpayne@68: specify graphical properties; the selectors specify when they apply. jpayne@68:
jpayne@68:GNU libtextstyle supports simple selectors based on "CSS classes", see
jpayne@68: the CSS2 spec, section 5.8.3. The set of CSS classes that are supported
jpayne@68: by a libtextstyle-enabled program are documented in the
jpayne@68: documentation of that program.
jpayne@68:
These selectors can be combined to hierarchical selectors. For example,
jpayne@68: assume a program supports the CSS classes string (that matches a
jpayne@68: string) and non-ascii (that matches a word with non-ASCII
jpayne@68: characters), you could write
jpayne@68:
.string .non-ascii { color: red; }
jpayne@68: |
to highlight only the non-ASCII words inside strings. jpayne@68:
jpayne@68:In text mode, pseudo-classes (CSS2 spec, section 5.11) and jpayne@68: pseudo-elements (CSS2 spec, section 5.12) are not supported. jpayne@68:
jpayne@68:The declarations in HTML mode are not limited; any graphical attribute jpayne@68: supported by the browsers can be used. jpayne@68:
jpayne@68:The declarations in text mode are limited to the following properties. jpayne@68: Other properties will be silently ignored. jpayne@68:
jpayne@68:color (CSS2 spec, section 14.1)background-color (CSS2 spec, section 14.2.1)These properties are supported. Colors will be adjusted to match the jpayne@68: terminal's capabilities. Note that many terminals support only 8 colors. jpayne@68:
jpayne@68:font-weight (CSS2 spec, section 15.2.3)This property is supported, but most terminals can only render two
jpayne@68: different weights: normal and bold. Values >= 600 are
jpayne@68: rendered as bold.
jpayne@68:
font-style (CSS2 spec, section 15.2.3)This property is supported. The values italic and oblique
jpayne@68: are rendered the same way.
jpayne@68:
text-decoration (CSS2 spec, section 16.3.1)This property is supported, limited to the values none and
jpayne@68: underline.
jpayne@68:
If you want to understand why the style rules in a style file produce jpayne@68: the output that you see, you can do so in three steps: jpayne@68:
jpayne@68:--color=html,
jpayne@68: redirecting the output to a file.
jpayne@68: This technique allows you, in particular, to see which CSS declarations jpayne@68: override which other CSS declarations from other CSS rules. jpayne@68:
jpayne@68: jpayne@68:| [ << ] | jpayne@68:[ >> ] | jpayne@68:jpayne@68: | jpayne@68: | jpayne@68: | jpayne@68: | jpayne@68: | [Top] | jpayne@68:[Contents] | jpayne@68:[Index] | jpayne@68:[ ? ] | jpayne@68:
jpayne@68:
jpayne@68: This document was generated by Bruno Haible on February, 21 2024 using texi2html 1.78a.
jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68: