Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/libtextstyle/libtextstyle_3.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: 3. The programmer's perspective</title>
15
16 <meta name="description" content="GNU libtextstyle: 3. The programmer's perspective">
17 <meta name="keywords" content="GNU libtextstyle: 3. The programmer'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_2.html#SEC4" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
46 <td valign="middle" align="left">[<a href="libtextstyle_4.html#SEC38" 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-programmer_0027s-view"></a>
60 <a name="SEC15"></a>
61 <h1 class="chapter"> <a href="libtextstyle_toc.html#TOC15">3. The programmer's perspective</a> </h1>
62
63 <p>As a programmer, enabling styling consists of the following tasks:
64 </p><ol>
65 <li>
66 Define the command-line options and environment variable that the user
67 can use to control the styling.
68 </li><li>
69 Define the CSS classes that the user can use in the CSS file. Each CSS
70 class corresponds to a text role; each CSS class can be given a different
71 styling by the user.
72 </li><li>
73 Change the output routines so that they take an &lsquo;<samp>ostream_t</samp>&rsquo; object
74 as argument instead of a &lsquo;<samp>FILE *</samp>&rsquo;.
75 </li><li>
76 Insert paired invocations to <code>styled_ostream_begin_css_class</code>,
77 <code>styled_ostream_end_css_class</code> around each run of text with a
78 specific text role.
79 </li><li>
80 Link with <code>libtextstyle</code>. If your package is using GNU autoconf,
81 you can use the <code>libtextstyle.m4</code> macro from Gnulib.
82 </li><li>
83 Prepare a default style file.
84 </li><li>
85 Update the documentation of your package.
86 </li></ol>
87
88 <p>The following sections go into more detail.
89 </p>
90
91
92 <a name="Basic-use"></a>
93 <a name="SEC16"></a>
94 <h2 class="section"> <a href="libtextstyle_toc.html#TOC16">3.1 Basic use of libtextstyle</a> </h2>
95
96 <p>Source code that makes use of GNU libtextstyle needs an include statement:
97 </p>
98 <table><tr><td>&nbsp;</td><td><pre class="smallexample">#include &lt;textstyle.h&gt;
99 </pre></td></tr></table>
100
101 <p>Basic use of GNU libtextstyle consists of statements like these:
102 </p>
103 <table><tr><td>&nbsp;</td><td><pre class="smallexample"> styled_ostream_t stream =
104 styled_ostream_create (STDOUT_FILENO, &quot;(stdout)&quot;, TTYCTL_AUTO,
105 style_file_name);
106 ...
107 styled_ostream_begin_use_class (stream, css_class);
108 ...
109 ostream_write_str (stream, string);
110 ...
111 styled_ostream_end_use_class (stream, css_class);
112 ...
113 styled_ostream_free (stream);
114 </pre></td></tr></table>
115
116 <p>Before this snippet, your code needs to determine the name of the style
117 file to use (<code>style_file_name</code>). If no styling is desired &ndash; the
118 precise condition depends on the value of <code>color_mode</code> but also on
119 your application logic &ndash;, you should set <code>style_file_name</code> to
120 <code>NULL</code>.
121 </p>
122 <p>An object of type <code>styled_ostream_t</code> is allocated. The function
123 <code>styled_ostream_create</code> allocates it; the function
124 <code>styled_ostream_free</code> deallocates it.
125 </p>
126 <p>Such <code>styled_ostream_t</code> supports output operations
127 (<code>ostream_write_str</code>), interleaved with adding and removing CSS
128 classes. The CSS class in effect when an output operation is performed
129 determines, through the style file, the text attributes associated with
130 that piece of text.
131 </p>
132
133
134 <a name="Hyperlinks"></a>
135 <a name="SEC17"></a>
136 <h3 class="subsection"> <a href="libtextstyle_toc.html#TOC17">3.1.1 Hyperlinks</a> </h3>
137
138 <p>Text output may contain hyperlinks. These hyperlinks are encoded through
139 an escape sequence, specified at
140 <a href="https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda">Hyperlinks in terminal emulators</a>. Currently (as of 2019), they are
141 displayed only in <code>gnome-terminal</code> version 3.26 or above. More
142 terminal emulators will support hyperlinks in the future. Terminal
143 emulators which don't support hyperlinks ignore it, except for a few
144 terminal emulators, for which users may need to disable the hyperlinks
145 (see <a href="libtextstyle_2.html#SEC9">The environment variable <code>NO_TERM_HYPERLINKS</code></a>) if the heuristic built into
146 <code>libtextstyle</code> does not already disable them.
147 </p>
148 <p>To emit a hyperlink, use code like this:
149 </p>
150 <table><tr><td>&nbsp;</td><td><pre class="smallexample"> styled_ostream_t stream = ...
151 ...
152 /* Start a hyperlink. */
153 styled_ostream_set_hyperlink (stream, url, NULL);
154 ...
155 /* Emit the anchor text. This can be styled text. */
156 ostream_write_str (stream, &quot;Click here!&quot;);
157 ...
158 /* End the current hyperlink. */
159 styled_ostream_set_hyperlink (stream, NULL, NULL);
160 </pre></td></tr></table>
161
162 <p>The anchor text can be styled. But the hyperlinks themselves cannot be
163 styled; they behave as implemented by the terminal emulator.
164 </p>
165
166 <a name="Include-files"></a>
167 <a name="SEC18"></a>
168 <h2 class="section"> <a href="libtextstyle_toc.html#TOC18">3.2 Include files</a> </h2>
169
170 <p>The include file <code>&lt;textstyle.h&gt;</code> declares all facilities defined by
171 the library.
172 </p>
173
174 <a name="Link-options"></a>
175 <a name="SEC19"></a>
176 <h2 class="section"> <a href="libtextstyle_toc.html#TOC19">3.3 Link options</a> </h2>
177
178 <p>The library to link with is called <code>libtextstyle</code>, with a
179 system-dependent suffix. You link with it though link options of the
180 form <code>-ltextstyle</code> for a library installed in system locations, or
181 <code>-L<var>libdir</var> -ltextstyle</code> for a static library installed in other
182 locations, or <code>-L<var>libdir</var> -ltextstyle -Wl,-rpath,<var>libdir</var></code>
183 for a shared library installed in other locations (assuming a GCC
184 compatible compiler and linker and no <code>libtool</code>), or
185 <code>-L<var>libdir</var> -ltextstyle -R<var>libdir</var></code> for a shared library
186 installed in other locations (with <code>libtool</code>). Additionally, the
187 link options may need to include the dependencies: <code>-lm</code>, and
188 <code>-lncurses</code> or (on NetBSD) <code>-ltermcap</code> or (on AIX)
189 <code>-lxcurses</code> or (on HP-UX) <code>-lcurses</code>, and on some systems also
190 <code>-liconv</code>.
191 </p>
192 <p>It is a bit complicated to determine the right link options in a portable
193 way. Therefore an Autoconf macro is provided in the file
194 <code>libtextstyle.m4</code> in Gnulib, that makes this task easier. Assuming
195 the build system of your package is based on GNU Autoconf, you invoke it
196 through <code>gl_LIBTEXTSTYLE</code>. It searches for an installed
197 <code>libtextstyle</code>. If found, it sets and AC_SUBSTs
198 <code>HAVE_LIBTEXTSTYLE=yes</code> and the <code>LIBTEXTSTYLE</code> and
199 <code>LTLIBTEXTSTYLE</code> variables, and augments the <code>CPPFLAGS</code>
200 variable, and #defines <code>HAVE_LIBTEXTSTYLE</code> to 1. Otherwise, it sets
201 and AC_SUBSTs <code>HAVE_LIBTEXTSTYLE=no</code> and <code>LIBTEXTSTYLE</code> and
202 <code>LTLIBTEXTSTYLE</code> to empty. In link commands that use <code>libtool</code>,
203 use <code>LTLIBTEXTSTYLE</code>; in link commands that don't use <code>libtool</code>,
204 use <code>LIBTEXTSTYLE</code>.
205 </p>
206 <p>If you use GNU Automake, the proper place to use the link options is
207 <code><var>program</var>_LDADD</code> for programs and <code><var>library</var>_LIBADD</code>
208 for libraries.
209 </p>
210
211 <a name="Command_002dline-options"></a>
212 <a name="SEC20"></a>
213 <h2 class="section"> <a href="libtextstyle_toc.html#TOC20">3.4 Command-line options</a> </h2>
214
215 <p>While you are free to provide any command-line option to enable the
216 styling of the output, it is good if different GNU programs use the same
217 command-line options for this purpose. These options are described in
218 the sections <a href="libtextstyle_2.html#SEC11">The <code>--color</code> option</a> and <a href="libtextstyle_2.html#SEC12">The <code>--style</code> option</a>. To
219 achieve this, use the following API (declared in <code>&lt;textstyle.h&gt;</code>):
220 </p>
221 <dl>
222 <dt><u>Variable:</u> bool <b>color_test_mode</b>
223 <a name="IDX1"></a>
224 </dt>
225 <dd><p>True if a <code>--color</code> option with value <code>test</code> has been seen.
226 </p></dd></dl>
227
228 <dl>
229 <dt><u>Variable:</u> enum&nbsp;color_option <b>color_mode</b>
230 <a name="IDX2"></a>
231 </dt>
232 <dd><p>Stores the value of the <code>--color</code> option.
233 </p></dd></dl>
234
235 <dl>
236 <dt><u>Variable:</u> const&nbsp;char&nbsp;* <b>style_file_name</b>
237 <a name="IDX3"></a>
238 </dt>
239 <dd><p>Stores the value of the <code>--style</code> option.
240 </p></dd></dl>
241
242 <p>Note: These variables, like any variables exported from shared libraries,
243 can only be used in executable code. You <em>cannot</em> portably use
244 their address in initializers of global or static variables. This is a
245 restriction that is imposed by the Windows, Cygwin, and Android platforms.
246 </p>
247 <dl>
248 <dt><u>Function:</u> bool <b>handle_color_option</b><i> (const&nbsp;char&nbsp;*<var>option</var>)</i>
249 <a name="IDX4"></a>
250 </dt>
251 <dd><p>You invoke this function when, during argument parsing, you have
252 encountered a <code>--color</code> or <code>--color=...</code> option. The return
253 value is an error indicator: <code>true</code> means an invalid option.
254 </p></dd></dl>
255
256 <dl>
257 <dt><u>Function:</u> void <b>handle_style_option</b><i> (const&nbsp;char&nbsp;*<var>option</var>)</i>
258 <a name="IDX5"></a>
259 </dt>
260 <dd><p>You invoke this function when, during argument parsing, you have
261 encountered a <code>--style</code> or <code>--style=...</code> option.
262 </p></dd></dl>
263
264 <dl>
265 <dt><u>Function:</u> void <b>print_color_test</b><i> (void)</i>
266 <a name="IDX6"></a>
267 </dt>
268 <dd><p>Prints a color test page. You invoke this function after argument
269 parsing, when the <code>color_test_mode</code> variable is true.
270 </p></dd></dl>
271
272 <dl>
273 <dt><u>Function:</u> void <b>style_file_prepare</b><i> (const&nbsp;char&nbsp;*<var>style_file_envvar</var>, const&nbsp;char&nbsp;*<var>stylesdir_envvar</var>, const&nbsp;char&nbsp;*<var>stylesdir_after_install</var>, const&nbsp;char&nbsp;*<var>default_style_file</var>)</i>
274 <a name="IDX7"></a>
275 </dt>
276 <dd><p>Assigns a default value to <code>style_file_name</code> if necessary. You
277 invoke this function after argument parsing, when <code>color_test_mode</code>
278 is false.
279 </p>
280 <p><code><var>style_file_envvar</var></code> is an environment variable that, when set
281 to a non-empty value, specifies the style file to use. This environment
282 variable is meant to be set by the user.
283 </p>
284 <p><code><var>stylesdir_envvar</var></code> is an environment variable that, when set
285 to a non-empty value, specifies the directory with the style files, or
286 <code>NULL</code>. This is necessary for running the testsuite before
287 &lsquo;<samp>make install</samp>&rsquo;.
288 </p>
289 <p><code><var>stylesdir_after_install</var></code> is the directory with the style
290 files after &lsquo;<samp>make install</samp>&rsquo;.
291 </p>
292 <p><code><var>default_style_file</var></code> is the file name of the default style
293 file, relative to <var>stylesdir</var>.
294 </p></dd></dl>
295
296
297 <a name="The-output-stream-hierarchy"></a>
298 <a name="SEC21"></a>
299 <h2 class="section"> <a href="libtextstyle_toc.html#TOC21">3.5 The output stream hierarchy</a> </h2>
300
301 <p>There are various classes of output streams, some of them with styling
302 support. These &ldquo;classes&rdquo; are defined in an object-oriented programming
303 style that resembles C++ or Java, but are actually implemented in C with
304 a little bit of object orientation syntax. These definitions are
305 preprocessed down to C. As a consequence, GNU libtextstyle is a C
306 library and does not need to link with the C++ standard library.
307 </p>
308 <p>All these classes are declared in <code>&lt;textstyle.h&gt;</code>.
309 </p>
310 <p>The base output stream type is &lsquo;<samp>ostream_t</samp>&rsquo;. It is a pointer type to
311 a (hidden) implementation type. Similarly for the subclasses.
312 </p>
313 <p>When we say that &lsquo;<samp>some_ostream_t</samp>&rsquo; is a subclass of &lsquo;<samp>ostream_t</samp>&rsquo;,
314 what we mean is:
315 </p><ul>
316 <li>
317 Every &lsquo;<samp>some_ostream_t</samp>&rsquo; object can be converted to an
318 &lsquo;<samp>ostream_t</samp>&rsquo;, by virtue of a simple assignment. No cast is needed.
319 </li><li>
320 The opposite conversion, from &lsquo;<samp>ostream_t</samp>&rsquo; to &lsquo;<samp>some_ostream_t</samp>&rsquo;,
321 can also be performed, provided that the object is actually an instance
322 of &lsquo;<samp>some_ostream_t</samp>&rsquo;. You can test whether an object is an instance
323 of &lsquo;<samp>some_ostream_t</samp>&rsquo; by invoking the method
324 &lsquo;<samp>bool is_instance_of_some_ostream (ostream_t stream)</samp>&rsquo;.
325 <a name="IDX8"></a>
326 <a name="IDX9"></a>
327 <a name="IDX10"></a>
328 <a name="IDX11"></a>
329 <a name="IDX12"></a>
330 <a name="IDX13"></a>
331 <a name="IDX14"></a>
332 <a name="IDX15"></a>
333 <a name="IDX16"></a>
334 <a name="IDX17"></a>
335 </li><li>
336 Every method &lsquo;<samp>ostream_<var>foobar</var></samp>&rsquo; exists also as a method
337 &lsquo;<samp>some_ostream_<var>foobar</var></samp>&rsquo; with compatible argument types and a
338 compatible return type.
339 </li></ul>
340
341
342
343 <a name="The-ostream-class"></a>
344 <a name="SEC22"></a>
345 <h3 class="subsection"> <a href="libtextstyle_toc.html#TOC22">3.5.1 The abstract <code>ostream</code> class</a> </h3>
346
347 <p>The base output stream type is &lsquo;<samp>ostream_t</samp>&rsquo;.
348 </p>
349 <p>It has the following methods:
350 </p>
351 <dl>
352 <dt><u>Function:</u> void <b>ostream_write_mem</b><i> (ostream_t&nbsp;<var>stream</var>, const&nbsp;void&nbsp;*<var>data</var>, size_t&nbsp;<var>len</var>)</i>
353 <a name="IDX18"></a>
354 </dt>
355 <dd><p>Writes a sequence of bytes to a stream.
356 </p></dd></dl>
357
358 <dl>
359 <dt><u>Function:</u> void <b>ostream_write_str</b><i> (ostream_t&nbsp;<var>stream</var>, const&nbsp;char&nbsp;*<var>string</var>)</i>
360 <a name="IDX19"></a>
361 </dt>
362 <dd><p>Writes a string's contents to a stream.
363 </p></dd></dl>
364
365 <dl>
366 <dt><u>Function:</u> ptrdiff_t <b>ostream_printf</b><i> (ostream_t&nbsp;<var>stream</var>, const&nbsp;char&nbsp;*<var>format</var>, ...)</i>
367 <a name="IDX20"></a>
368 </dt>
369 <dt><u>Function:</u> ptrdiff_t <b>ostream_vprintf</b><i> (ostream_t&nbsp;<var>stream</var>, const&nbsp;char&nbsp;*<var>format</var>, va_list args)</i>
370 <a name="IDX21"></a>
371 </dt>
372 <dd><p>Writes formatted output to a stream.
373 </p>
374 <p>These functions return the size of formatted output, or a negative value
375 in case of an error.
376 </p></dd></dl>
377
378 <dl>
379 <dt><u>Function:</u> void <b>ostream_flush</b><i> (ostream_t&nbsp;<var>stream</var>, ostream_flush_scope_t&nbsp;<var>scope</var>)</i>
380 <a name="IDX22"></a>
381 </dt>
382 <dd><p>Brings buffered data to its destination.
383 </p></dd></dl>
384
385 <dl>
386 <dt><u>Function:</u> void <b>ostream_free</b><i> (ostream_t&nbsp;<var>stream</var>)</i>
387 <a name="IDX23"></a>
388 </dt>
389 <dd><p>Closes and frees a stream.
390 </p></dd></dl>
391
392
393 <a name="The-styled_005fostream-class"></a>
394 <a name="SEC23"></a>
395 <h3 class="subsection"> <a href="libtextstyle_toc.html#TOC23">3.5.2 The abstract <code>styled_ostream</code> class</a> </h3>
396
397 <p>The type for a styled output stream is &lsquo;<samp>styled_ostream_t</samp>&rsquo;. It is a
398 subclass of &lsquo;<samp>ostream_t</samp>&rsquo; that adds the following methods:
399 </p>
400 <dl>
401 <dt><u>Function:</u> void <b>styled_ostream_begin_use_class</b><i> (styled_ostream_t&nbsp;<var>stream</var>, const&nbsp;char&nbsp;*<var>classname</var>)</i>
402 <a name="IDX24"></a>
403 </dt>
404 <dd><p>Starts a run of text belonging to <code><var>classname</var></code>. The
405 <code><var>classname</var></code> is the name of a CSS class. It can be chosen
406 arbitrarily and customized through the CSS file.
407 </p></dd></dl>
408
409 <dl>
410 <dt><u>Function:</u> void <b>styled_ostream_end_use_class</b><i> (styled_ostream_t&nbsp;<var>stream</var>, const&nbsp;char&nbsp;*<var>classname</var>)</i>
411 <a name="IDX25"></a>
412 </dt>
413 <dd><p>Ends a run of text belonging to <code><var>classname</var></code>. The
414 <code>styled_ostream_begin_use_class</code> /
415 <code>styled_ostream_end_use_class</code> calls must match properly.
416 </p></dd></dl>
417
418 <dl>
419 <dt><u>Function:</u> const&nbsp;char&nbsp;* <b>styled_ostream_get_hyperlink_ref</b><i> (styled_ostream_t&nbsp;<var>stream</var>)</i>
420 <a name="IDX26"></a>
421 </dt>
422 <dd><p>Returns the referred URL of the currently set hyperlink, or <code>NULL</code>
423 if no hyperlink attribute is currently set.
424 </p>
425 <p>Note: The returned string is only valid up to the next invocation of
426 <code>styled_ostream_set_hyperlink</code>.
427 </p></dd></dl>
428
429 <dl>
430 <dt><u>Function:</u> const&nbsp;char&nbsp;* <b>styled_ostream_get_hyperlink_id</b><i> (styled_ostream_t&nbsp;<var>stream</var>)</i>
431 <a name="IDX27"></a>
432 </dt>
433 <dd><p>Returns the id of the currently set hyperlink, or <code>NULL</code> if no
434 hyperlink attribute is currently set.
435 </p>
436 <p>Note: The returned string is only valid up to the next invocation of
437 <code>styled_ostream_set_hyperlink</code>.
438 </p></dd></dl>
439
440 <dl>
441 <dt><u>Function:</u> void <b>styled_ostream_set_hyperlink</b><i> (styled_ostream_t&nbsp;<var>stream</var>, const&nbsp;char&nbsp;*<var>ref</var>, const&nbsp;char&nbsp;*<var>id</var>)</i>
442 <a name="IDX28"></a>
443 </dt>
444 <dd><p>Sets or removes a hyperlink attribute.
445 </p>
446 <p>To set a hyperlink attribute, pass a non-<code>NULL</code> <var>ref</var>.
447 <var>ref</var> is an URL; it should be at most 2083 bytes long. Non-ASCII
448 characters should be URI-escaped (using the %nn syntax). <var>id</var> is
449 an optional identifier. On terminal output, multiple hyperlinks with
450 the same <var>id</var> will be highlighted together. If specified, <var>id</var>
451 should be at most 250 bytes long.
452 </p>
453 <p>To remove a hyperlink attribute, pass <code>NULL</code> for <var>ref</var> and <var>id</var>.
454 </p>
455 <p>Hyperlinks don't nest. That is, a hyperlink attribute is enabled only
456 up to the next invocation of <code>styled_ostream_set_hyperlink</code>.
457 </p></dd></dl>
458
459 <dl>
460 <dt><u>Function:</u> void <b>styled_ostream_flush_to_current_style</b><i> (styled_ostream_t&nbsp;<var>stream</var>)</i>
461 <a name="IDX29"></a>
462 </dt>
463 <dd><p>This function acts like <code>ostream_flush (<var>stream</var>, FLUSH_THIS_STREAM)</code>,
464 except that it leaves the destination with the current text style enabled,
465 instead of with the default text style.
466 </p>
467 <p>After calling this function, you can output strings without newlines(!) to the
468 underlying stream, and they will be rendered like strings passed to
469 <code>ostream_write_mem</code>, <code>ostream_write_str</code>, or <code>ostream_printf</code>.
470 </p></dd></dl>
471
472
473 <a name="ostream-subclasses-without-styling"></a>
474 <a name="SEC24"></a>
475 <h3 class="subsection"> <a href="libtextstyle_toc.html#TOC24">3.5.3 Concrete ostream subclasses without styling</a> </h3>
476
477
478
479 <a name="The-file_005fostream-class"></a>
480 <a name="SEC25"></a>
481 <h4 class="subsubsection"> <a href="libtextstyle_toc.html#TOC25">3.5.3.1 The <code>file_ostream</code> class</a> </h4>
482
483 <p>The <code>file_ostream</code> class supports output to an <code>&lt;stdio.h&gt;</code>
484 <code>FILE</code> stream. Its type is &lsquo;<samp>file_ostream_t</samp>&rsquo;. It is a subclass
485 of &lsquo;<samp>ostream_t</samp>&rsquo; that adds no methods.
486 </p>
487 <p>It can be instantiated through this function:
488 </p>
489 <dl>
490 <dt><u>Function:</u> file_ostream_t <b>file_ostream_create</b><i> (FILE&nbsp;*<var>fp</var>)</i>
491 <a name="IDX30"></a>
492 </dt>
493 <dd><p>Creates an output stream referring to <code><var>fp</var></code>.
494 </p>
495 <p>Note: The resulting stream must be closed before <code><var>fp</var></code> can be
496 closed.
497 </p></dd></dl>
498
499
500 <a name="The-fd_005fostream-class"></a>
501 <a name="SEC26"></a>
502 <h4 class="subsubsection"> <a href="libtextstyle_toc.html#TOC26">3.5.3.2 The <code>fd_ostream</code> class</a> </h4>
503
504 <p>The <code>file_ostream</code> class supports output to a file descriptor. Its
505 type is &lsquo;<samp>fd_ostream_t</samp>&rsquo;. It is a subclass of &lsquo;<samp>ostream_t</samp>&rsquo; that
506 adds no methods.
507 </p>
508 <p>It can be instantiated through this function:
509 </p>
510 <dl>
511 <dt><u>Function:</u> fd_ostream_t <b>fd_ostream_create</b><i> (int&nbsp;<var>fd</var>, const&nbsp;char&nbsp;*<var>filename</var>, bool&nbsp;<var>buffered</var>)</i>
512 <a name="IDX31"></a>
513 </dt>
514 <dd><p>Creates an output stream referring to the file descriptor <code><var>fd</var></code>.
515 </p>
516 <p><code><var>filename</var></code> is used only for error messages.
517 </p>
518 <p>Note: The resulting stream must be closed before <code><var>fd</var></code> can be
519 closed.
520 </p></dd></dl>
521
522
523 <a name="The-term_005fostream-class"></a>
524 <a name="SEC27"></a>
525 <h4 class="subsubsection"> <a href="libtextstyle_toc.html#TOC27">3.5.3.3 The <code>term_ostream</code> class</a> </h4>
526
527 <p>The <code>term_ostream</code> class supports output to a file descriptor that
528 is connected to a terminal emulator or console. Its type is
529 &lsquo;<samp>term_ostream_t</samp>&rsquo;. It is a subclass of &lsquo;<samp>ostream_t</samp>&rsquo;.
530 </p>
531 <p>It can be instantiated through this function:
532 </p>
533 <dl>
534 <dt><u>Function:</u> term_ostream_t <b>term_ostream_create</b><i> (int&nbsp;<var>fd</var>, const&nbsp;char&nbsp;*<var>filename</var>, ttyctl_t&nbsp;<var>tty_control</var>)</i>
535 <a name="IDX32"></a>
536 </dt>
537 <dd><p>Creates an output stream referring to the file descriptor <code><var>fd</var></code>.
538 </p>
539 <p><code><var>filename</var></code> is used only for error messages.
540 </p>
541 <p><code><var>tty_control</var></code> specifies the amount of control to take over the
542 underlying tty.
543 </p>
544 <p>The resulting stream will be line-buffered.
545 </p>
546 <p>Note: The resulting stream must be closed before <code><var>fd</var></code> can be
547 closed.
548 </p></dd></dl>
549
550 <p>The class adds the following methods:
551 </p>
552 <dl>
553 <dt><u>Function:</u> term_color_t <b>term_ostream_rgb_to_color</b><i> (term_ostream_t&nbsp;<var>stream</var>, int&nbsp;<var>red</var>, int&nbsp;<var>green</var>, int&nbsp;<var>blue</var>)</i>
554 <a name="IDX33"></a>
555 </dt>
556 <dd><p>Converts an RGB value
557 (<code><var>red</var></code>, <code><var>green</var></code>, <code><var>blue</var></code> in [0..255]) to
558 a color, valid for this stream only.
559 </p></dd></dl>
560
561 <dl>
562 <dt><u>Function:</u> term_color_t <b>term_ostream_get_color</b><i> (term_ostream_t&nbsp;<var>stream</var>)</i>
563 <a name="IDX34"></a>
564 </dt>
565 <dt><u>Function:</u> void <b>term_ostream_set_color</b><i> (term_ostream_t&nbsp;<var>stream</var>, term_color_t&nbsp;<var>color</var>)</i>
566 <a name="IDX35"></a>
567 </dt>
568 <dd><p>Gets/sets the text color.
569 </p></dd></dl>
570
571 <dl>
572 <dt><u>Function:</u> term_color_t <b>term_ostream_get_bgcolor</b><i> (term_ostream_t&nbsp;<var>stream</var>)</i>
573 <a name="IDX36"></a>
574 </dt>
575 <dt><u>Function:</u> void <b>term_ostream_set_bgcolor</b><i> (term_ostream_t&nbsp;<var>stream</var>, term_color_t&nbsp;<var>color</var>)</i>
576 <a name="IDX37"></a>
577 </dt>
578 <dd><p>Gets/sets the background color.
579 </p></dd></dl>
580
581 <dl>
582 <dt><u>Function:</u> term_weight_t <b>term_ostream_get_weight</b><i> (term_ostream_t&nbsp;<var>stream</var>)</i>
583 <a name="IDX38"></a>
584 </dt>
585 <dt><u>Function:</u> void <b>term_ostream_set_weight</b><i> (term_ostream_t&nbsp;<var>stream</var>, term_weight_t&nbsp;<var>weight</var>)</i>
586 <a name="IDX39"></a>
587 </dt>
588 <dd><p>Gets/sets the font weight.
589 </p></dd></dl>
590
591 <dl>
592 <dt><u>Function:</u> term_posture_t <b>term_ostream_get_posture</b><i> (term_ostream_t&nbsp;<var>stream</var>)</i>
593 <a name="IDX40"></a>
594 </dt>
595 <dt><u>Function:</u> void <b>term_ostream_set_posture</b><i> (term_ostream_t&nbsp;<var>stream</var>, term_posture_t&nbsp;<var>posture</var>)</i>
596 <a name="IDX41"></a>
597 </dt>
598 <dd><p>Gets/sets the font posture.
599 </p></dd></dl>
600
601 <dl>
602 <dt><u>Function:</u> term_underline_t <b>term_ostream_get_underline</b><i> (term_ostream_t&nbsp;<var>stream</var>)</i>
603 <a name="IDX42"></a>
604 </dt>
605 <dt><u>Function:</u> void <b>term_ostream_set_underline</b><i> (term_ostream_t&nbsp;<var>stream</var>, term_underline_t&nbsp;<var>underline</var>)</i>
606 <a name="IDX43"></a>
607 </dt>
608 <dd><p>Gets/sets the text underline decoration.
609 </p></dd></dl>
610
611 <dl>
612 <dt><u>Function:</u> const&nbsp;char&nbsp;* <b>term_ostream_get_hyperlink_ref</b><i> (term_ostream_t&nbsp;<var>stream</var>)</i>
613 <a name="IDX44"></a>
614 </dt>
615 <dd><p>Returns the referred URL of the currently set hyperlink, or <code>NULL</code>
616 if no hyperlink attribute is currently set.
617 </p>
618 <p>Note: The returned string is only valid up to the next invocation of
619 <code>term_ostream_set_hyperlink</code>.
620 </p></dd></dl>
621
622 <dl>
623 <dt><u>Function:</u> const&nbsp;char&nbsp;* <b>term_ostream_get_hyperlink_id</b><i> (term_ostream_t&nbsp;<var>stream</var>)</i>
624 <a name="IDX45"></a>
625 </dt>
626 <dd><p>Returns the id of the currently set hyperlink, or <code>NULL</code> if no
627 hyperlink attribute is currently set.
628 </p>
629 <p>Note: The returned string is only valid up to the next invocation of
630 <code>term_ostream_set_hyperlink</code>.
631 </p></dd></dl>
632
633 <dl>
634 <dt><u>Function:</u> void <b>term_ostream_set_hyperlink</b><i> (term_ostream_t&nbsp;<var>stream</var>, const&nbsp;char&nbsp;*<var>ref</var>, const&nbsp;char&nbsp;*<var>id</var>)</i>
635 <a name="IDX46"></a>
636 </dt>
637 <dd><p>Sets or removes a hyperlink attribute.
638 </p>
639 <p>To set a hyperlink attribute, pass a non-<code>NULL</code> <var>ref</var>.
640 <var>ref</var> is an URL; it should be at most 2083 bytes long. Non-ASCII
641 characters should be URI-escaped (using the %nn syntax). <var>id</var> is
642 an optional identifier. Multiple hyperlinks with the same <var>id</var>
643 will be highlighted together. If specified, <var>id</var> should be at most
644 250 bytes long.
645 </p>
646 <p>To remove a hyperlink attribute, pass <code>NULL</code> for <var>ref</var> and <var>id</var>.
647 </p>
648 <p>Hyperlinks don't nest. That is, a hyperlink attribute is enabled only
649 up to the next invocation of <code>styled_ostream_set_hyperlink</code>.
650 </p></dd></dl>
651
652 <dl>
653 <dt><u>Function:</u> void <b>term_ostream_flush_to_current_style</b><i> (term_ostream_t&nbsp;<var>stream</var>)</i>
654 <a name="IDX47"></a>
655 </dt>
656 <dd><p>This function acts like <code>ostream_flush (<var>stream</var>, FLUSH_THIS_STREAM)</code>,
657 except that it leaves the terminal with the current text attributes enabled,
658 instead of with the default text attributes.
659 </p>
660 <p>After calling this function, you can output strings without newlines(!) to the
661 underlying file descriptor, and they will be rendered like strings passed to
662 <code>ostream_write_mem</code>, <code>ostream_write_str</code>, or <code>ostream_printf</code>.
663 </p></dd></dl>
664
665
666 <a name="The-html_005fostream-class"></a>
667 <a name="SEC28"></a>
668 <h4 class="subsubsection"> <a href="libtextstyle_toc.html#TOC28">3.5.3.4 The <code>html_ostream</code> class</a> </h4>
669
670 <p>The <code>html_ostream</code> class supports output to any destination, in HTML
671 syntax. Its type is &lsquo;<samp>html_ostream_t</samp>&rsquo;. It is a subclass of
672 &lsquo;<samp>ostream_t</samp>&rsquo;.
673 </p>
674 <p>It can be instantiated through this function:
675 </p>
676 <dl>
677 <dt><u>Function:</u> html_ostream_t <b>html_ostream_create</b><i> (ostream_t&nbsp;<var>destination</var>)</i>
678 <a name="IDX48"></a>
679 </dt>
680 <dd><p>Creates an output stream that takes input in the UTF-8 encoding and
681 writes it in HTML form on <code><var>destination</var></code>.
682 </p>
683 <p>This stream produces a sequence of lines. The caller is responsible for
684 opening the <code>&lt;body&gt;&lt;html&gt;</code> elements before and for closing them
685 after the use of this stream.
686 </p>
687 <p>Note: The resulting stream must be closed before <code><var>destination</var></code>
688 can be closed.
689 </p></dd></dl>
690
691 <p>The class adds the following methods:
692 </p>
693 <dl>
694 <dt><u>Function:</u> void <b>html_ostream_begin_span</b><i> (html_ostream_t&nbsp;<var>stream</var>, const&nbsp;char&nbsp;*<var>classname</var>)</i>
695 <a name="IDX49"></a>
696 </dt>
697 <dd><p>Starts a <code>&lt;span class=&quot;<var>classname</var>&quot;&gt;</code> element. The
698 <code><var>classname</var></code> is the name of a CSS class. It can be chosen
699 arbitrarily and customized through the CSS file.
700 </p></dd></dl>
701
702 <dl>
703 <dt><u>Function:</u> void <b>html_ostream_end_span</b><i> (html_ostream_t&nbsp;<var>stream</var>, const&nbsp;char&nbsp;*<var>classname</var>)</i>
704 <a name="IDX50"></a>
705 </dt>
706 <dd><p>Ends a <code>&lt;span class=&quot;<var>classname</var>&quot;&gt;</code> element.
707 </p>
708 <p>The <code>html_ostream_begin_span</code> / <code>html_ostream_end_span</code> calls
709 must match properly.
710 </p></dd></dl>
711
712 <dl>
713 <dt><u>Function:</u> const&nbsp;char&nbsp;* <b>html_ostream_get_hyperlink_ref</b><i> (html_ostream_t&nbsp;<var>stream</var>)</i>
714 <a name="IDX51"></a>
715 </dt>
716 <dd><p>Returns the referred URL of the currently set hyperlink, or <code>NULL</code>
717 if no hyperlink attribute is currently set.
718 </p>
719 <p>Note: The returned string is only valid up to the next invocation of
720 <code>html_ostream_set_hyperlink_ref</code>.
721 </p></dd></dl>
722
723 <dl>
724 <dt><u>Function:</u> void <b>html_ostream_set_hyperlink_ref</b><i> (html_ostream_t&nbsp;<var>stream</var>, const&nbsp;char&nbsp;*<var>ref</var>)</i>
725 <a name="IDX52"></a>
726 </dt>
727 <dd><p>Sets or removes a hyperlink attribute.
728 </p>
729 <p>To set a hyperlink attribute, pass a non-<code>NULL</code> <var>ref</var>.
730 <var>ref</var> is an URL; it should be at most 2083 bytes long. Non-ASCII
731 characters should be URI-escaped (using the %nn syntax).
732 </p>
733 <p>To remove a hyperlink attribute, pass <code>NULL</code> for <var>ref</var>.
734 </p>
735 <p>Hyperlinks don't nest. That is, a hyperlink attribute is enabled only
736 up to the next invocation of <code>html_ostream_set_hyperlink_ref</code>.
737 </p></dd></dl>
738
739 <dl>
740 <dt><u>Function:</u> void <b>html_ostream_flush_to_current_style</b><i> (html_ostream_t&nbsp;<var>stream</var>)</i>
741 <a name="IDX53"></a>
742 </dt>
743 <dd><p>This function acts like <code>ostream_flush (<var>stream</var>, FLUSH_THIS_STREAM)</code>,
744 except that it leaves the destination with the current text style enabled,
745 instead of with the default text style.
746 </p>
747 <p>After calling this function, you can output strings without newlines(!) to the
748 underlying stream, and they will be rendered like strings passed to
749 <code>ostream_write_mem</code>, <code>ostream_write_str</code>, or <code>ostream_printf</code>.
750 </p></dd></dl>
751
752
753 <a name="The-memory_005fostream-class"></a>
754 <a name="SEC29"></a>
755 <h4 class="subsubsection"> <a href="libtextstyle_toc.html#TOC29">3.5.3.5 The <code>memory_ostream</code> class</a> </h4>
756
757 <p>The <code>memory_ostream</code> class supports output to an in-memory buffer.
758 Its type is &lsquo;<samp>memory_ostream_t</samp>&rsquo;. It is a subclass of
759 &lsquo;<samp>ostream_t</samp>&rsquo;.
760 </p>
761 <p>It can be instantiated through this function:
762 </p>
763 <dl>
764 <dt><u>Function:</u> memory_ostream_t <b>memory_ostream_create</b><i> (void)</i>
765 <a name="IDX54"></a>
766 </dt>
767 <dd><p>Creates an output stream that accumulates the output in a memory buffer.
768 </p></dd></dl>
769
770 <p>The class adds the following method:
771 </p>
772 <dl>
773 <dt><u>Function:</u> void <b>memory_ostream_contents</b><i> (memory_ostream_t&nbsp;<var>stream</var>, const&nbsp;void&nbsp;**<var>bufp</var>, size_t&nbsp;*<var>buflenp</var>)</i>
774 <a name="IDX55"></a>
775 </dt>
776 <dd><p>Returns a pointer to the output accumulated so far and its size. It
777 stores them in <code>*<var>bufp</var></code> and <code>*<var>buflenp</var></code>, respectively.
778 </p>
779 <p>Note: These two return values become invalid when more output is done to
780 the stream or when the stream is freed.
781 </p></dd></dl>
782
783
784 <a name="The-iconv_005fostream-class"></a>
785 <a name="SEC30"></a>
786 <h4 class="subsubsection"> <a href="libtextstyle_toc.html#TOC30">3.5.3.6 The <code>iconv_ostream</code> class</a> </h4>
787
788 <p>The <code>iconv_ostream</code> class supports output to any destination. Its
789 type is &lsquo;<samp>iconv_ostream_t</samp>&rsquo;. It is a subclass of &lsquo;<samp>ostream_t</samp>&rsquo;
790 that adds no methods.
791 </p>
792 <p>It can be instantiated through this function:
793 </p>
794 <dl>
795 <dt><u>Function:</u> iconv_ostream_t <b>iconv_ostream_create</b><i> (const&nbsp;char&nbsp;*<var>from_encoding</var>, const&nbsp;char&nbsp;*<var>to_encoding</var>, ostream_t&nbsp;<var>destination</var>)</i>
796 <a name="IDX56"></a>
797 </dt>
798 <dd><p>Creates an output stream that converts from <code><var>from_encoding</var></code> to
799 <code><var>to_encoding</var></code>, writing the result to <code><var>destination</var></code>.
800 </p>
801 <p>Note: The resulting stream must be closed before <code><var>destination</var></code>
802 can be closed.
803 </p></dd></dl>
804
805
806 <a name="styled_005fostream-subclasses"></a>
807 <a name="SEC31"></a>
808 <h3 class="subsection"> <a href="libtextstyle_toc.html#TOC31">3.5.4 Concrete <code>styled_ostream</code> subclasses</a> </h3>
809
810
811
812 <a name="The-term_005fstyled_005fostream-class"></a>
813 <a name="SEC32"></a>
814 <h4 class="subsubsection"> <a href="libtextstyle_toc.html#TOC32">3.5.4.1 The <code>term_styled_ostream</code> class</a> </h4>
815
816 <p>The <code>term_styled_ostream</code> class supports styled output to a file
817 descriptor that is connected to a terminal emulator or console. Its type
818 is &lsquo;<samp>term_styled_ostream_t</samp>&rsquo;. It is a subclass of
819 &lsquo;<samp>styled_ostream_t</samp>&rsquo;.
820 </p>
821 <p>It can be instantiated through this function:
822 </p>
823 <dl>
824 <dt><u>Function:</u> term_styled_ostream_t <b>term_styled_ostream_create</b><i> (int&nbsp;<var>fd</var>, const&nbsp;char&nbsp;*<var>filename</var>, ttyctl_t&nbsp;<var>tty_control</var>, const&nbsp;char&nbsp;*<var>css_filename</var>)</i>
825 <a name="IDX57"></a>
826 </dt>
827 <dd><p>Creates an output stream referring to the file descriptor <code><var>fd</var></code>,
828 styled with the file <code><var>css_filename</var></code>.
829 </p>
830 <p><code><var>filename</var></code> is used only for error messages.
831 </p>
832 <p><code><var>tty_control</var></code> specifies the amount of control to take over the
833 underlying tty.
834 </p>
835 <p>Note: The resulting stream must be closed before <code><var>fd</var></code> can be
836 closed.
837 </p>
838 <p>Returns <code>NULL</code> upon failure.
839 </p></dd></dl>
840
841 <p>The following is a variant of this function. Upon failure, it does not
842 return <code>NULL</code>; instead, it returns a styled <code>fd_stream</code> on
843 which the styling operations exist but are no-ops.
844 </p>
845 <dl>
846 <dt><u>Function:</u> styled_ostream_t <b>styled_ostream_create</b><i> (int&nbsp;<var>fd</var>, const&nbsp;char&nbsp;*<var>filename</var>, ttyctl_t&nbsp;<var>tty_control</var>, const&nbsp;char&nbsp;*<var>css_filename</var>)</i>
847 <a name="IDX58"></a>
848 </dt>
849 <dd><p>Creates an output stream referring to the file descriptor <code><var>fd</var></code>,
850 styled with the file <code><var>css_filename</var></code> if possible.
851 </p>
852 <p><code><var>filename</var></code> is used only for error messages.
853 </p>
854 <p><code><var>tty_control</var></code> specifies the amount of control to take over the
855 underlying tty.
856 </p>
857 <p>Note: The resulting stream must be closed before <code><var>fd</var></code> can be
858 closed.
859 </p></dd></dl>
860
861
862 <a name="The-html_005fstyled_005fostream-class"></a>
863 <a name="SEC33"></a>
864 <h4 class="subsubsection"> <a href="libtextstyle_toc.html#TOC33">3.5.4.2 The <code>html_styled_ostream</code> class</a> </h4>
865
866 <p>The <code>html_styled_ostream</code> class supports styled output to any
867 destination, in HTML syntax. Its type is &lsquo;<samp>html_styled_ostream_t</samp>&rsquo;.
868 It is a subclass of &lsquo;<samp>styled_ostream_t</samp>&rsquo;.
869 </p>
870 <p>It can be instantiated through this function:
871 </p>
872 <dl>
873 <dt><u>Function:</u> html_styled_ostream_t <b>html_styled_ostream_create</b><i> (ostream_t&nbsp;<var>destination</var>, const&nbsp;char&nbsp;*<var>css_filename</var>)</i>
874 <a name="IDX59"></a>
875 </dt>
876 <dd><p>Creates an output stream that takes input in the UTF-8 encoding and
877 writes it in HTML form on <code><var>destination</var></code>, styled with the file
878 <code><var>css_filename</var></code>.
879 </p>
880 <p>Note: The resulting stream must be closed before <code><var>destination</var></code>
881 can be closed.
882 </p></dd></dl>
883
884
885 <a name="The-noop_005fstyled_005fostream-class"></a>
886 <a name="SEC34"></a>
887 <h4 class="subsubsection"> <a href="libtextstyle_toc.html#TOC34">3.5.4.3 The <code>noop_styled_ostream</code> class</a> </h4>
888
889 <p>The <code>noop_styled_ostream</code> class supports the styled output operations
890 to any destination. The text is output to the given destination; the
891 styling operations, however, do nothing. Its type is
892 &lsquo;<samp>noop_styled_ostream_t</samp>&rsquo;. It is a subclass of &lsquo;<samp>styled_ostream_t</samp>&rsquo;.
893 </p>
894 <p>It can be instantiated through this function:
895 </p>
896 <dl>
897 <dt><u>Function:</u> noop_styled_ostream_t <b>noop_styled_ostream_create</b><i> (ostream_t&nbsp;<var>destination</var>, bool&nbsp;<var>pass_ownership</var>)</i>
898 <a name="IDX60"></a>
899 </dt>
900 <dd><p>Creates an output stream that delegates to <code><var>destination</var></code> and
901 that supports the styling operations as no-ops.
902 </p>
903 <p>If <code><var>pass_ownership</var></code> is <code>true</code>, closing the resulting
904 stream will automatically close the <code><var>destination</var></code>.
905 </p>
906 <p>Note: If <code><var>pass_ownership</var></code> is <code>false</code>, the resulting stream
907 must be closed before <code><var>destination</var></code> can be closed.
908 </p></dd></dl>
909
910
911 <a name="Accessors"></a>
912 <a name="SEC35"></a>
913 <h3 class="subsection"> <a href="libtextstyle_toc.html#TOC35">3.5.5 Accessor functions</a> </h3>
914
915 <p>The various concrete stream classes have methods that allow you to retrieve
916 the arguments passed to the respective constructor function.
917 </p>
918 <p>Note: While these methods allow you to retrieve the underlying destination
919 stream of various kinds of stream, it is not recommended to operate on both
920 the stream and its underlying destination stream at the same time. Doing
921 so can lead to undesired interactions between the two streams.
922 </p>
923 <p>The <code>file_ostream</code> class has this accessor method:
924 </p>
925 <dl>
926 <dt><u>Function:</u> FILE&nbsp;* <b>file_ostream_get_stdio_stream</b><i> (file_ostream_t&nbsp;<var>stream</var>)</i>
927 <a name="IDX61"></a>
928 </dt>
929 </dl>
930
931 <p>The <code>fd_ostream</code> class has these accessor methods:
932 </p>
933 <dl>
934 <dt><u>Function:</u> int <b>fd_ostream_get_descriptor</b><i> (fd_ostream_t&nbsp;<var>stream</var>)</i>
935 <a name="IDX62"></a>
936 </dt>
937 </dl>
938 <dl>
939 <dt><u>Function:</u> const&nbsp;char&nbsp;* <b>fd_ostream_get_filename</b><i> (fd_ostream_t&nbsp;<var>stream</var>)</i>
940 <a name="IDX63"></a>
941 </dt>
942 </dl>
943 <dl>
944 <dt><u>Function:</u> bool <b>fd_ostream_is_buffered</b><i> (fd_ostream_t&nbsp;<var>stream</var>)</i>
945 <a name="IDX64"></a>
946 </dt>
947 </dl>
948
949 <p>The <code>term_ostream</code> class has these accessor methods:
950 </p>
951 <dl>
952 <dt><u>Function:</u> int <b>term_ostream_get_descriptor</b><i> (term_ostream_t&nbsp;<var>stream</var>)</i>
953 <a name="IDX65"></a>
954 </dt>
955 </dl>
956 <dl>
957 <dt><u>Function:</u> const&nbsp;char&nbsp;* <b>term_ostream_get_filename</b><i> (term_ostream_t&nbsp;<var>stream</var>)</i>
958 <a name="IDX66"></a>
959 </dt>
960 </dl>
961 <dl>
962 <dt><u>Function:</u> ttyctl_t <b>term_ostream_get_tty_control</b><i> (term_ostream_t&nbsp;<var>stream</var>)</i>
963 <a name="IDX67"></a>
964 </dt>
965 </dl>
966 <dl>
967 <dt><u>Function:</u> ttyctl_t <b>term_ostream_get_effective_tty_control</b><i> (term_ostream_t&nbsp;<var>stream</var>)</i>
968 <a name="IDX68"></a>
969 </dt>
970 <dd><p>Returns the effective tty control of the stream (not <code>TTYCTL_AUTO</code>).
971 </p></dd></dl>
972
973 <p>The <code>iconv_ostream</code> class has these accessor methods:
974 </p>
975 <dl>
976 <dt><u>Function:</u> const&nbsp;char&nbsp;* <b>iconv_ostream_get_from_encoding</b><i> (iconv_ostream_t&nbsp;<var>stream</var>)</i>
977 <a name="IDX69"></a>
978 </dt>
979 </dl>
980 <dl>
981 <dt><u>Function:</u> const&nbsp;char&nbsp;* <b>iconv_ostream_get_to_encoding</b><i> (iconv_ostream_t&nbsp;<var>stream</var>)</i>
982 <a name="IDX70"></a>
983 </dt>
984 </dl>
985 <dl>
986 <dt><u>Function:</u> ostream_t <b>iconv_ostream_get_destination</b><i> (iconv_ostream_t&nbsp;<var>stream</var>)</i>
987 <a name="IDX71"></a>
988 </dt>
989 </dl>
990
991 <p>The <code>html_ostream</code> class has this accessor method:
992 </p>
993 <dl>
994 <dt><u>Function:</u> ostream_t <b>html_ostream_get_destination</b><i> (html_ostream_t&nbsp;<var>stream</var>)</i>
995 <a name="IDX72"></a>
996 </dt>
997 </dl>
998
999 <p>The <code>term_styled_ostream</code> class has these accessor methods:
1000 </p>
1001 <dl>
1002 <dt><u>Function:</u> term_ostream_t <b>term_styled_ostream_get_destination</b><i> (term_styled_ostream_t&nbsp;<var>stream</var>)</i>
1003 <a name="IDX73"></a>
1004 </dt>
1005 </dl>
1006 <dl>
1007 <dt><u>Function:</u> const&nbsp;char&nbsp;* <b>term_styled_ostream_get_css_filename</b><i> (term_styled_ostream_t&nbsp;<var>stream</var>)</i>
1008 <a name="IDX74"></a>
1009 </dt>
1010 </dl>
1011
1012 <p>The <code>html_styled_ostream</code> class has these accessor methods:
1013 </p>
1014 <dl>
1015 <dt><u>Function:</u> ostream_t <b>html_styled_ostream_get_destination</b><i> (html_styled_ostream_t&nbsp;<var>stream</var>)</i>
1016 <a name="IDX75"></a>
1017 </dt>
1018 </dl>
1019 <dl>
1020 <dt><u>Function:</u> html_ostream_t <b>html_styled_ostream_get_html_destination</b><i> (html_styled_ostream_t&nbsp;<var>stream</var>)</i>
1021 <a name="IDX76"></a>
1022 </dt>
1023 </dl>
1024 <dl>
1025 <dt><u>Function:</u> const&nbsp;char&nbsp;* <b>html_styled_ostream_get_css_filename</b><i> (html_styled_ostream_t&nbsp;<var>stream</var>)</i>
1026 <a name="IDX77"></a>
1027 </dt>
1028 </dl>
1029
1030 <p>The <code>noop_styled_ostream</code> class has these accessor methods:
1031 </p>
1032 <dl>
1033 <dt><u>Function:</u> ostream_t <b>noop_styled_ostream_get_destination</b><i> (noop_styled_ostream_t&nbsp;<var>stream</var>)</i>
1034 <a name="IDX78"></a>
1035 </dt>
1036 </dl>
1037 <dl>
1038 <dt><u>Function:</u> bool <b>noop_styled_ostream_is_owning_destination</b><i> (noop_styled_ostream_t&nbsp;<var>stream</var>)</i>
1039 <a name="IDX79"></a>
1040 </dt>
1041 </dl>
1042
1043
1044 <a name="Debugging-the-styling-code"></a>
1045 <a name="SEC36"></a>
1046 <h2 class="section"> <a href="libtextstyle_toc.html#TOC36">3.6 Debugging the text styling support</a> </h2>
1047
1048 <p>If you want to understand which output of your program is associated with
1049 which CSS classes, the simplest way is as follows:
1050 </p>
1051 <ol>
1052 <li>
1053 Run the program with the command-line option <code>--color=html</code>,
1054 redirecting the output to a file.
1055 </li><li>
1056 Then inspect this output. Text regions associated with a CSS class are
1057 surrounded by <code>&lt;span class=&quot;<var>css-class</var>&quot;&gt;</code>...<code>&lt;/span&gt;</code>.
1058 </li></ol>
1059
1060
1061 <a name="What-to-document"></a>
1062 <a name="SEC37"></a>
1063 <h2 class="section"> <a href="libtextstyle_toc.html#TOC37">3.7 Documenting the text styling support</a> </h2>
1064
1065 <p>To make the text styling support available to the end user of your
1066 package, the following need to be documented:
1067 </p><ul>
1068 <li>
1069 The command-line options. This typically needs to be done in several
1070 places: in the &lsquo;<samp>--help</samp>&rsquo; output, in the <code>man</code> pages (if present),
1071 and in the documentation.
1072 </li><li>
1073 Which programs support &lsquo;<samp>--color=test</samp>&rsquo;?
1074 </li><li>
1075 The list of CSS classes and their meaning. This is necessary, so that
1076 the user can create their own style file; the CSS classes are part of the
1077 selectors in the CSS rules.
1078 </li><li>
1079 The location of the default style file. This is a convenience, so that
1080 the user, when creating their own style file, can start from the default
1081 one.
1082 </li><li>
1083 The environment variable, called <code><var>style_file_envvar</var></code> above,
1084 that, when set to a non-empty value, specifies the style file to use.
1085 </li></ul>
1086
1087
1088 <table cellpadding="1" cellspacing="1" border="0">
1089 <tr><td valign="middle" align="left">[<a href="#SEC15" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
1090 <td valign="middle" align="left">[<a href="libtextstyle_4.html#SEC38" title="Next chapter"> &gt;&gt; </a>]</td>
1091 <td valign="middle" align="left"> &nbsp; </td>
1092 <td valign="middle" align="left"> &nbsp; </td>
1093 <td valign="middle" align="left"> &nbsp; </td>
1094 <td valign="middle" align="left"> &nbsp; </td>
1095 <td valign="middle" align="left"> &nbsp; </td>
1096 <td valign="middle" align="left">[<a href="libtextstyle_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
1097 <td valign="middle" align="left">[<a href="libtextstyle_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
1098 <td valign="middle" align="left">[<a href="libtextstyle_5.html#SEC46" title="Index">Index</a>]</td>
1099 <td valign="middle" align="left">[<a href="libtextstyle_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
1100 </tr></table>
1101 <p>
1102 <font size="-1">
1103 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>.
1104 </font>
1105 <br>
1106
1107 </p>
1108 </body>
1109 </html>