     [file version.texi not included]

This manual provides documentation for the GNU libtextstyle library.

Copyright (C) 2018-2019 Free Software Foundation, Inc.

This manual is free documentation.  It is dually licensed under the GNU FDL and the GNU GPL.  This means that you can redistribute this manual under either of these two licenses, at your choice.

This manual is covered by the GNU FDL.  Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License (FDL), either version 1.2 of the License, or (at your option) any later version published by the Free Software Foundation (FSF); with no Invariant Sections, with no Front-Cover Text, and with no Back-Cover Texts. A copy of the license is at https://www.gnu.org/licenses/fdl.html.

This manual is covered by the GNU GPL.  You can redistribute it and/or modify it under the terms of the GNU General Public License (GPL), either version 2 of the License, or (at your option) any later version published by the Free Software Foundation (FSF). A copy of the license is at https://www.gnu.org/licenses/gpl.html.

GNU libtextstyle
****************

This manual documents the GNU libtextstyle library, version VERSION.

Introduction
************

Text is easier to read when it is accompanied with styling information, such as color, font attributes (weight, posture), or underlining, and this styling is customized appropriately for the output device.

GNU libtextstyle provides an easy way to add styling to programs that produce output to a console or terminal emulator window.  It does this in a way that allows the end user to customize the styling using the industry standard, namely Cascading Style Sheets (CSS).

Style definitions
=================

Let's look at the traditional way styling is done for specific programs.

Browsers, when they render HTML, use CSS styling.

The older approach to user-customizable text styling is that the user associates patterns with escape sequences in an environment variable or a command-line argument.  This is the approach used, for example, by the GNU ls program in combination with the dircolors program. The processing is distributed across several steps:

 1. There is default style definition that is hard-coded in the dircolors program.  The user can also define their own definitions in a file such as ~/.dir_colors.  This style definition contains explicit terminal escape sequences; thus, it can only be used with consoles and terminal emulators, and each style definition applies only to a certain class of mostly-compatible terminal emulators.

 2. The dircolors program, when invoked, translates such a style definition to a sequence of shell statements that sets an environment variable LS_COLORS.

 3. The shell executes these statements, and thus sets the environment variable LS_COLORS.

 4. The program looks at the environment variable and emits the listed escape sequences.

In contrast, this library implements styling as follows:

 1. There is a default style definition in a CSS file that is part of the same package as the stylable program.  The user can also define their own definitions in a CSS file, and set an environment environment variable to point to it.

 2. The program looks at the environment variable, parses the CSS file, translates the styling specifications to the form that is appropriate for the output device (escape sequences for terminal emulators, inline CSS and <span> elements for HTML output), and emits it.

Thus, with GNU libtextstyle, the styling has the following properties:

  * It is easier for the user to define their own styling, because the file format is standardized and supported by numerous syntax aware editors.

  * A styling file does not depend on the particular output device.  An HTML output and a black-on-white terminal emulator can use the same styling file.  A white-on-black (or even green-on-black) terminal emulator will need different styling, though.

  * It is simpler: There is no need for a program that converts the style specification from one format to another.

Built-in versus separate styling
================================

There are generally two approaches for adding styling to text:

  * The program that generates the text adds the styling.  It does so through interleaved statements that turn on or off specific attributes.

  * The styling gets added by a separate program, that postprocesses the output.  This separate program usually uses regular expressions to determine which text regions to style with a certain set of text attributes.

The first approach produces a styling that is 100% correct, regardless of the complexity of the text that is being output.  This is the preferred approach for example for JSON, XML, or programming language text.

The second approach works well if the output has a simple, easy-to-parse format.  It may produce wrong styling in some cases when the text format is more complex.  This approach is often used for viewing log files.

GNU libtextstyle supports both approaches; it includes an example program for each of the two approaches.

The end user's perspective
**************************

Styled output can viewed fine in a console or terminal emulator window.

The stylable program will typically have the following options:

--color
     Use colors and other text attributes always.

--color=WHEN
     Use colors and other text attributes if WHEN.  WHEN may be always, never, auto, or html.

--style=STYLE-FILE
     Specify the CSS style rule file for --color.

For more details, see the sections The --color option and The --style option below.

If the output does not fit on a screen, you can use less -R to scroll around in the styled output.  For example:

     PROGRAM --color ARGUMENTS | less -R

The environment variable TERM
=============================

The environment variable TERM contains a identifier for the text window's capabilities.  You can get a detailed list of these cababilities by using the infocmp command (for example: infocmp -L1 xterm), using man 5 terminfo as a reference.

When producing text with embedded color directives, a libtextstyle-enabled program looks at the TERM variable. Text windows today typically support at least 8 colors.  Often, however, the text window supports 16 or more colors, even though the TERM variable is set to a identifier denoting only 8 supported colors.  It can be worth setting the TERM variable to a different value in these cases.

After setting TERM, you can verify how well it works by invoking PROGRAM --color=test, where PROGRAM is any libtextstyle-enabled program, and seeing whether the output looks like a reasonable color map.

Terminal emulator programs
--------------------------

The following terminal emulator programs support 256 colors and set TERM=xterm-256color accordingly:

  * In GNOME: gnome-terminal, tilda.

  * rxvt-unicode (sets TERM=rxvt-unicode-256color).

  * st (sets TERM=st-256color).

  * QTerminal.

  * On macOS: Terminal, iTerm2.

The following terminal emulator programs support 256 colors.  You only need to set TERM=xterm-256color or similar; the programs by default set TERM to a value that supports only 8 colors.

  * xterm is in many cases built with support for 256 colors.  But it sets TERM=xterm.  You need to set TERM=xterm-256color.

  * In GNOME: guake (sets TERM=xterm).  You need to set TERM=xterm-256color.

  * In KDE: konsole (sets TERM=xterm).  You need to set TERM=xterm-256color or TERM=konsole-256color.

  * In KDE: yakuake (sets TERM=xterm).  You need to set TERM=xterm-256color.

  * In Enlightenment: Eterm (sets TERM=Eterm).  You need to set TERM=Eterm-256color.

  * mlterm (sets TERM=mlterm).  You need to set TERM=mlterm-256color.

  * On Windows: PuTTY (sets TERM=xterm).  You need to set TERM=xterm-256color or TERM=putty-256color.

  * On Windows: TeraTerm (sets TERM=xterm).  You need to set TERM=xterm-256color.

A couple of terminal emulator programs support even the entire RGB color space (16 million colors).  To get this to work, at this date (2019), you need three things:

  * The ncurses library version 6.1 or newer must be installed.

  * You need a recent version of the respective terminal emulator program. See https://gist.github.com/XVilka/8346728 for the most recent developments in this area.

  * You need to set the TERM environment variable to the corresponding value: TERM=xterm-direct instead of TERM=xterm or TERM=xterm-256color, TERM=konsole-direct in konsole, TERM=st-direct in st, TERM=mlterm-direct in mlterm, or TERM=iterm2-direct in iTerm2 on macOS.

Consoles
--------

On OpenBSD 6 consoles, TERM=xterm produces better results than the default TERM=vt220.

On NetBSD 8 consoles, TERM=netbsd6 produces better results than the default TERM=vt100.

On Windows consoles, no TERM setting is needed.

Emacs as a terminal emulator
============================

Emacs has several terminal emulators: M-x shell and M-x term.  M-x term has good support for styling, whereas in M-x shell most of the styling gets lost.

The --color option
==================

The --color=WHEN option specifies under which conditions styled (colorized) output should be generated.  The WHEN part can be one of the following:

always
yes
     The output will be colorized.

never
no
     The output will not be colorized.

auto
tty
     The output will be colorized if the output device is a tty, i.e. when the output goes directly to a text screen or terminal emulator window.

html
     The output will be colorized and be in HTML format.  This value is only supported by some programs.

test
     This is a special value, understood only by some programs.  It is explained in the section (The TERM variable) above.

--color is equivalent to --color=yes.  The default is --color=auto.

Thus, a command that invokes a libtextstyle-enabled program will produce colorized output when called by itself in a command window. Whereas in a pipe, such as PROGRAM ARGUMENTS | less -R, it will not produce colorized output.  To get colorized output in this situation nevertheless, use the command PROGRAM --color ARGUMENTS | less -R.

The --color=html option will produce output that can be viewed in a browser.  This can be useful, for example, for Indic languages, because the renderic of Indic scripts in browsers is usually better than in terminal emulators.

Note that the output produced with the --color option is not consumable by programs that expect the raw text.  It contains additional terminal-specific escape sequences or HTML tags.  For example, an XML parser will give a syntax error when confronted with a colored XML output.  Except for the --color=html case, you therefore normally don't need to save output produced with the --color option in a file.

The --style option
==================

The --style=STYLE_FILE option specifies the style file to use when colorizing.  It has an effect only when the --color option is effective.

If the --style option is not specified, the program may consider the value of an environment variable.  It is meant to point to the user's preferred style for such output.  The name of such an environment variable, if supported, is documented in the documentation of the libtextstyle-enabled program.

You can also design your own styles.  This is described in the next section.

Creating your own style files
-----------------------------

The same style file can be used for styling a certain type of output, for terminal output and for HTML output.  It is written in CSS (Cascading Style Sheet) syntax.  See https://www.w3.org/TR/css2/cover.html for a formal definition of CSS.  Many HTML authoring tutorials also contain explanations of CSS.

In the case of HTML output, the style file is embedded in the HTML output. In the case of text output, the style file is interpreted by the libtextstyle-enabled program.

You should avoid @import statements, because

  - In the case of HTML output, the files referenced by the @import statements would not be embedded in the HTML output.  In fact, relative file names would be interpreted relative to the resulting HTML file.

  - In the case of text output, @imports are not supported, due to a limitation in libcroco.

CSS rules are built up from selectors and declarations.  The declarations specify graphical properties; the selectors specify when they apply.

GNU libtextstyle supports simple selectors based on "CSS classes", see the CSS2 spec, section 5.8.3.  The set of CSS classes that are supported by a libtextstyle-enabled program are documented in the documentation of that program.

These selectors can be combined to hierarchical selectors.  For example, assume a program supports the CSS classes string (that matches a string) and non-ascii (that matches a word with non-ASCII characters), you could write

     .string .non-ascii { color: red; }

to highlight only the non-ASCII words inside strings.

In text mode, pseudo-classes (CSS2 spec, section 5.11) and pseudo-elements (CSS2 spec, section 5.12) are not supported.

The declarations in HTML mode are not limited; any graphical attribute supported by the browsers can be used.

The declarations in text mode are limited to the following properties. Other properties will be silently ignored.

color (CSS2 spec, section 14.1)
background-color (CSS2 spec, section 14.2.1)
     These properties are supported.  Colors will be adjusted to match the terminal's capabilities.  Note that many terminals support only 8 colors.

font-weight (CSS2 spec, section 15.2.3)
     This property is supported, but most terminals can only render two different weights: normal and bold.  Values >= 600 are rendered as bold.

font-style (CSS2 spec, section 15.2.3)
     This property is supported.  The values italic and oblique are rendered the same way.

text-decoration (CSS2 spec, section 16.3.1)
     This property is supported, limited to the values none and underline.

Debugging style files
---------------------

If you want to understand why the style rules in a style file produce the output that you see, you can do so in three steps:

 1. Run the program with the command-line option --color=html, redirecting the output to a file.

 2. Open the resulting HTML file in a browser.

 3. Use the browser's built-in CSS debugging tool.

       * In Firefox: From the pop-up menu, select "Inspect Element". Click somewhere in the DOM tree ("Inspector" tab) and look at the CSS declarations in the "Rules" tab.

       * In Chromium: From the pop-up menu, select "Inspect". Click somewhere in the DOM tree ("Elements" tab) and look at the CSS declarations in the "Styles" tab.

This technique allows you, in particular, to see which CSS declarations override which other CSS declarations from other CSS rules.

The programmer's perspective
****************************

As a programmer, enabling styling consists of the following tasks:

 1. Define the command-line options and environment variable that the user can use to control the styling.

 2. Define the CSS classes that the user can use in the CSS file.  Each CSS class corresponds to a text role; each CSS class can be given a different styling by the user.

 3. Change the output routines so that they take an ostream_t object as argument instead of a FILE *.

 4. Insert paired invocations to styled_ostream_begin_css_class, styled_ostream_end_css_class around each run of text with a specific text role.

 5. Link with libtextstyle.  If your package is using GNU autoconf, you can use the libtextstyle.m4 macro from Gnulib.

 6. Prepare a default style file.

 7. Update the documentation of your package.

The following sections go into more detail.

Basic use of libtextstyle
=========================

Source code that makes use of GNU libtextstyle needs an include statement:

     #include <textstyle.h>

Basic use of GNU libtextstyle consists of statements like these:

       styled_ostream_t stream =
         styled_ostream_create (STDOUT_FILENO, "(stdout)", TTYCTL_AUTO,
                                style_file_name);
       ...
       styled_ostream_begin_use_class (stream, css_class);
       ...
       ostream_write_str (stream, string);
       ...
       styled_ostream_end_use_class (stream, css_class);
       ...
       styled_ostream_free (stream);

Before this snippet, your code needs to determine the name of the style file to use (style_file_name).  If no styling is desired -- the precise condition depends on the value of color_mode but also on your application logic --, you should set style_file_name to NULL.

An object of type styled_ostream_t is allocated.  The function styled_ostream_create allocates it; the function styled_ostream_free deallocates it.

Such styled_ostream_t supports output operations (ostream_write_str), interleaved with adding and removing CSS classes.  The CSS class in effect when an output operation is performed determines, through the style file, the text attributes associated with that piece of text.

Include files
=============

The include file <textstyle.h> declares all facilities defined by the library.

Link options
============

The library to link with is called libtextstyle, with a system-dependent suffix.  You link with it though link options of the form -ltextstyle for a library installed in system locations, or -LLIBDIR -ltextstyle for a static library installed in other locations, or -LLIBDIR -ltextstyle -Wl,-rpath,LIBDIR for a shared library installed in other locations (assuming a GCC compatible compiler and linker and no libtool), or -LLIBDIR -ltextstyle -RLIBDIR for a shared library installed in other locations (with libtool).  Additionally, the link options may need to include the dependencies: -lm, and -lncurses or (on NetBSD) -ltermcap or (on AIX) -lxcurses or (on HP-UX) -lcurses, and on some systems also -liconv.

It is a bit complicated to determine the right link options in a portable way.  Therefore an Autoconf macro is provided in the file libtextstyle.m4 in Gnulib, that makes this task easier.  Assuming the build system of your package is based on GNU Autoconf, you invoke it through gl_LIBTEXTSTYLE.  It searches for an installed libtextstyle.  If found, it sets and AC_SUBSTs HAVE_LIBTEXTSTYLE=yes and the LIBTEXTSTYLE and LTLIBTEXTSTYLE variables, and augments the CPPFLAGS variable, and #defines HAVE_LIBTEXTSTYLE to 1.  Otherwise, it sets and AC_SUBSTs HAVE_LIBTEXTSTYLE=no and LIBTEXTSTYLE and LTLIBTEXTSTYLE to empty.  In link commands that use libtool, use LTLIBTEXTSTYLE; in link commands that don't use libtool, use LIBTEXTSTYLE.

If you use GNU Automake, the proper place to use the link options is PROGRAM_LDADD for programs and LIBRARY_LIBADD for libraries.

Command-line options
====================

While you are free to provide any command-line option to enable the styling of the output, it is good if different GNU programs use the same command-line options for this purpose.  These options are described in the sections The --color option and The --style option.  To achieve this, use the following API (declared in <textstyle.h>):

 -- Variable: bool color_test_mode
     True if a --color option with value test has been seen.

 -- Variable: enum color_option color_mode
     Stores the value of the --color option.

 -- Variable: const char * style_file_name
     Stores the value of the --style option.

Note: These variables, like any variables exported from shared libraries, can only be used in executable code.  You cannot portably use their address in initializers of global or static variables.  This is a restriction that is imposed by the Windows, Cygwin, and Android platforms.

 -- Function: bool handle_color_option (const char *OPTION)
     You invoke this function when, during argument parsing, you have encountered a --color or --color=... option.  The return value is an error indicator: true means an invalid option.

 -- Function: void handle_style_option (const char *OPTION)
     You invoke this function when, during argument parsing, you have encountered a --style or --style=... option.

 -- Function: void print_color_test (void)
     Prints a color test page.  You invoke this function after argument parsing, when the color_test_mode variable is true.

 -- Function: void style_file_prepare (const char *STYLE_FILE_ENVVAR, const char *STYLESDIR_ENVVAR, const char *STYLESDIR_AFTER_INSTALL, const char *DEFAULT_STYLE_FILE)
     Assigns a default value to style_file_name if necessary.  You invoke this function after argument parsing, when color_test_mode is false.

     STYLE_FILE_ENVVAR is an environment variable that, when set to a non-empty value, specifies the style file to use.  This environment variable is meant to be set by the user.

     STYLESDIR_ENVVAR is an environment variable that, when set to a non-empty value, specifies the directory with the style files, or NULL.  This is necessary for running the testsuite before make install.

     STYLESDIR_AFTER_INSTALL is the directory with the style files after make install.

     DEFAULT_STYLE_FILE is the file name of the default style file, relative to STYLESDIR.

The output stream hierarchy
===========================

There are various classes of output streams, some of them with styling support.  These ``classes'' are defined in an object-oriented programming style that resembles C++ or Java, but are actually implemented in C with a little bit of object orientation syntax.  These definitions are preprocessed down to C.  As a consequence, GNU libtextstyle is a C library and does not need to link with the C++ standard library.

All these classes are declared in <textstyle.h>.

The base output stream type is ostream_t.  It is a pointer type to a (hidden) implementation type.  Similarly for the subclasses.

When we say that some_ostream_t is a subclass of ostream_t, what we mean is:

  * Every some_ostream_t object can be converted to an ostream_t, by virtue of a simple assignment.  No cast is needed.

  * The opposite conversion, from ostream_t to some_ostream_t, can also be performed, provided that the object is actually an instance of some_ostream_t.

  * Every method ostream_FOOBAR exists also as a method some_ostream_FOOBAR with compatible argument types and a compatible return type.

The abstract ostream class
--------------------------

The base output stream type is ostream_t.

It has the following methods:

 -- Function: void ostream_write_mem (ostream_t STREAM, const void *DATA, size_t LEN)
     Writes a sequence of bytes to a stream.

 -- Function: void ostream_write_str (ostream_t STREAM, const char *STRING)
     Writes a string's contents to a stream.

 -- Function: void ostream_flush (ostream_t STREAM, ostream_flush_scope_t SCOPE)
     Brings buffered data to its destination.

 -- Function: void ostream_free (ostream_t STREAM)
     Closes and frees a stream.

The abstract styled_ostream class
---------------------------------

The type for a styled output stream is styled_ostream_t.  It is a subclass of ostream_t that adds the following methods:

 -- Function: void styled_ostream_begin_use_class (styled_ostream_t STREAM, const char *CLASSNAME)
     Starts a run of text belonging to CLASSNAME.  The CLASSNAME is the name of a CSS class.  It can be chosen arbitrarily and customized through the CSS file.

 -- Function: void styled_ostream_end_use_class (styled_ostream_t STREAM, const char *CLASSNAME)
     Ends a run of text belonging to CLASSNAME.  The styled_ostream_begin_use_class / styled_ostream_end_use_class calls must match properly.

 -- Function: void styled_ostream_flush_to_current_style (styled_ostream_t STREAM)
     This function acts like ostream_flush (STREAM, FLUSH_THIS_STREAM), except that it leaves the destination with the current text style enabled, instead of with the default text style.

     After calling this function, you can output strings without newlines(!) to the underlying stream, and they will be rendered like strings passed to ostream_write_mem or ostream_write_str.

Concrete ostream subclasses without styling
-------------------------------------------

The file_ostream class
......................

The file_ostream class supports output to an <stdio.h> FILE stream.  Its type is file_ostream_t.  It is a subclass of ostream_t that adds no methods.

It can be instantiated through this function:

 -- Function: file_ostream_t file_ostream_create (FILE *FP)
     Creates an output stream referring to FP.

     Note: The resulting stream must be closed before FP can be closed.

The fd_ostream class
....................

The file_ostream class supports output to a file descriptor.  Its type is fd_ostream_t.  It is a subclass of ostream_t that adds no methods.

It can be instantiated through this function:

 -- Function: fd_ostream_t fd_ostream_create (int FD, const char *FILENAME, bool BUFFERED)
     Creates an output stream referring to the file descriptor FD.

     FILENAME is used only for error messages.

     Note: The resulting stream must be closed before FD can be closed.

The term_ostream class
......................

The term_ostream class supports output to a file descriptor that is connected to a terminal emulator or console.  Its type is term_ostream_t.  It is a subclass of ostream_t.

It can be instantiated through this function:

 -- Function: term_ostream_t term_ostream_create (int FD, const char *FILENAME, ttyctl_t TTY_CONTROL)
     Creates an output stream referring to the file descriptor FD.

     FILENAME is used only for error messages.

     TTY_CONTROL specifies the amount of control to take over the underlying tty.

     The resulting stream will be line-buffered.

     Note: The resulting stream must be closed before FD can be closed.

The class adds the following methods:

 -- Function: term_color_t term_ostream_rgb_to_color (term_ostream_t STREAM, int RED, int GREEN, int BLUE)
     Converts an RGB value (RED, GREEN, BLUE in [0..255]) to a color, valid for this stream only.

 -- Function: term_color_t term_ostream_get_color (term_ostream_t STREAM)
 -- Function: void term_ostream_set_color (term_ostream_t STREAM, term_color_t COLOR)
     Gets/sets the text color.

 -- Function: term_color_t term_ostream_get_bgcolor (term_ostream_t STREAM)
 -- Function: void term_ostream_set_bgcolor (term_ostream_t STREAM, term_color_t COLOR)
     Gets/sets the background color.

 -- Function: term_weight_t term_ostream_get_weight (term_ostream_t STREAM)
 -- Function: void term_ostream_set_weight (term_ostream_t STREAM, term_weight_t WEIGHT)
     Gets/sets the font weight.

 -- Function: term_posture_t term_ostream_get_posture (term_ostream_t STREAM)
 -- Function: void term_ostream_set_posture (term_ostream_t STREAM, term_posture_t POSTURE)
     Gets/sets the font posture.

 -- Function: term_underline_t term_ostream_get_underline (term_ostream_t STREAM)
 -- Function: void term_ostream_set_underline (term_ostream_t STREAM, term_underline_t UNDERLINE)
     Gets/sets the text underline decoration.

 -- Function: void term_ostream_flush_to_current_style (term_ostream_t STREAM)
     This function acts like ostream_flush (STREAM, FLUSH_THIS_STREAM), except that it leaves the terminal with the current text attributes enabled, instead of with the default text attributes.

     After calling this function, you can output strings without newlines(!) to the underlying file descriptor, and they will be rendered like strings passed to ostream_write_mem or ostream_write_str.

The html_ostream class
......................

The html_ostream class supports output to any destination, in HTML syntax.  Its type is html_ostream_t.  It is a subclass of ostream_t.

It can be instantiated through this function:

 -- Function: html_ostream_t html_ostream_create (ostream_t DESTINATION)
     Creates an output stream that takes input in the UTF-8 encoding and writes it in HTML form on DESTINATION.

     This stream produces a sequence of lines.  The caller is responsible for opening the <body><html> elements before and for closing them after the use of this stream.

     Note: The resulting stream must be closed before DESTINATION can be closed.

The class adds the following methods:

 -- Function: void html_ostream_begin_span (html_ostream_t STREAM, const char *CLASSNAME)
     Starts a <span class="CLASSNAME"> element.  The CLASSNAME is the name of a CSS class.  It can be chosen arbitrarily and customized through the CSS file.

 -- Function: void html_ostream_end_span (html_ostream_t STREAM, const char *CLASSNAME)
     Ends a <span class="CLASSNAME"> element.

     The html_ostream_begin_span / html_ostream_end_span calls must match properly.

 -- Function: void html_ostream_flush_to_current_style (html_ostream_t STREAM)
     This function acts like ostream_flush (STREAM, FLUSH_THIS_STREAM), except that it leaves the destination with the current text style enabled, instead of with the default text style.

     After calling this function, you can output strings without newlines(!) to the underlying stream, and they will be rendered like strings passed to ostream_write_mem or ostream_write_str.

The memory_ostream class
........................

The memory_ostream class supports output to an in-memory buffer. Its type is memory_ostream_t.  It is a subclass of ostream_t.

It can be instantiated through this function:

 -- Function: memory_ostream_t memory_ostream_create (void)
     Creates an output stream that accumulates the output in a memory buffer.

The class adds the following method:

 -- Function: void memory_ostream_contents (memory_ostream_t STREAM, const void **BUFP, size_t *BUFLENP)
     Returns a pointer to the output accumulated so far and its size.  It stores them in *BUFP and *BUFLENP, respectively.

     Note: These two return values become invalid when more output is done to the stream.

The iconv_ostream class
.......................

The iconv_ostream class supports output to any destination.  Its type is iconv_ostream_t.  It is a subclass of ostream_t that adds no methods.

It can be instantiated through this function:

 -- Function: iconv_ostream_t iconv_ostream_create (const char *FROM_ENCODING, const char *TO_ENCODING, ostream_t DESTINATION)
     Creates an output stream that converts from FROM_ENCODING to TO_ENCODING, writing the result to DESTINATION.

     Note: The resulting stream must be closed before DESTINATION can be closed.

Concrete styled_ostream subclasses
----------------------------------

The term_styled_ostream class
.............................

The term_styled_ostream class supports styled output to a file descriptor that is connected to a terminal emulator or console.  Its type is term_styled_ostream_t.  It is a subclass of styled_ostream_t.

It can be instantiated through this function:

 -- Function: term_styled_ostream_t term_styled_ostream_create (int FD, const char *FILENAME, ttyctl_t TTY_CONTROL, const char *CSS_FILENAME)
     Creates an output stream referring to the file descriptor FD, styled with the file CSS_FILENAME.

     FILENAME is used only for error messages.

     TTY_CONTROL specifies the amount of control to take over the underlying tty.

     Note: The resulting stream must be closed before FD can be closed.

     Returns NULL upon failure.

The following is a variant of this function.  Upon failure, it does not return NULL; instead, it returns a styled fd_stream on which the styling operations exist but are no-ops.

 -- Function: styled_ostream_t styled_ostream_create (int FD, const char *FILENAME, ttyctl_t TTY_CONTROL, const char *CSS_FILENAME)
     Creates an output stream referring to the file descriptor FD, styled with the file CSS_FILENAME if possible.

     FILENAME is used only for error messages.

     TTY_CONTROL specifies the amount of control to take over the underlying tty.

     Note: The resulting stream must be closed before FD can be closed.

The html_styled_ostream class
.............................

The html_styled_ostream class supports styled output to any destination, in HTML syntax.  Its type is html_styled_ostream_t. It is a subclass of styled_ostream_t.

It can be instantiated through this function:

 -- Function: html_styled_ostream_t html_styled_ostream_create (ostream_t DESTINATION, const char *CSS_FILENAME)
     Creates an output stream that takes input in the UTF-8 encoding and writes it in HTML form on DESTINATION, styled with the file CSS_FILENAME.

     Note: The resulting stream must be closed before DESTINATION can be closed.

The noop_styled_ostream class
.............................

The noop_styled_ostream class supports the styled output operations to any destination.  The text is output to the given destination; the styling operations, however, do nothing.  Its type is noop_styled_ostream_t.  It is a subclass of styled_ostream_t.

It can be instantiated through this function:

 -- Function: noop_styled_ostream_t noop_styled_ostream_create (ostream_t DESTINATION, bool PASS_OWNERSHIP)
     Creates an output stream that delegates to DESTINATION and that supports the styling operations as no-ops.

     If PASS_OWNERSHIP is true, closing the resulting stream will automatically close the DESTINATION.

     Note: If PASS_OWNERSHIP is false, the resulting stream must be closed before DESTINATION can be closed.

Debugging the text styling support
==================================

If you want to understand which output of your program is associated with which CSS classes, the simplest way is as follows:

 1. Run the program with the command-line option --color=html, redirecting the output to a file.

 2. Then inspect this output.  Text regions associated with a CSS class are surrounded by <span class="CSS-CLASS">...</span>.

Documenting the text styling support
====================================

To make the text styling support available to the end user of your package, the following need to be documented:

  * The command-line options.  This typically needs to be done in several places: in the --help output, in the man pages (if present), and in the documentation.

  * Which programs support --color=test?

  * The list of CSS classes and their meaning.  This is necessary, so that the user can create their own style file; the CSS classes are part of the selectors in the CSS rules.

  * The location of the default style file.  This is a convenience, so that the user, when creating their own style file, can start from the default one.

  * The environment variable, called STYLE_FILE_ENVVAR above, that, when set to a non-empty value, specifies the style file to use.

Licenses
********

The files of this package are covered by the licenses indicated in each particular file or directory.  Here is a summary:

  * The libtextstyle library and the example programs are covered by the GNU General Public License (GPL). A copy of the license is included in GNU GPL.

  * This manual is free documentation.  It is dually licensed under the GNU FDL and the GNU GPL.  This means that you can redistribute this manual under either of these two licenses, at your choice. This manual is covered by the GNU FDL.  Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License (FDL), either version 1.2 of the License, or (at your option) any later version published by the Free Software Foundation (FSF); with no Invariant Sections, with no Front-Cover Text, and with no Back-Cover Texts. A copy of the license is included in GNU FDL. This manual is covered by the GNU GPL.  You can redistribute it and/or modify it under the terms of the GNU General Public License (GPL), either version 3 of the License, or (at your option) any later version published by the Free Software Foundation (FSF). A copy of the license is included in GNU GPL.

GNU GENERAL PUBLIC LICENSE
==========================

     [file gpl.texi not included]

GNU Free Documentation License
==============================

     [file fdl.texi not included]