Mercurial > repos > rliterman > csp2

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