Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/libtextstyle/libtextstyle_2.html @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
2 <html>
3 <!-- Created on February, 21 2024 by texi2html 1.78a -->
4 <!--
5 Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
6 Karl Berry <karl@freefriends.org>
7 Olaf Bachmann <obachman@mathematik.uni-kl.de>
8 and many others.
9 Maintained by: Many creative people.
10 Send bugs and suggestions to <texi2html-bug@nongnu.org>
11
12 -->
13 <head>
14 <title>GNU libtextstyle: 2. The end user's perspective</title>
15
16 <meta name="description" content="GNU libtextstyle: 2. The end user's perspective">
17 <meta name="keywords" content="GNU libtextstyle: 2. The end user's perspective">
18 <meta name="resource-type" content="document">
19 <meta name="distribution" content="global">
20 <meta name="Generator" content="texi2html 1.78a">
21 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
22 <style type="text/css">
23 <!--
24 a.summary-letter {text-decoration: none}
25 pre.display {font-family: serif}
26 pre.format {font-family: serif}
27 pre.menu-comment {font-family: serif}
28 pre.menu-preformatted {font-family: serif}
29 pre.smalldisplay {font-family: serif; font-size: smaller}
30 pre.smallexample {font-size: smaller}
31 pre.smallformat {font-family: serif; font-size: smaller}
32 pre.smalllisp {font-size: smaller}
33 span.roman {font-family:serif; font-weight:normal;}
34 span.sansserif {font-family:sans-serif; font-weight:normal;}
35 ul.toc {list-style: none}
36 -->
37 </style>
38
39
40 </head>
41
42 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
43
44 <table cellpadding="1" cellspacing="1" border="0">
45 <tr><td valign="middle" align="left">[<a href="libtextstyle_1.html#SEC1" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
46 <td valign="middle" align="left">[<a href="libtextstyle_3.html#SEC15" title="Next chapter"> &gt;&gt; </a>]</td>
47 <td valign="middle" align="left"> &nbsp; </td>
48 <td valign="middle" align="left"> &nbsp; </td>
49 <td valign="middle" align="left"> &nbsp; </td>
50 <td valign="middle" align="left"> &nbsp; </td>
51 <td valign="middle" align="left"> &nbsp; </td>
52 <td valign="middle" align="left">[<a href="libtextstyle_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
53 <td valign="middle" align="left">[<a href="libtextstyle_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
54 <td valign="middle" align="left">[<a href="libtextstyle_5.html#SEC46" title="Index">Index</a>]</td>
55 <td valign="middle" align="left">[<a href="libtextstyle_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
56 </tr></table>
57
58 <hr size="2">
59 <a name="The-user_0027s-view"></a>
60 <a name="SEC4"></a>
61 <h1 class="chapter"> <a href="libtextstyle_toc.html#TOC4">2. The end user's perspective</a> </h1>
62
63 <p>Styled output can viewed fine in a console or terminal emulator window.
64 </p>
65 <p>The stylable program will typically have the following options:
66 </p><dl compact="compact">
67 <dt> <code>--color</code></dt>
68 <dd><p>Use colors and other text attributes always.
69 </p></dd>
70 <dt> <code>--color=<var>when</var></code></dt>
71 <dd><p>Use colors and other text attributes if <var>when</var>. <var>when</var> may be
72 <code>always</code>, <code>never</code>, <code>auto</code>, or <code>html</code>.
73 </p></dd>
74 <dt> <code>--style=<var>style-file</var></code></dt>
75 <dd><p>Specify the CSS style rule file for <code>--color</code>.
76 </p></dd>
77 </dl>
78
79 <p>For more details, see the sections <a href="#SEC11">The <code>--color</code> option</a> and
80 <a href="#SEC12">The <code>--style</code> option</a> below.
81 </p>
82 <p>If the output does not fit on a screen, you can use &lsquo;<samp>less -R</samp>&rsquo; to
83 scroll around in the styled output. For example:
84 </p><table><tr><td>&nbsp;</td><td><pre class="smallexample"><var>program</var> --color <var>arguments</var> | less -R
85 </pre></td></tr></table>
86
87
88
89 <a name="The-TERM-variable"></a>
90 <a name="SEC5"></a>
91 <h2 class="section"> <a href="libtextstyle_toc.html#TOC5">2.1 The environment variable <code>TERM</code></a> </h2>
92
93 <p>The environment variable <code>TERM</code> contains a identifier for the text
94 window's capabilities. You can get a detailed list of these cababilities
95 by using the &lsquo;<samp>infocmp</samp>&rsquo; command (for example: <code>infocmp -L1 xterm</code>),
96 using &lsquo;<samp>man 5 terminfo</samp>&rsquo; as a reference.
97 </p>
98 <p>When producing text with embedded color directives, a
99 <code>libtextstyle</code>-enabled program looks at the <code>TERM</code> variable.
100 Text windows today typically support at least 8 colors. Often, however,
101 the text window supports 16 or more colors, even though the <code>TERM</code>
102 variable is set to a identifier denoting only 8 supported colors. It
103 can be worth setting the <code>TERM</code> variable to a different value in
104 these cases.
105 </p>
106 <p>After setting <code>TERM</code>, you can verify how well it works by invoking
107 &lsquo;<samp><var>program</var> --color=test</samp>&rsquo;, where <code><var>program</var></code> is any
108 <code>libtextstyle</code>-enabled program, and seeing whether the output looks
109 like a reasonable color map.
110 </p>
111
112
113 <a name="Terminal-emulators"></a>
114 <a name="SEC6"></a>
115 <h3 class="subsection"> <a href="libtextstyle_toc.html#TOC6">2.1.1 Terminal emulator programs</a> </h3>
116
117 <p>The following terminal emulator programs support 256 colors and set
118 <code>TERM=xterm-256color</code> accordingly:
119 </p>
120 <ul>
121 <li>
122 In GNOME: <code>gnome-terminal</code>, <code>tilda</code>.
123 </li><li>
124 <code>rxvt-unicode</code> (sets <code>TERM=rxvt-unicode-256color</code>).
125 </li><li>
126 <code>st</code> (sets <code>TERM=st-256color</code>).
127 </li><li>
128 <code>QTerminal</code>.
129 </li><li>
130 On macOS: <code>Terminal</code>, <code>iTerm2</code>.
131 </li></ul>
132
133 <p>The following terminal emulator programs support 256 colors. You only
134 need to set <code>TERM=xterm-256color</code> or similar; the programs by default
135 set <code>TERM</code> to a value that supports only 8 colors.
136 </p>
137 <ul>
138 <li>
139 <code>xterm</code> is in many cases built with support for 256 colors. But it
140 sets <code>TERM=xterm</code>. You need to set <code>TERM=xterm-256color</code>.
141 </li><li>
142 In GNOME: <code>guake</code> (sets <code>TERM=xterm</code>). You need to set
143 <code>TERM=xterm-256color</code>.
144 </li><li>
145 In KDE: <code>konsole</code> (sets <code>TERM=xterm</code>). You need to set
146 <code>TERM=xterm-256color</code> or <code>TERM=konsole-256color</code>.
147 </li><li>
148 In KDE: <code>yakuake</code> (sets <code>TERM=xterm</code>). You need to set
149 <code>TERM=xterm-256color</code>.
150 </li><li>
151 In Enlightenment: <code>Eterm</code> (sets <code>TERM=Eterm</code>). You need to set
152 <code>TERM=Eterm-256color</code>.
153 </li><li>
154 <code>mlterm</code> (sets <code>TERM=mlterm</code>). You need to set
155 <code>TERM=mlterm-256color</code>.
156 </li><li>
157 On Windows: <code>PuTTY</code> (sets <code>TERM=xterm</code>). You need to set
158 <code>TERM=xterm-256color</code> or <code>TERM=putty-256color</code>.
159 </li><li>
160 On Windows: <code>TeraTerm</code> (sets <code>TERM=xterm</code>). You need to set
161 <code>TERM=xterm-256color</code>.
162 </li></ul>
163
164 <p>A couple of terminal emulator programs support even the entire RGB color
165 space (16 million colors). To get this to work, at this date (2019), you
166 need three things:
167 </p><ul>
168 <li>
169 The <code>ncurses</code> library version 6.1 or newer must be installed.
170 </li><li>
171 You need a recent version of the respective terminal emulator program.
172 See <a href="https://gist.github.com/XVilka/8346728">https://gist.github.com/XVilka/8346728</a> for the most recent
173 developments in this area.
174 </li><li>
175 You need to set the <code>TERM</code> environment variable to the corresponding
176 value:
177 <code>TERM=xterm-direct</code> instead of
178 <code>TERM=xterm</code> or <code>TERM=xterm-256color</code>,
179 <code>TERM=konsole-direct</code> in <code>konsole</code>,
180 <code>TERM=st-direct</code> in <code>st</code>,
181 <code>TERM=mlterm-direct</code> in <code>mlterm</code>,
182 or <code>TERM=iterm2-direct</code> in <code>iTerm2</code> on macOS.
183 </li></ul>
184
185
186 <a name="Consoles"></a>
187 <a name="SEC7"></a>
188 <h3 class="subsection"> <a href="libtextstyle_toc.html#TOC7">2.1.2 Consoles</a> </h3>
189
190 <p>On OpenBSD 6 consoles, <code>TERM=xterm</code> produces better results than the
191 default <code>TERM=vt220</code>.
192 </p>
193 <p>On NetBSD 8 consoles, <code>TERM=netbsd6</code> produces better results than the
194 default <code>TERM=vt100</code>.
195 </p>
196 <p>On Windows consoles, no <code>TERM</code> setting is needed.
197 </p>
198
199 <a name="The-NO_005fCOLOR-variable"></a>
200 <a name="SEC8"></a>
201 <h2 class="section"> <a href="libtextstyle_toc.html#TOC8">2.2 The environment variable <code>NO_COLOR</code></a> </h2>
202
203 <p>The environment variable <code>NO_COLOR</code> can be used to suppress styling
204 in the textual output. When this environment variable is set (to any value),
205 <code>libtextstyle</code>-enabled programs will not emit colors and other text
206 styling.
207 </p>
208 <p>This environment variable can be overridden by passing the command-line option
209 &lsquo;<samp>--color=always</samp>&rsquo; (see <a href="#SEC11">The <code>--color</code> option</a>).
210 </p>
211
212 <a name="The-NO_005fTERM_005fHYPERLINKS-variable"></a>
213 <a name="SEC9"></a>
214 <h2 class="section"> <a href="libtextstyle_toc.html#TOC9">2.3 The environment variable <code>NO_TERM_HYPERLINKS</code></a> </h2>
215
216 <p>The environment variable <code>NO_TERM_HYPERLINKS</code> can be used to suppress
217 hyperlinks in the textual output. When this environment variable is set
218 (to any value), <code>libtextstyle</code>-enabled programs will not emit
219 hyperlinks. This may be useful for terminal emulators which produce
220 garbage output when they receive the escape sequence for a hyperlink.
221 Currently (as of 2019), this affects some versions of
222 <code>konsole</code>, <code>emacs</code>, <code>lxterminal</code>, <code>guake</code>, <code>yakuake</code>, <code>rxvt</code>. </p>
223
224 <a name="Emacs"></a>
225 <a name="SEC10"></a>
226 <h2 class="section"> <a href="libtextstyle_toc.html#TOC10">2.4 Emacs as a terminal emulator</a> </h2>
227
228 <p>Emacs has several terminal emulators: <code>M-x shell</code> and
229 <code>M-x term</code>. <code>M-x term</code> has good support for styling, whereas
230 in <code>M-x shell</code> most of the styling gets lost.
231 </p>
232
233 <a name="The-_002d_002dcolor-option"></a>
234 <a name="SEC11"></a>
235 <h2 class="section"> <a href="libtextstyle_toc.html#TOC11">2.5 The <code>--color</code> option</a> </h2>
236
237 <p>The &lsquo;<samp>--color=<var>when</var></samp>&rsquo; option specifies under which conditions
238 styled (colorized) output should be generated. The <var>when</var> part can
239 be one of the following:
240 </p>
241 <dl compact="compact">
242 <dt> <code>always</code></dt>
243 <dt> <code>yes</code></dt>
244 <dd><p>The output will be colorized.
245 </p>
246 </dd>
247 <dt> <code>never</code></dt>
248 <dt> <code>no</code></dt>
249 <dd><p>The output will not be colorized.
250 </p>
251 </dd>
252 <dt> <code>auto</code></dt>
253 <dt> <code>tty</code></dt>
254 <dd><p>The output will be colorized if the output device is a tty, i.e. when
255 the output goes directly to a text screen or terminal emulator window.
256 </p>
257 </dd>
258 <dt> <code>html</code></dt>
259 <dd><p>The output will be colorized and be in HTML format. This value is only
260 supported by some programs.
261 </p>
262 </dd>
263 <dt> <code>test</code></dt>
264 <dd><p>This is a special value, understood only by some programs. It is
265 explained in the section (<a href="#SEC5">The environment variable <code>TERM</code></a>) above.
266 </p></dd>
267 </dl>
268
269 <p>&lsquo;<samp>--color</samp>&rsquo; is equivalent to &lsquo;<samp>--color=yes</samp>&rsquo;. The default is
270 &lsquo;<samp>--color=auto</samp>&rsquo;.
271 </p>
272 <p>Thus, a command that invokes a <code>libtextstyle</code>-enabled program will
273 produce colorized output when called by itself in a command window.
274 Whereas in a pipe, such as &lsquo;<samp><var>program</var> <var>arguments</var> | less -R</samp>&rsquo;,
275 it will not produce colorized output. To get colorized output in this
276 situation nevertheless, use the command
277 &lsquo;<samp><var>program</var> --color <var>arguments</var> | less -R</samp>&rsquo;.
278 </p>
279 <p>The &lsquo;<samp>--color=html</samp>&rsquo; option will produce output that can be viewed in
280 a browser. This can be useful, for example, for Indic languages,
281 because the renderic of Indic scripts in browsers is usually better than
282 in terminal emulators.
283 </p>
284 <p>Note that the output produced with the <code>--color</code> option is
285 <em>not</em> consumable by programs that expect the raw text. It contains
286 additional terminal-specific escape sequences or HTML tags. For example,
287 an XML parser will give a syntax error when confronted with a colored XML
288 output. Except for the &lsquo;<samp>--color=html</samp>&rsquo; case, you therefore normally
289 don't need to save output produced with the <code>--color</code> option in a
290 file.
291 </p>
292
293 <a name="The-_002d_002dstyle-option"></a>
294 <a name="SEC12"></a>
295 <h2 class="section"> <a href="libtextstyle_toc.html#TOC12">2.6 The <code>--style</code> option</a> </h2>
296
297 <p>The &lsquo;<samp>--style=<var>style_file</var></samp>&rsquo; option specifies the style file to
298 use when colorizing. It has an effect only when the <code>--color</code>
299 option is effective.
300 </p>
301 <p>If the <code>--style</code> option is not specified, the program may consider
302 the value of an environment variable. It is meant to point to the user's
303 preferred style for such output. The name of such an environment
304 variable, if supported, is documented in the documentation of the
305 <code>libtextstyle</code>-enabled program.
306 </p>
307 <p>You can also design your own styles. This is described in the next
308 section.
309 </p>
310
311
312 <a name="Style-rules"></a>
313 <a name="SEC13"></a>
314 <h3 class="subsection"> <a href="libtextstyle_toc.html#TOC13">2.6.1 Creating your own style files</a> </h3>
315
316 <p>The same style file can be used for styling a certain type of output, for
317 terminal output and for HTML output. It is written in CSS
318 (Cascading Style Sheet) syntax. See
319 <a href="https://www.w3.org/TR/css2/cover.html">https://www.w3.org/TR/css2/cover.html</a> for a formal definition of
320 CSS. Many HTML authoring tutorials also contain explanations of CSS.
321 </p>
322 <p>In the case of HTML output, the style file is embedded in the HTML output.
323 In the case of text output, the style file is interpreted by the
324 <code>libtextstyle</code>-enabled program.
325 </p>
326 <p>You should avoid <code>@import</code> statements, because
327 </p><ul class="toc">
328 <li>-
329 In the case of HTML output, the files referenced by the <code>@import</code>
330 statements would not be embedded in the HTML output. In fact, relative
331 file names would be interpreted relative to the resulting HTML file.
332 </li><li>-
333 In the case of text output, <code>@import</code>s are not supported, due to a
334 limitation in <code>libcroco</code>.
335 </li></ul>
336
337 <p>CSS rules are built up from selectors and declarations. The declarations
338 specify graphical properties; the selectors specify when they apply.
339 </p>
340 <p>GNU libtextstyle supports simple selectors based on &quot;CSS classes&quot;, see
341 the CSS2 spec, section 5.8.3. The set of CSS classes that are supported
342 by a <code>libtextstyle</code>-enabled program are documented in the
343 documentation of that program.
344 </p>
345 <p>These selectors can be combined to hierarchical selectors. For example,
346 assume a program supports the CSS classes <code>string</code> (that matches a
347 string) and <code>non-ascii</code> (that matches a word with non-ASCII
348 characters), you could write
349 </p>
350 <table><tr><td>&nbsp;</td><td><pre class="smallexample">.string .non-ascii { color: red; }
351 </pre></td></tr></table>
352
353 <p>to highlight only the non-ASCII words inside strings.
354 </p>
355 <p>In text mode, pseudo-classes (CSS2 spec, section 5.11) and
356 pseudo-elements (CSS2 spec, section 5.12) are not supported.
357 </p>
358 <p>The declarations in HTML mode are not limited; any graphical attribute
359 supported by the browsers can be used.
360 </p>
361 <p>The declarations in text mode are limited to the following properties.
362 Other properties will be silently ignored.
363 </p>
364 <dl compact="compact">
365 <dt> <code>color</code> (CSS2 spec, section 14.1)</dt>
366 <dt> <code>background-color</code> (CSS2 spec, section 14.2.1)</dt>
367 <dd><p>These properties are supported. Colors will be adjusted to match the
368 terminal's capabilities. Note that many terminals support only 8 colors.
369 </p>
370 </dd>
371 <dt> <code>font-weight</code> (CSS2 spec, section 15.2.3)</dt>
372 <dd><p>This property is supported, but most terminals can only render two
373 different weights: <code>normal</code> and <code>bold</code>. Values &gt;= 600 are
374 rendered as <code>bold</code>.
375 </p>
376 </dd>
377 <dt> <code>font-style</code> (CSS2 spec, section 15.2.3)</dt>
378 <dd><p>This property is supported. The values <code>italic</code> and <code>oblique</code>
379 are rendered the same way.
380 </p>
381 </dd>
382 <dt> <code>text-decoration</code> (CSS2 spec, section 16.3.1)</dt>
383 <dd><p>This property is supported, limited to the values <code>none</code> and
384 <code>underline</code>.
385 </p></dd>
386 </dl>
387
388
389 <a name="Debugging-style-files"></a>
390 <a name="SEC14"></a>
391 <h3 class="subsection"> <a href="libtextstyle_toc.html#TOC14">2.6.2 Debugging style files</a> </h3>
392
393 <p>If you want to understand why the style rules in a style file produce
394 the output that you see, you can do so in three steps:
395 </p>
396 <ol>
397 <li>
398 Run the program with the command-line option <code>--color=html</code>,
399 redirecting the output to a file.
400 </li><li>
401 Open the resulting HTML file in a browser.
402 </li><li>
403 Use the browser's built-in CSS debugging tool.
404 <ul>
405 <li>
406 In Firefox: From the pop-up menu, select &quot;Inspect Element&quot;.
407 Click somewhere in the DOM tree (&quot;Inspector&quot; tab) and look at the
408 CSS declarations in the &quot;Rules&quot; tab.
409 </li><li>
410 In Chromium: From the pop-up menu, select &quot;Inspect&quot;.
411 Click somewhere in the DOM tree (&quot;Elements&quot; tab) and look at the
412 CSS declarations in the &quot;Styles&quot; tab.
413 </li></ul>
414 </li></ol>
415
416 <p>This technique allows you, in particular, to see which CSS declarations
417 override which other CSS declarations from other CSS rules.
418 </p>
419
420 <table cellpadding="1" cellspacing="1" border="0">
421 <tr><td valign="middle" align="left">[<a href="#SEC4" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
422 <td valign="middle" align="left">[<a href="libtextstyle_3.html#SEC15" title="Next chapter"> &gt;&gt; </a>]</td>
423 <td valign="middle" align="left"> &nbsp; </td>
424 <td valign="middle" align="left"> &nbsp; </td>
425 <td valign="middle" align="left"> &nbsp; </td>
426 <td valign="middle" align="left"> &nbsp; </td>
427 <td valign="middle" align="left"> &nbsp; </td>
428 <td valign="middle" align="left">[<a href="libtextstyle_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
429 <td valign="middle" align="left">[<a href="libtextstyle_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
430 <td valign="middle" align="left">[<a href="libtextstyle_5.html#SEC46" title="Index">Index</a>]</td>
431 <td valign="middle" align="left">[<a href="libtextstyle_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
432 </tr></table>
433 <p>
434 <font size="-1">
435 This document was generated by <em>Bruno Haible</em> on <em>February, 21 2024</em> using <a href="https://www.nongnu.org/texi2html/"><em>texi2html 1.78a</em></a>.
436 </font>
437 <br>
438
439 </p>
440 </body>
441 </html>