src/ml_smarttext.h

   1 /* Monolith smart text library.
   2  * - by Richard W.M. Jones <rich@annexia.org>
   3  *
   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.
   8  *
   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.
  13  *
  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.
  17  *
  18  * $Id: ml_smarttext.h,v 1.1 2002/12/08 17:29:17 rich Exp $
  19  */
  20
  21 #ifndef ML_SMARTTEXT_H
  22 #define ML_SMARTTEXT_H
  23
  24 #include <pthr_iolib.h>
  25
  26 #include "monolith.h"
  27
  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
  36  *
  37  * The monolith "smart text" library is concerned with rendering
  38  * plain text, smart text and filtered HTML safely in the browser.
  39  *
  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.
  43  *
  44  * Smart text is ordinary text with user-friendly markup sequences
  45  * (see below) allow the user to easily make text bold, etc.
  46  *
  47  * Filtered HTML is a limited, safe subset of HTML.
  48  *
  49  * The library currently supports the following smart text
  50  * constructs:
  51  *
  52  * - URLs.
  53  *
  54  * - @code{mailto:} URLs are marked up with a special mail icon.
  55  *
  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.
  59  *
  60  * - Various smileys, including @code{:-)}, @code{:-(} and @code{:-P}.
  61  *
  62  * - @code{(C)}, @code{(R)}, @code{(TM)} are marked up as the appropriate
  63  * symbol.
  64  *
  65  * - @code{1/4}, @code{1/2}, @code{3/4} are marked up as fractions.
  66  *
  67  * @code{ml_plaintext_print} converts a string @code{text} containing
  68  * just plain text to HTML and writes it directly to @code{io}.
  69  *
  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
  72  * in @code{pool}.
  73  *
  74  * @code{ml_smarttext_print} converts a string @code{text} containing
  75  * smart text to HTML and writes it directly to @code{io}.
  76  *
  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
  79  * in @code{pool}.
  80  *
  81  * @code{ml_filterhtml_print} converts a string @code{text} containing
  82  * filtered HTML to HTML and writes it directly to @code{io}.
  83  *
  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
  86  * in @code{pool}.
  87  *
  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'}.
  92  */
  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);
 101
 102 #endif /* ML_SMARTTEXT_H */