1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename libtextstyle.info 4@c The @ifset makeinfo ... @end ifset conditional evaluates to true in makeinfo 5@c for info and html output, but to false in texi2html. 6@ifnottex 7@ifclear texi2html 8@set makeinfo 9@end ifclear 10@end ifnottex 11@settitle GNU @code{libtextstyle} 12@finalout 13@c Indices: 14@c cp = concept @cindex 15@c fn = function @findex 16@c vr = variable @vindex 17@c Unused predefined indices: 18@c ky = keystroke @kindex 19@c pg = program @pindex 20@c tp = type @tindex 21@ifclear texi2html 22@firstparagraphindent insert 23@end ifclear 24@c %**end of header 25 26@include version.texi 27 28@ifinfo 29@dircategory Software development 30@direntry 31* GNU libtextstyle: (libtextstyle). Output of styled text. 32@end direntry 33@end ifinfo 34 35@ifinfo 36This manual provides documentation for the GNU @code{libtextstyle} library. 37 38@copying 39Copyright (C) 2018-2019 Free Software Foundation, Inc. 40 41This manual is free documentation. It is dually licensed under the 42GNU FDL and the GNU GPL. This means that you can redistribute this 43manual under either of these two licenses, at your choice. 44 45This manual is covered by the GNU FDL. Permission is granted to copy, 46distribute and/or modify this document under the terms of the 47GNU Free Documentation License (FDL), either version 1.2 of the 48License, or (at your option) any later version published by the 49Free Software Foundation (FSF); with no Invariant Sections, with no 50Front-Cover Text, and with no Back-Cover Texts. 51A copy of the license is at @url{https://www.gnu.org/licenses/fdl.html}. 52 53This manual is covered by the GNU GPL. You can redistribute it and/or 54modify it under the terms of the GNU General Public License (GPL), either 55version 2 of the License, or (at your option) any later version published 56by the Free Software Foundation (FSF). 57A copy of the license is at @url{https://www.gnu.org/licenses/gpl.html}. 58@end copying 59@end ifinfo 60 61@titlepage 62@title GNU libtextstyle, version @value{VERSION} 63@subtitle Output of styled text 64@subtitle updated @value{UPDATED} 65@author Bruno Haible 66 67@ifnothtml 68@page 69@vskip 0pt plus 1filll 70@c @insertcopying 71Copyright (C) 2018-2019 Free Software Foundation, Inc. 72 73This manual is free documentation. It is dually licensed under the 74GNU FDL and the GNU GPL. This means that you can redistribute this 75manual under either of these two licenses, at your choice. 76 77This manual is covered by the GNU FDL. Permission is granted to copy, 78distribute and/or modify this document under the terms of the 79GNU Free Documentation License (FDL), either version 1.2 of the 80License, or (at your option) any later version published by the 81Free Software Foundation (FSF); with no Invariant Sections, with no 82Front-Cover Text, and with no Back-Cover Texts. 83A copy of the license is at @url{https://www.gnu.org/licenses/fdl.html}. 84 85This manual is covered by the GNU GPL. You can redistribute it and/or 86modify it under the terms of the GNU General Public License (GPL), either 87version 2 of the License, or (at your option) any later version published 88by the Free Software Foundation (FSF). 89A copy of the license is at @url{https://www.gnu.org/licenses/gpl.html}. 90@end ifnothtml 91@end titlepage 92 93@c Table of Contents 94@contents 95 96@ifnottex 97@node Top 98@top GNU libtextstyle 99 100This manual documents the GNU libtextstyle library, version 101@value{VERSION}. 102 103@menu 104* Introduction:: Introduction 105* The user's view:: The user's perspective 106* The programmer's view:: The programmer's perspective 107* Licenses:: 108* Function Index:: 109* Variable Index:: 110* Index:: 111@end menu 112 113@end ifnottex 114 115@node Introduction 116@chapter Introduction 117 118Text is easier to read when it is accompanied with styling information, 119such as color, font attributes (weight, posture), or underlining, and 120this styling is customized appropriately for the output device. 121 122GNU libtextstyle provides an easy way to add styling to programs that 123produce output to a console or terminal emulator window. It does this 124in a way that allows the end user to customize the styling using the 125industry standard, namely Cascading Style Sheets (CSS). 126 127@menu 128* Style definitions:: 129* Built-in versus separate styling:: 130@end menu 131 132@node Style definitions 133@section Style definitions 134 135Let's look at the traditional way styling is done for specific programs. 136 137Browsers, when they render HTML, use CSS styling. 138 139The older approach to user-customizable text styling is that the user 140associates patterns with escape sequences in an environment variable or a 141command-line argument. This is the approach used, for example, by the 142GNU @samp{ls} program in combination with the @samp{dircolors} program. 143The processing is distributed across several steps: 144@enumerate 145@item 146There is default style definition that is hard-coded in the 147@samp{dircolors} program. The user can also define their own definitions 148in a file such as @file{~/.dir_colors}. This style definition contains 149explicit terminal escape sequences; thus, it can only be used with 150consoles and terminal emulators, and each style definition applies only 151to a certain class of mostly-compatible terminal emulators. 152@item 153The @command{dircolors} program, when invoked, translates such a style 154definition to a sequence of shell statements that sets an environment 155variable @code{LS_COLORS}. 156@item 157The shell executes these statements, and thus sets the environment 158variable @code{LS_COLORS}. 159@item 160The program looks at the environment variable and emits the listed escape 161sequences. 162@end enumerate 163 164In contrast, this library implements styling as follows: 165@enumerate 166@item 167There is a default style definition in a CSS file that is part of the 168same package as the stylable program. The user can also define their own 169definitions in a CSS file, and set an environment environment variable to 170point to it. 171@item 172The program looks at the environment variable, parses the CSS file, 173translates the styling specifications to the form that is appropriate for 174the output device (escape sequences for terminal emulators, inline CSS 175and @code{<span>} elements for HTML output), and emits it. 176@end enumerate 177 178Thus, with GNU libtextstyle, the styling has the following properties: 179@itemize @bullet 180@item 181It is easier for the user to define their own styling, because the file 182format is standardized and supported by numerous syntax aware editors. 183@item 184A styling file does not depend on the particular output device. An HTML 185output and a black-on-white terminal emulator can use the same styling 186file. A white-on-black (or even green-on-black) terminal emulator will 187need different styling, though. 188@item 189It is simpler: There is no need for a program that converts the style 190specification from one format to another. 191@end itemize 192 193@node Built-in versus separate styling 194@section Built-in versus separate styling 195 196There are generally two approaches for adding styling to text: 197@itemize @bullet 198@item 199The program that generates the text adds the styling. It does so through 200interleaved statements that turn on or off specific attributes. 201@item 202The styling gets added by a separate program, that postprocesses the 203output. This separate program usually uses regular expressions to 204determine which text regions to style with a certain set of text 205attributes. 206@end itemize 207 208The first approach produces a styling that is 100% correct, regardless of 209the complexity of the text that is being output. This is the preferred 210approach for example for JSON, XML, or programming language text. 211 212The second approach works well if the output has a simple, easy-to-parse 213format. It may produce wrong styling in some cases when the text format 214is more complex. This approach is often used for viewing log files. 215 216GNU libtextstyle supports both approaches; it includes an example program 217for each of the two approaches. 218 219@node The user's view 220@chapter The end user's perspective 221 222Styled output can viewed fine in a console or terminal emulator window. 223 224The stylable program will typically have the following options: 225@table @code 226@item --color 227Use colors and other text attributes always. 228@item --color=@var{when} 229Use colors and other text attributes if @var{when}. @var{when} may be 230@code{always}, @code{never}, @code{auto}, or @code{html}. 231@item --style=@var{style-file} 232Specify the CSS style rule file for @code{--color}. 233@end table 234 235For more details, see the sections @ref{The --color option} and 236@ref{The --style option} below. 237 238If the output does not fit on a screen, you can use @samp{less -R} to 239scroll around in the styled output. For example: 240@smallexample 241@var{program} --color @var{arguments} | less -R 242@end smallexample 243 244@menu 245* The TERM variable:: 246* The NO_COLOR variable:: 247* The NO_TERM_HYPERLINKS variable:: 248* Emacs:: 249* The --color option:: 250* The --style option:: 251@end menu 252 253@node The TERM variable 254@section The environment variable @code{TERM} 255 256@vindex TERM@r{, environment variable} 257The environment variable @code{TERM} contains a identifier for the text 258window's capabilities. You can get a detailed list of these cababilities 259by using the @samp{infocmp} command (for example: @code{infocmp -L1 xterm}), 260using @samp{man 5 terminfo} as a reference. 261 262When producing text with embedded color directives, a 263@code{libtextstyle}-enabled program looks at the @code{TERM} variable. 264Text windows today typically support at least 8 colors. Often, however, 265the text window supports 16 or more colors, even though the @code{TERM} 266variable is set to a identifier denoting only 8 supported colors. It 267can be worth setting the @code{TERM} variable to a different value in 268these cases. 269 270After setting @code{TERM}, you can verify how well it works by invoking 271@samp{@var{program} --color=test}, where @code{@var{program}} is any 272@code{libtextstyle}-enabled program, and seeing whether the output looks 273like a reasonable color map. 274 275@menu 276* Terminal emulators:: 277* Consoles:: 278@end menu 279 280@node Terminal emulators 281@subsection Terminal emulator programs 282 283The following terminal emulator programs support 256 colors and set 284@code{TERM=xterm-256color} accordingly: 285 286@itemize @bullet 287@item 288In GNOME: @code{gnome-terminal}, @code{tilda}. 289@item 290@code{rxvt-unicode} (sets @code{TERM=rxvt-unicode-256color}). 291@item 292@code{st} (sets @code{TERM=st-256color}). 293@item 294@code{QTerminal}. 295@item 296On macOS: @code{Terminal}, @code{iTerm2}. 297@end itemize 298 299The following terminal emulator programs support 256 colors. You only 300need to set @code{TERM=xterm-256color} or similar; the programs by default 301set @code{TERM} to a value that supports only 8 colors. 302 303@itemize @bullet 304@item 305@code{xterm} is in many cases built with support for 256 colors. But it 306sets @code{TERM=xterm}. You need to set @code{TERM=xterm-256color}. 307@item 308In GNOME: @code{guake} (sets @code{TERM=xterm}). You need to set 309@code{TERM=xterm-256color}. 310@item 311In KDE: @code{konsole} (sets @code{TERM=xterm}). You need to set 312@code{TERM=xterm-256color} or @code{TERM=konsole-256color}. 313@item 314In KDE: @code{yakuake} (sets @code{TERM=xterm}). You need to set 315@code{TERM=xterm-256color}. 316@item 317In Enlightenment: @code{Eterm} (sets @code{TERM=Eterm}). You need to set 318@code{TERM=Eterm-256color}. 319@item 320@code{mlterm} (sets @code{TERM=mlterm}). You need to set 321@code{TERM=mlterm-256color}. 322@item 323On Windows: @code{PuTTY} (sets @code{TERM=xterm}). You need to set 324@code{TERM=xterm-256color} or @code{TERM=putty-256color}. 325@item 326On Windows: @code{TeraTerm} (sets @code{TERM=xterm}). You need to set 327@code{TERM=xterm-256color}. 328@end itemize 329 330A couple of terminal emulator programs support even the entire RGB color 331space (16 million colors). To get this to work, at this date (2019), you 332need three things: 333@itemize @bullet 334@item 335The @code{ncurses} library version 6.1 or newer must be installed. 336@item 337You need a recent version of the respective terminal emulator program. 338See @url{https://gist.github.com/XVilka/8346728} for the most recent 339developments in this area. 340@item 341You need to set the @code{TERM} environment variable to the corresponding 342value: 343@code{TERM=xterm-direct} instead of 344@code{TERM=xterm} or @code{TERM=xterm-256color}, 345@code{TERM=konsole-direct} in @code{konsole}, 346@code{TERM=st-direct} in @code{st}, 347@code{TERM=mlterm-direct} in @code{mlterm}, 348or @code{TERM=iterm2-direct} in @code{iTerm2} on macOS. 349@end itemize 350 351@node Consoles 352@subsection Consoles 353 354On OpenBSD 6 consoles, @code{TERM=xterm} produces better results than the 355default @code{TERM=vt220}. 356 357On NetBSD 8 consoles, @code{TERM=netbsd6} produces better results than the 358default @code{TERM=vt100}. 359 360On Windows consoles, no @code{TERM} setting is needed. 361 362@node The NO_COLOR variable 363@section The environment variable @code{NO_COLOR} 364 365@vindex NO_COLOR@r{, environment variable} 366@c The name of this environment variable is specified by https://no-color.org/. 367The environment variable @code{NO_COLOR} can be used to suppress styling 368in the textual output. When this environment variable is set (to any value), 369@code{libtextstyle}-enabled programs will not emit colors and other text 370styling. 371 372This environment variable can be overridden by passing the command-line option 373@samp{--color=always} (see @ref{The --color option}). 374 375@node The NO_TERM_HYPERLINKS variable 376@section The environment variable @code{NO_TERM_HYPERLINKS} 377 378@vindex NO_TERM_HYPERLINKS@r{, environment variable} 379The environment variable @code{NO_TERM_HYPERLINKS} can be used to suppress 380hyperlinks in the textual output. When this environment variable is set 381(to any value), @code{libtextstyle}-enabled programs will not emit 382hyperlinks. This may be useful for terminal emulators which produce 383garbage output when they receive the escape sequence for a hyperlink. 384Currently (as of 2019), this affects some versions of 385@c https://qa.debian.org/popcon.php 386@code{konsole}, @c 11% 387@code{emacs}, @c 7% 388@code{lxterminal}, @c 6% 389@code{guake}, @c 1.3% 390@code{yakuake}, @c 1.1% 391@code{rxvt}. @c 0.9% 392 393@node Emacs 394@section Emacs as a terminal emulator 395 396Emacs has several terminal emulators: @code{M-x shell} and 397@code{M-x term}. @code{M-x term} has good support for styling, whereas 398in @code{M-x shell} most of the styling gets lost. 399 400@node The --color option 401@section The @code{--color} option 402 403@cindex @code{--color} option 404The @samp{--color=@var{when}} option specifies under which conditions 405styled (colorized) output should be generated. The @var{when} part can 406be one of the following: 407 408@table @code 409@item always 410@itemx yes 411The output will be colorized. 412 413@item never 414@itemx no 415The output will not be colorized. 416 417@item auto 418@itemx tty 419The output will be colorized if the output device is a tty, i.e.@: when 420the output goes directly to a text screen or terminal emulator window. 421 422@item html 423The output will be colorized and be in HTML format. This value is only 424supported by some programs. 425 426@item test 427This is a special value, understood only by some programs. It is 428explained in the section (@ref{The TERM variable}) above. 429@end table 430 431@noindent 432@samp{--color} is equivalent to @samp{--color=yes}. The default is 433@samp{--color=auto}. 434 435Thus, a command that invokes a @code{libtextstyle}-enabled program will 436produce colorized output when called by itself in a command window. 437Whereas in a pipe, such as @samp{@var{program} @var{arguments} | less -R}, 438it will not produce colorized output. To get colorized output in this 439situation nevertheless, use the command 440@samp{@var{program} --color @var{arguments} | less -R}. 441 442The @samp{--color=html} option will produce output that can be viewed in 443a browser. This can be useful, for example, for Indic languages, 444because the renderic of Indic scripts in browsers is usually better than 445in terminal emulators. 446 447Note that the output produced with the @code{--color} option is 448@emph{not} consumable by programs that expect the raw text. It contains 449additional terminal-specific escape sequences or HTML tags. For example, 450an XML parser will give a syntax error when confronted with a colored XML 451output. Except for the @samp{--color=html} case, you therefore normally 452don't need to save output produced with the @code{--color} option in a 453file. 454 455@node The --style option 456@section The @code{--style} option 457 458@cindex @code{--style} option 459The @samp{--style=@var{style_file}} option specifies the style file to 460use when colorizing. It has an effect only when the @code{--color} 461option is effective. 462 463If the @code{--style} option is not specified, the program may consider 464the value of an environment variable. It is meant to point to the user's 465preferred style for such output. The name of such an environment 466variable, if supported, is documented in the documentation of the 467@code{libtextstyle}-enabled program. 468 469You can also design your own styles. This is described in the next 470section. 471 472@menu 473* Style rules:: How to create a style file 474* Debugging style files:: How to debug a style file 475@end menu 476 477@node Style rules 478@subsection Creating your own style files 479 480The same style file can be used for styling a certain type of output, for 481terminal output and for HTML output. It is written in CSS 482(Cascading Style Sheet) syntax. See 483@url{https://www.w3.org/TR/css2/cover.html} for a formal definition of 484CSS. Many HTML authoring tutorials also contain explanations of CSS. 485 486In the case of HTML output, the style file is embedded in the HTML output. 487In the case of text output, the style file is interpreted by the 488@code{libtextstyle}-enabled program. 489 490You should avoid @code{@@import} statements, because 491@itemize @minus 492@item 493In the case of HTML output, the files referenced by the @code{@@import} 494statements would not be embedded in the HTML output. In fact, relative 495file names would be interpreted relative to the resulting HTML file. 496@item 497In the case of text output, @code{@@import}s are not supported, due to a 498limitation in @code{libcroco}. 499@end itemize 500 501CSS rules are built up from selectors and declarations. The declarations 502specify graphical properties; the selectors specify when they apply. 503 504GNU libtextstyle supports simple selectors based on "CSS classes", see 505the CSS2 spec, section 5.8.3. The set of CSS classes that are supported 506by a @code{libtextstyle}-enabled program are documented in the 507documentation of that program. 508 509These selectors can be combined to hierarchical selectors. For example, 510assume a program supports the CSS classes @code{string} (that matches a 511string) and @code{non-ascii} (that matches a word with non-ASCII 512characters), you could write 513 514@smallexample 515.string .non-ascii @{ color: red; @} 516@end smallexample 517 518@noindent 519to highlight only the non-ASCII words inside strings. 520 521In text mode, pseudo-classes (CSS2 spec, section 5.11) and 522pseudo-elements (CSS2 spec, section 5.12) are not supported. 523 524The declarations in HTML mode are not limited; any graphical attribute 525supported by the browsers can be used. 526 527The declarations in text mode are limited to the following properties. 528Other properties will be silently ignored. 529 530@table @asis 531@item @code{color} (CSS2 spec, section 14.1) 532@itemx @code{background-color} (CSS2 spec, section 14.2.1) 533These properties are supported. Colors will be adjusted to match the 534terminal's capabilities. Note that many terminals support only 8 colors. 535 536@item @code{font-weight} (CSS2 spec, section 15.2.3) 537This property is supported, but most terminals can only render two 538different weights: @code{normal} and @code{bold}. Values >= 600 are 539rendered as @code{bold}. 540 541@item @code{font-style} (CSS2 spec, section 15.2.3) 542This property is supported. The values @code{italic} and @code{oblique} 543are rendered the same way. 544 545@item @code{text-decoration} (CSS2 spec, section 16.3.1) 546This property is supported, limited to the values @code{none} and 547@code{underline}. 548@end table 549 550@node Debugging style files 551@subsection Debugging style files 552 553@cindex Debugging 554If you want to understand why the style rules in a style file produce 555the output that you see, you can do so in three steps: 556 557@enumerate 558@item 559Run the program with the command-line option @code{--color=html}, 560redirecting the output to a file. 561@item 562Open the resulting HTML file in a browser. 563@item 564Use the browser's built-in CSS debugging tool. 565@itemize @bullet 566@item 567In Firefox: From the pop-up menu, select "Inspect Element". 568Click somewhere in the DOM tree ("Inspector" tab) and look at the 569CSS declarations in the "Rules" tab. 570@item 571In Chromium: From the pop-up menu, select "Inspect". 572Click somewhere in the DOM tree ("Elements" tab) and look at the 573CSS declarations in the "Styles" tab. 574@end itemize 575@end enumerate 576 577This technique allows you, in particular, to see which CSS declarations 578override which other CSS declarations from other CSS rules. 579 580@node The programmer's view 581@chapter The programmer's perspective 582 583As a programmer, enabling styling consists of the following tasks: 584@enumerate 585@item 586Define the command-line options and environment variable that the user 587can use to control the styling. 588@item 589Define the CSS classes that the user can use in the CSS file. Each CSS 590class corresponds to a text role; each CSS class can be given a different 591styling by the user. 592@item 593Change the output routines so that they take an @samp{ostream_t} object 594as argument instead of a @samp{FILE *}. 595@item 596Insert paired invocations to @code{styled_ostream_begin_css_class}, 597@code{styled_ostream_end_css_class} around each run of text with a 598specific text role. 599@item 600Link with @code{libtextstyle}. If your package is using GNU autoconf, 601you can use the @code{libtextstyle.m4} macro from Gnulib. 602@item 603Prepare a default style file. 604@item 605Update the documentation of your package. 606@end enumerate 607 608The following sections go into more detail. 609 610@menu 611* Basic use:: 612* Include files:: 613* Link options:: 614* Command-line options:: 615* The output stream hierarchy:: 616* Debugging the styling code:: 617* What to document:: 618@end menu 619 620@node Basic use 621@section Basic use of libtextstyle 622 623Source code that makes use of GNU libtextstyle needs an include statement: 624 625@smallexample 626#include <textstyle.h> 627@end smallexample 628 629Basic use of GNU libtextstyle consists of statements like these: 630 631@smallexample 632 styled_ostream_t stream = 633 styled_ostream_create (STDOUT_FILENO, "(stdout)", TTYCTL_AUTO, 634 style_file_name); 635 ... 636 styled_ostream_begin_use_class (stream, css_class); 637 ... 638 ostream_write_str (stream, string); 639 ... 640 styled_ostream_end_use_class (stream, css_class); 641 ... 642 styled_ostream_free (stream); 643@end smallexample 644 645Before this snippet, your code needs to determine the name of the style 646file to use (@code{style_file_name}). If no styling is desired -- the 647precise condition depends on the value of @code{color_mode} but also on 648your application logic --, you should set @code{style_file_name} to 649@code{NULL}. 650 651An object of type @code{styled_ostream_t} is allocated. The function 652@code{styled_ostream_create} allocates it; the function 653@code{styled_ostream_free} deallocates it. 654 655Such @code{styled_ostream_t} supports output operations 656(@code{ostream_write_str}), interleaved with adding and removing CSS 657classes. The CSS class in effect when an output operation is performed 658determines, through the style file, the text attributes associated with 659that piece of text. 660 661@menu 662* Hyperlinks:: 663@end menu 664 665@node Hyperlinks 666@subsection Hyperlinks 667 668Text output may contain hyperlinks. These hyperlinks are encoded through 669an escape sequence, specified at 670@url{https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda, 671Hyperlinks in terminal emulators}. Currently (as of 2019), they are 672displayed only in @code{gnome-terminal} version 3.26 or above. More 673terminal emulators will support hyperlinks in the future. Terminal 674emulators which don't support hyperlinks ignore it, except for a few 675terminal emulators, for which users may need to disable the hyperlinks 676(see @ref{The NO_TERM_HYPERLINKS variable}) if the heuristic built into 677@code{libtextstyle} does not already disable them. 678 679To emit a hyperlink, use code like this: 680 681@smallexample 682 styled_ostream_t stream = ... 683 ... 684 /* Start a hyperlink. */ 685 styled_ostream_set_hyperlink (stream, url, NULL); 686 ... 687 /* Emit the anchor text. This can be styled text. */ 688 ostream_write_str (stream, "Click here!"); 689 ... 690 /* End the current hyperlink. */ 691 styled_ostream_set_hyperlink (stream, NULL, NULL); 692@end smallexample 693 694The anchor text can be styled. But the hyperlinks themselves cannot be 695styled; they behave as implemented by the terminal emulator. 696 697@node Include files 698@section Include files 699 700@cindex Include file 701@cindex @code{<textstyle.h>} 702The include file @code{<textstyle.h>} declares all facilities defined by 703the library. 704 705@node Link options 706@section Link options 707 708The library to link with is called @code{libtextstyle}, with a 709system-dependent suffix. You link with it though link options of the 710form @code{-ltextstyle} for a library installed in system locations, or 711@code{-L@var{libdir} -ltextstyle} for a static library installed in other 712locations, or @code{-L@var{libdir} -ltextstyle -Wl,-rpath,@var{libdir}} 713for a shared library installed in other locations (assuming a GCC 714compatible compiler and linker and no @code{libtool}), or 715@code{-L@var{libdir} -ltextstyle -R@var{libdir}} for a shared library 716installed in other locations (with @code{libtool}). Additionally, the 717link options may need to include the dependencies: @code{-lm}, and 718@code{-lncurses} or (on NetBSD) @code{-ltermcap} or (on AIX) 719@code{-lxcurses} or (on HP-UX) @code{-lcurses}, and on some systems also 720@code{-liconv}. 721 722It is a bit complicated to determine the right link options in a portable 723way. Therefore an Autoconf macro is provided in the file 724@code{libtextstyle.m4} in Gnulib, that makes this task easier. Assuming 725the build system of your package is based on GNU Autoconf, you invoke it 726through @code{gl_LIBTEXTSTYLE}. It searches for an installed 727@code{libtextstyle}. If found, it sets and AC_SUBSTs 728@code{HAVE_LIBTEXTSTYLE=yes} and the @code{LIBTEXTSTYLE} and 729@code{LTLIBTEXTSTYLE} variables, and augments the @code{CPPFLAGS} 730variable, and #defines @code{HAVE_LIBTEXTSTYLE} to 1. Otherwise, it sets 731and AC_SUBSTs @code{HAVE_LIBTEXTSTYLE=no} and @code{LIBTEXTSTYLE} and 732@code{LTLIBTEXTSTYLE} to empty. In link commands that use @code{libtool}, 733use @code{LTLIBTEXTSTYLE}; in link commands that don't use @code{libtool}, 734use @code{LIBTEXTSTYLE}. 735 736If you use GNU Automake, the proper place to use the link options is 737@code{@var{program}_LDADD} for programs and @code{@var{library}_LIBADD} 738for libraries. 739 740@node Command-line options 741@section Command-line options 742 743While you are free to provide any command-line option to enable the 744styling of the output, it is good if different GNU programs use the same 745command-line options for this purpose. These options are described in 746the sections @ref{The --color option} and @ref{The --style option}. To 747achieve this, use the following API (declared in @code{<textstyle.h>}): 748 749@deftypevr Variable bool color_test_mode 750True if a @code{--color} option with value @code{test} has been seen. 751@end deftypevr 752 753@deftypevr Variable {enum@tie{}color_option} color_mode 754Stores the value of the @code{--color} option. 755@end deftypevr 756 757@deftypevr Variable {const@tie{}char@tie{}*} style_file_name 758Stores the value of the @code{--style} option. 759@end deftypevr 760 761Note: These variables, like any variables exported from shared libraries, 762can only be used in executable code. You @emph{cannot} portably use 763their address in initializers of global or static variables. This is a 764restriction that is imposed by the Windows, Cygwin, and Android platforms. 765 766@deftypefn Function bool handle_color_option (const@tie{}char@tie{}*@var{option}) 767You invoke this function when, during argument parsing, you have 768encountered a @code{--color} or @code{--color=...} option. The return 769value is an error indicator: @code{true} means an invalid option. 770@end deftypefn 771 772@deftypefn Function void handle_style_option (const@tie{}char@tie{}*@var{option}) 773You invoke this function when, during argument parsing, you have 774encountered a @code{--style} or @code{--style=...} option. 775@end deftypefn 776 777@deftypefn Function void print_color_test (void) 778Prints a color test page. You invoke this function after argument 779parsing, when the @code{color_test_mode} variable is true. 780@end deftypefn 781 782@deftypefn Function void style_file_prepare (const@tie{}char@tie{}*@var{style_file_envvar}, const@tie{}char@tie{}*@var{stylesdir_envvar}, const@tie{}char@tie{}*@var{stylesdir_after_install}, const@tie{}char@tie{}*@var{default_style_file}) 783Assigns a default value to @code{style_file_name} if necessary. You 784invoke this function after argument parsing, when @code{color_test_mode} 785is false. 786 787@code{@var{style_file_envvar}} is an environment variable that, when set 788to a non-empty value, specifies the style file to use. This environment 789variable is meant to be set by the user. 790 791@code{@var{stylesdir_envvar}} is an environment variable that, when set 792to a non-empty value, specifies the directory with the style files, or 793@code{NULL}. This is necessary for running the testsuite before 794@samp{make install}. 795 796@code{@var{stylesdir_after_install}} is the directory with the style 797files after @samp{make install}. 798 799@code{@var{default_style_file}} is the file name of the default style 800file, relative to @var{stylesdir}. 801@end deftypefn 802 803@node The output stream hierarchy 804@section The output stream hierarchy 805 806There are various classes of output streams, some of them with styling 807support. These ``classes'' are defined in an object-oriented programming 808style that resembles C++ or Java, but are actually implemented in C with 809a little bit of object orientation syntax. These definitions are 810preprocessed down to C. As a consequence, GNU libtextstyle is a C 811library and does not need to link with the C++ standard library. 812 813All these classes are declared in @code{<textstyle.h>}. 814 815The base output stream type is @samp{ostream_t}. It is a pointer type to 816a (hidden) implementation type. Similarly for the subclasses. 817 818When we say that @samp{some_ostream_t} is a subclass of @samp{ostream_t}, 819what we mean is: 820@itemize @bullet 821@item 822Every @samp{some_ostream_t} object can be converted to an 823@samp{ostream_t}, by virtue of a simple assignment. No cast is needed. 824@item 825The opposite conversion, from @samp{ostream_t} to @samp{some_ostream_t}, 826can also be performed, provided that the object is actually an instance 827of @samp{some_ostream_t}. 828@item 829Every method @samp{ostream_@var{foobar}} exists also as a method 830@samp{some_ostream_@var{foobar}} with compatible argument types and a 831compatible return type. 832@end itemize 833 834@menu 835* The ostream class:: 836* The styled_ostream class:: 837* ostream subclasses without styling:: 838* styled_ostream subclasses:: 839@end menu 840 841@node The ostream class 842@subsection The abstract @code{ostream} class 843 844The base output stream type is @samp{ostream_t}. 845 846It has the following methods: 847 848@deftypefn Function void ostream_write_mem (ostream_t@tie{}@var{stream}, const@tie{}void@tie{}*@var{data}, size_t@tie{}@var{len}) 849Writes a sequence of bytes to a stream. 850@end deftypefn 851 852@deftypefn Function void ostream_write_str (ostream_t@tie{}@var{stream}, const@tie{}char@tie{}*@var{string}) 853Writes a string's contents to a stream. 854@end deftypefn 855 856@deftypefn Function ptrdiff_t ostream_printf (ostream_t@tie{}@var{stream}, const@tie{}char@tie{}*@var{format}, ...) 857@deftypefnx Function ptrdiff_t ostream_vprintf (ostream_t@tie{}@var{stream}, const@tie{}char@tie{}*@var{format}, va_list args) 858Writes formatted output to a stream. 859 860These functions return the size of formatted output, or a negative value 861in case of an error. 862@end deftypefn 863 864@deftypefn Function void ostream_flush (ostream_t@tie{}@var{stream}, ostream_flush_scope_t@tie{}@var{scope}) 865Brings buffered data to its destination. 866@end deftypefn 867 868@deftypefn Function void ostream_free (ostream_t@tie{}@var{stream}) 869Closes and frees a stream. 870@end deftypefn 871 872@node The styled_ostream class 873@subsection The abstract @code{styled_ostream} class 874 875The type for a styled output stream is @samp{styled_ostream_t}. It is a 876subclass of @samp{ostream_t} that adds the following methods: 877 878@deftypefn Function void styled_ostream_begin_use_class (styled_ostream_t@tie{}@var{stream}, const@tie{}char@tie{}*@var{classname}) 879Starts a run of text belonging to @code{@var{classname}}. The 880@code{@var{classname}} is the name of a CSS class. It can be chosen 881arbitrarily and customized through the CSS file. 882@end deftypefn 883 884@deftypefn Function void styled_ostream_end_use_class (styled_ostream_t@tie{}@var{stream}, const@tie{}char@tie{}*@var{classname}) 885Ends a run of text belonging to @code{@var{classname}}. The 886@code{styled_ostream_begin_use_class} / 887@code{styled_ostream_end_use_class} calls must match properly. 888@end deftypefn 889 890@deftypefn Function {const char *} styled_ostream_get_hyperlink_ref (styled_ostream_t@tie{}@var{stream}) 891Returns the referred URL of the currently set hyperlink, or @code{NULL} 892if no hyperlink attribute is currently set. 893 894Note: The returned string is only valid up to the next invocation of 895@code{styled_ostream_set_hyperlink}. 896@end deftypefn 897 898@deftypefn Function {const char *} styled_ostream_get_hyperlink_id (styled_ostream_t@tie{}@var{stream}) 899Returns the id of the currently set hyperlink, or @code{NULL} if no 900hyperlink attribute is currently set. 901 902Note: The returned string is only valid up to the next invocation of 903@code{styled_ostream_set_hyperlink}. 904@end deftypefn 905 906@deftypefn Function void styled_ostream_set_hyperlink (styled_ostream_t@tie{}@var{stream}, const@tie{}char@tie{}*@var{ref}, const@tie{}char@tie{}*@var{id}) 907Sets or removes a hyperlink attribute. 908 909To set a hyperlink attribute, pass a non-@code{NULL} @var{ref}. 910@var{ref} is an URL; it should be at most 2083 bytes long. Non-ASCII 911characters should be URI-escaped (using the %nn syntax). @var{id} is 912an optional identifier. On terminal output, multiple hyperlinks with 913the same @var{id} will be highlighted together. If specified, @var{id} 914should be at most 250 bytes long. 915 916To remove a hyperlink attribute, pass @code{NULL} for @var{ref} and @var{id}. 917 918Hyperlinks don't nest. That is, a hyperlink attribute is enabled only 919up to the next invocation of @code{styled_ostream_set_hyperlink}. 920@end deftypefn 921 922@deftypefn Function void styled_ostream_flush_to_current_style (styled_ostream_t@tie{}@var{stream}) 923This function acts like @code{ostream_flush (@var{stream}, FLUSH_THIS_STREAM)}, 924except that it leaves the destination with the current text style enabled, 925instead of with the default text style. 926 927After calling this function, you can output strings without newlines(!) to the 928underlying stream, and they will be rendered like strings passed to 929@code{ostream_write_mem}, @code{ostream_write_str}, or @code{ostream_printf}. 930@end deftypefn 931 932@node ostream subclasses without styling 933@subsection Concrete ostream subclasses without styling 934 935@menu 936* The file_ostream class:: Output to a FILE stream. 937* The fd_ostream class:: Output to a file descriptor. 938* The term_ostream class:: Output to a terminal. 939* The html_ostream class:: Output to an HTML file. 940* The memory_ostream class:: Output to a memory buffer, 941* The iconv_ostream class:: Output with character encoding conversion. 942@end menu 943 944@node The file_ostream class 945@subsubsection The @code{file_ostream} class 946 947The @code{file_ostream} class supports output to an @code{<stdio.h>} 948@code{FILE} stream. Its type is @samp{file_ostream_t}. It is a subclass 949of @samp{ostream_t} that adds no methods. 950 951It can be instantiated through this function: 952 953@deftypefn Function file_ostream_t file_ostream_create (FILE@tie{}*@var{fp}) 954Creates an output stream referring to @code{@var{fp}}. 955 956Note: The resulting stream must be closed before @code{@var{fp}} can be 957closed. 958@end deftypefn 959 960@node The fd_ostream class 961@subsubsection The @code{fd_ostream} class 962 963The @code{file_ostream} class supports output to a file descriptor. Its 964type is @samp{fd_ostream_t}. It is a subclass of @samp{ostream_t} that 965adds no methods. 966 967It can be instantiated through this function: 968 969@deftypefn Function fd_ostream_t fd_ostream_create (int@tie{}@var{fd}, const@tie{}char@tie{}*@var{filename}, bool@tie{}@var{buffered}) 970Creates an output stream referring to the file descriptor @code{@var{fd}}. 971 972@code{@var{filename}} is used only for error messages. 973 974Note: The resulting stream must be closed before @code{@var{fd}} can be 975closed. 976@end deftypefn 977 978@node The term_ostream class 979@subsubsection The @code{term_ostream} class 980 981The @code{term_ostream} class supports output to a file descriptor that 982is connected to a terminal emulator or console. Its type is 983@samp{term_ostream_t}. It is a subclass of @samp{ostream_t}. 984 985It can be instantiated through this function: 986 987@deftypefn Function term_ostream_t term_ostream_create (int@tie{}@var{fd}, const@tie{}char@tie{}*@var{filename}, ttyctl_t@tie{}@var{tty_control}) 988Creates an output stream referring to the file descriptor @code{@var{fd}}. 989 990@code{@var{filename}} is used only for error messages. 991 992@code{@var{tty_control}} specifies the amount of control to take over the 993underlying tty. 994 995The resulting stream will be line-buffered. 996 997Note: The resulting stream must be closed before @code{@var{fd}} can be 998closed. 999@end deftypefn 1000 1001The class adds the following methods: 1002 1003@deftypefn Function term_color_t term_ostream_rgb_to_color (term_ostream_t@tie{}@var{stream}, int@tie{}@var{red}, int@tie{}@var{green}, int@tie{}@var{blue}) 1004Converts an RGB value 1005(@code{@var{red}}, @code{@var{green}}, @code{@var{blue}} in [0..255]) to 1006a color, valid for this stream only. 1007@end deftypefn 1008 1009@deftypefn Function term_color_t term_ostream_get_color (term_ostream_t@tie{}@var{stream}) 1010@deftypefnx Function void term_ostream_set_color (term_ostream_t@tie{}@var{stream}, term_color_t@tie{}@var{color}) 1011Gets/sets the text color. 1012@end deftypefn 1013 1014@deftypefn Function term_color_t term_ostream_get_bgcolor (term_ostream_t@tie{}@var{stream}) 1015@deftypefnx Function void term_ostream_set_bgcolor (term_ostream_t@tie{}@var{stream}, term_color_t@tie{}@var{color}) 1016Gets/sets the background color. 1017@end deftypefn 1018 1019@deftypefn Function term_weight_t term_ostream_get_weight (term_ostream_t@tie{}@var{stream}) 1020@deftypefnx Function void term_ostream_set_weight (term_ostream_t@tie{}@var{stream}, term_weight_t@tie{}@var{weight}) 1021Gets/sets the font weight. 1022@end deftypefn 1023 1024@deftypefn Function term_posture_t term_ostream_get_posture (term_ostream_t@tie{}@var{stream}) 1025@deftypefnx Function void term_ostream_set_posture (term_ostream_t@tie{}@var{stream}, term_posture_t@tie{}@var{posture}) 1026Gets/sets the font posture. 1027@end deftypefn 1028 1029@deftypefn Function term_underline_t term_ostream_get_underline (term_ostream_t@tie{}@var{stream}) 1030@deftypefnx Function void term_ostream_set_underline (term_ostream_t@tie{}@var{stream}, term_underline_t@tie{}@var{underline}) 1031Gets/sets the text underline decoration. 1032@end deftypefn 1033 1034@deftypefn Function {const char *} term_ostream_get_hyperlink_ref (term_ostream_t@tie{}@var{stream}) 1035Returns the referred URL of the currently set hyperlink, or @code{NULL} 1036if no hyperlink attribute is currently set. 1037 1038Note: The returned string is only valid up to the next invocation of 1039@code{term_ostream_set_hyperlink}. 1040@end deftypefn 1041 1042@deftypefn Function {const char *} term_ostream_get_hyperlink_id (term_ostream_t@tie{}@var{stream}) 1043Returns the id of the currently set hyperlink, or @code{NULL} if no 1044hyperlink attribute is currently set. 1045 1046Note: The returned string is only valid up to the next invocation of 1047@code{term_ostream_set_hyperlink}. 1048@end deftypefn 1049 1050@deftypefn Function void term_ostream_set_hyperlink (term_ostream_t@tie{}@var{stream}, const@tie{}char@tie{}*@var{ref}, const@tie{}char@tie{}*@var{id}) 1051Sets or removes a hyperlink attribute. 1052 1053To set a hyperlink attribute, pass a non-@code{NULL} @var{ref}. 1054@var{ref} is an URL; it should be at most 2083 bytes long. Non-ASCII 1055characters should be URI-escaped (using the %nn syntax). @var{id} is 1056an optional identifier. Multiple hyperlinks with the same @var{id} 1057will be highlighted together. If specified, @var{id} should be at most 1058250 bytes long. 1059 1060To remove a hyperlink attribute, pass @code{NULL} for @var{ref} and @var{id}. 1061 1062Hyperlinks don't nest. That is, a hyperlink attribute is enabled only 1063up to the next invocation of @code{styled_ostream_set_hyperlink}. 1064@end deftypefn 1065 1066@deftypefn Function void term_ostream_flush_to_current_style (term_ostream_t@tie{}@var{stream}) 1067This function acts like @code{ostream_flush (@var{stream}, FLUSH_THIS_STREAM)}, 1068except that it leaves the terminal with the current text attributes enabled, 1069instead of with the default text attributes. 1070 1071After calling this function, you can output strings without newlines(!) to the 1072underlying file descriptor, and they will be rendered like strings passed to 1073@code{ostream_write_mem}, @code{ostream_write_str}, or @code{ostream_printf}. 1074@end deftypefn 1075 1076@node The html_ostream class 1077@subsubsection The @code{html_ostream} class 1078 1079The @code{html_ostream} class supports output to any destination, in HTML 1080syntax. Its type is @samp{html_ostream_t}. It is a subclass of 1081@samp{ostream_t}. 1082 1083It can be instantiated through this function: 1084 1085@deftypefn Function html_ostream_t html_ostream_create (ostream_t@tie{}@var{destination}) 1086Creates an output stream that takes input in the UTF-8 encoding and 1087writes it in HTML form on @code{@var{destination}}. 1088 1089This stream produces a sequence of lines. The caller is responsible for 1090opening the @code{<body><html>} elements before and for closing them 1091after the use of this stream. 1092 1093Note: The resulting stream must be closed before @code{@var{destination}} 1094can be closed. 1095@end deftypefn 1096 1097The class adds the following methods: 1098 1099@deftypefn Function void html_ostream_begin_span (html_ostream_t@tie{}@var{stream}, const@tie{}char@tie{}*@var{classname}) 1100Starts a @code{<span class="@var{classname}">} element. The 1101@code{@var{classname}} is the name of a CSS class. It can be chosen 1102arbitrarily and customized through the CSS file. 1103@end deftypefn 1104 1105@deftypefn Function void html_ostream_end_span (html_ostream_t@tie{}@var{stream}, const@tie{}char@tie{}*@var{classname}) 1106Ends a @code{<span class="@var{classname}">} element. 1107 1108The @code{html_ostream_begin_span} / @code{html_ostream_end_span} calls 1109must match properly. 1110@end deftypefn 1111 1112@deftypefn Function {const char *} html_ostream_get_hyperlink_ref (html_ostream_t@tie{}@var{stream}) 1113Returns the referred URL of the currently set hyperlink, or @code{NULL} 1114if no hyperlink attribute is currently set. 1115 1116Note: The returned string is only valid up to the next invocation of 1117@code{html_ostream_set_hyperlink_ref}. 1118@end deftypefn 1119 1120@deftypefn Function void html_ostream_set_hyperlink_ref (html_ostream_t@tie{}@var{stream}, const@tie{}char@tie{}*@var{ref}) 1121Sets or removes a hyperlink attribute. 1122 1123To set a hyperlink attribute, pass a non-@code{NULL} @var{ref}. 1124@var{ref} is an URL; it should be at most 2083 bytes long. Non-ASCII 1125characters should be URI-escaped (using the %nn syntax). 1126 1127To remove a hyperlink attribute, pass @code{NULL} for @var{ref}. 1128 1129Hyperlinks don't nest. That is, a hyperlink attribute is enabled only 1130up to the next invocation of @code{html_ostream_set_hyperlink_ref}. 1131@end deftypefn 1132 1133@deftypefn Function void html_ostream_flush_to_current_style (html_ostream_t@tie{}@var{stream}) 1134This function acts like @code{ostream_flush (@var{stream}, FLUSH_THIS_STREAM)}, 1135except that it leaves the destination with the current text style enabled, 1136instead of with the default text style. 1137 1138After calling this function, you can output strings without newlines(!) to the 1139underlying stream, and they will be rendered like strings passed to 1140@code{ostream_write_mem}, @code{ostream_write_str}, or @code{ostream_printf}. 1141@end deftypefn 1142 1143@node The memory_ostream class 1144@subsubsection The @code{memory_ostream} class 1145 1146The @code{memory_ostream} class supports output to an in-memory buffer. 1147Its type is @samp{memory_ostream_t}. It is a subclass of 1148@samp{ostream_t}. 1149 1150It can be instantiated through this function: 1151 1152@deftypefn Function memory_ostream_t memory_ostream_create (void) 1153Creates an output stream that accumulates the output in a memory buffer. 1154@end deftypefn 1155 1156The class adds the following method: 1157 1158@deftypefn Function void memory_ostream_contents (memory_ostream_t@tie{}@var{stream}, const@tie{}void@tie{}**@var{bufp}, size_t@tie{}*@var{buflenp}) 1159Returns a pointer to the output accumulated so far and its size. It 1160stores them in @code{*@var{bufp}} and @code{*@var{buflenp}}, respectively. 1161 1162Note: These two return values become invalid when more output is done to 1163the stream or when the stream is freed. 1164@end deftypefn 1165 1166@node The iconv_ostream class 1167@subsubsection The @code{iconv_ostream} class 1168 1169The @code{iconv_ostream} class supports output to any destination. Its 1170type is @samp{iconv_ostream_t}. It is a subclass of @samp{ostream_t} 1171that adds no methods. 1172 1173It can be instantiated through this function: 1174 1175@deftypefn Function iconv_ostream_t iconv_ostream_create (const@tie{}char@tie{}*@var{from_encoding}, const@tie{}char@tie{}*@var{to_encoding}, ostream_t@tie{}@var{destination}) 1176Creates an output stream that converts from @code{@var{from_encoding}} to 1177@code{@var{to_encoding}}, writing the result to @code{@var{destination}}. 1178 1179Note: The resulting stream must be closed before @code{@var{destination}} 1180can be closed. 1181@end deftypefn 1182 1183@node styled_ostream subclasses 1184@subsection Concrete @code{styled_ostream} subclasses 1185 1186@menu 1187* The term_styled_ostream class:: Styled output to a terminal. 1188* The html_styled_ostream class:: Styled output to an HTML file. 1189* The noop_styled_ostream class:: No-op styling. 1190@end menu 1191 1192@node The term_styled_ostream class 1193@subsubsection The @code{term_styled_ostream} class 1194 1195The @code{term_styled_ostream} class supports styled output to a file 1196descriptor that is connected to a terminal emulator or console. Its type 1197is @samp{term_styled_ostream_t}. It is a subclass of 1198@samp{styled_ostream_t}. 1199 1200It can be instantiated through this function: 1201 1202@deftypefn Function term_styled_ostream_t term_styled_ostream_create (int@tie{}@var{fd}, const@tie{}char@tie{}*@var{filename}, ttyctl_t@tie{}@var{tty_control}, const@tie{}char@tie{}*@var{css_filename}) 1203Creates an output stream referring to the file descriptor @code{@var{fd}}, 1204styled with the file @code{@var{css_filename}}. 1205 1206@code{@var{filename}} is used only for error messages. 1207 1208@code{@var{tty_control}} specifies the amount of control to take over the 1209underlying tty. 1210 1211Note: The resulting stream must be closed before @code{@var{fd}} can be 1212closed. 1213 1214Returns @code{NULL} upon failure. 1215@end deftypefn 1216 1217The following is a variant of this function. Upon failure, it does not 1218return @code{NULL}; instead, it returns a styled @code{fd_stream} on 1219which the styling operations exist but are no-ops. 1220 1221@deftypefn Function styled_ostream_t styled_ostream_create (int@tie{}@var{fd}, const@tie{}char@tie{}*@var{filename}, ttyctl_t@tie{}@var{tty_control}, const@tie{}char@tie{}*@var{css_filename}) 1222Creates an output stream referring to the file descriptor @code{@var{fd}}, 1223styled with the file @code{@var{css_filename}} if possible. 1224 1225@code{@var{filename}} is used only for error messages. 1226 1227@code{@var{tty_control}} specifies the amount of control to take over the 1228underlying tty. 1229 1230Note: The resulting stream must be closed before @code{@var{fd}} can be 1231closed. 1232@end deftypefn 1233 1234@node The html_styled_ostream class 1235@subsubsection The @code{html_styled_ostream} class 1236 1237The @code{html_styled_ostream} class supports styled output to any 1238destination, in HTML syntax. Its type is @samp{html_styled_ostream_t}. 1239It is a subclass of @samp{styled_ostream_t}. 1240 1241It can be instantiated through this function: 1242 1243@deftypefn Function html_styled_ostream_t html_styled_ostream_create (ostream_t@tie{}@var{destination}, const@tie{}char@tie{}*@var{css_filename}) 1244Creates an output stream that takes input in the UTF-8 encoding and 1245writes it in HTML form on @code{@var{destination}}, styled with the file 1246@code{@var{css_filename}}. 1247 1248Note: The resulting stream must be closed before @code{@var{destination}} 1249can be closed. 1250@end deftypefn 1251 1252@node The noop_styled_ostream class 1253@subsubsection The @code{noop_styled_ostream} class 1254 1255The @code{noop_styled_ostream} class supports the styled output operations 1256to any destination. The text is output to the given destination; the 1257styling operations, however, do nothing. Its type is 1258@samp{noop_styled_ostream_t}. It is a subclass of @samp{styled_ostream_t}. 1259 1260It can be instantiated through this function: 1261 1262@deftypefn Function noop_styled_ostream_t noop_styled_ostream_create (ostream_t@tie{}@var{destination}, bool@tie{}@var{pass_ownership}) 1263Creates an output stream that delegates to @code{@var{destination}} and 1264that supports the styling operations as no-ops. 1265 1266If @code{@var{pass_ownership}} is @code{true}, closing the resulting 1267stream will automatically close the @code{@var{destination}}. 1268 1269Note: If @code{@var{pass_ownership}} is @code{false}, the resulting stream 1270must be closed before @code{@var{destination}} can be closed. 1271@end deftypefn 1272 1273@node Debugging the styling code 1274@section Debugging the text styling support 1275 1276@cindex Debugging 1277If you want to understand which output of your program is associated with 1278which CSS classes, the simplest way is as follows: 1279 1280@enumerate 1281@item 1282Run the program with the command-line option @code{--color=html}, 1283redirecting the output to a file. 1284@item 1285Then inspect this output. Text regions associated with a CSS class are 1286surrounded by @code{<span class="@var{css-class}">}...@code{</span>}. 1287@end enumerate 1288 1289@node What to document 1290@section Documenting the text styling support 1291 1292To make the text styling support available to the end user of your 1293package, the following need to be documented: 1294@itemize @bullet 1295@item 1296The command-line options. This typically needs to be done in several 1297places: in the @samp{--help} output, in the @code{man} pages (if present), 1298and in the documentation. 1299@item 1300Which programs support @samp{--color=test}? 1301@item 1302The list of CSS classes and their meaning. This is necessary, so that 1303the user can create their own style file; the CSS classes are part of the 1304selectors in the CSS rules. 1305@item 1306The location of the default style file. This is a convenience, so that 1307the user, when creating their own style file, can start from the default 1308one. 1309@item 1310The environment variable, called @code{@var{style_file_envvar}} above, 1311that, when set to a non-empty value, specifies the style file to use. 1312@end itemize 1313 1314@node Licenses 1315@appendix Licenses 1316@cindex Licenses 1317 1318The files of this package are covered by the licenses indicated in each 1319particular file or directory. Here is a summary: 1320 1321@itemize @bullet 1322@item 1323The @code{libtextstyle} library and the example programs 1324are covered by the GNU General Public License (GPL). 1325A copy of the license is included in @ref{GNU GPL}. 1326 1327@item 1328This manual is free documentation. It is dually licensed under the 1329GNU FDL and the GNU GPL. This means that you can redistribute this 1330manual under either of these two licenses, at your choice. 1331@* 1332This manual is covered by the GNU FDL. Permission is granted to copy, 1333distribute and/or modify this document under the terms of the 1334GNU Free Documentation License (FDL), either version 1.2 of the 1335License, or (at your option) any later version published by the 1336Free Software Foundation (FSF); with no Invariant Sections, with no 1337Front-Cover Text, and with no Back-Cover Texts. 1338A copy of the license is included in @ref{GNU FDL}. 1339@* 1340This manual is covered by the GNU GPL. You can redistribute it and/or 1341modify it under the terms of the GNU General Public License (GPL), either 1342version 3 of the License, or (at your option) any later version published 1343by the Free Software Foundation (FSF). 1344A copy of the license is included in @ref{GNU GPL}. 1345@end itemize 1346 1347@menu 1348* GNU GPL:: GNU General Public License 1349* GNU FDL:: GNU Free Documentation License 1350@end menu 1351 1352@page 1353@node GNU GPL 1354@appendixsec GNU GENERAL PUBLIC LICENSE 1355@cindex GPL, GNU General Public License 1356@cindex License, GNU GPL 1357@include gpl.texi 1358@page 1359@node GNU FDL 1360@appendixsec GNU Free Documentation License 1361@cindex FDL, GNU Free Documentation License 1362@cindex License, GNU FDL 1363@include fdl.texi 1364 1365@node Function Index 1366@unnumbered Function Index 1367 1368@printindex fn 1369 1370@node Variable Index 1371@unnumbered Variable Index 1372 1373@printindex vr 1374 1375@node Index 1376@unnumbered General Index 1377 1378@printindex cp 1379 1380@bye 1381 1382@c Local variables: 1383@c texinfo-column-for-description: 32 1384@c End: 1385