1 /* Monolith smart text library.
2 * - by Richard W.M. Jones <rich@annexia.org>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the Free
16 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 * $Id: ml_smarttext.h,v 1.1 2002/12/08 17:29:17 rich Exp $
21 #ifndef ML_SMARTTEXT_H
22 #define ML_SMARTTEXT_H
24 #include <pthr_iolib.h>
28 /* Function: ml_plaintext_print - convert text to HTML
29 * Function: ml_plaintext_to_html
30 * Function: ml_smarttext_print
31 * Function: ml_smarttext_to_html
32 * Function: ml_filterhtml_print
33 * Function: ml_filterhtml_to_html
34 * Function: ml_anytext_print
35 * Function: ml_anytext_to_html
37 * The monolith "smart text" library is concerned with rendering
38 * plain text, smart text and filtered HTML safely in the browser.
40 * Plain text is just ordinary text, in which we escape the HTML
41 * special entities such as @code{<} and @code{>} so that the user
42 * cannot put up arbitrary HTML.
44 * Smart text is ordinary text with user-friendly markup sequences
45 * (see below) allow the user to easily make text bold, etc.
47 * Filtered HTML is a limited, safe subset of HTML.
49 * The library currently supports the following smart text
54 * - @code{mailto:} URLs are marked up with a special mail icon.
56 * - @code{*bold*}, @code{/italic/} and @code{=monospace=} text, but
57 * only around simple text, and currently you cannot combine these
58 * with other smart text markup inside the text.
60 * - Various smileys, including @code{:-)}, @code{:-(} and @code{:-P}.
62 * - @code{(C)}, @code{(R)}, @code{(TM)} are marked up as the appropriate
65 * - @code{1/4}, @code{1/2}, @code{3/4} are marked up as fractions.
67 * @code{ml_plaintext_print} converts a string @code{text} containing
68 * just plain text to HTML and writes it directly to @code{io}.
70 * @code{ml_plaintext_to_html} converts a string @code{text} containing
71 * just plain text to HTML and returns this as a new string allocated
74 * @code{ml_smarttext_print} converts a string @code{text} containing
75 * smart text to HTML and writes it directly to @code{io}.
77 * @code{ml_smarttext_to_html} converts a string @code{text} containing
78 * smart text to HTML and returns this as a new string allocated
81 * @code{ml_filterhtml_print} converts a string @code{text} containing
82 * filtered HTML to HTML and writes it directly to @code{io}.
84 * @code{ml_filterhtml_to_html} converts a string @code{text} containing
85 * filtered HTML to HTML and returns this as a new string allocated
88 * @code{ml_anytext_print} and @code{ml_anytext_to_html} can be used
89 * on either plain text, smart text or filtered HTML, depending on the
90 * value passed in the @code{type} argument, which must be one of
91 * @code{'p'}, @code{'s'} or @code{'h'}.
93 extern void ml_plaintext_print (io_handle io, const char *text);
94 extern const char *ml_plaintext_to_html (pool, const char *text);
95 extern void ml_smarttext_print (io_handle io, const char *text);
96 extern const char *ml_smarttext_to_html (pool, const char *text);
97 extern void ml_filterhtml_print (io_handle io, const char *text);
98 extern const char *ml_filterhtml_to_html (pool, const char *text);
99 extern void ml_anytext_print (io_handle io, const char *text, char type);
100 extern const char *ml_anytext_to_html (pool, const char *text, char type);
102 #endif /* ML_SMARTTEXT_H */