Text::Smart(3pm)

1Text::Smart(3)        User Contributed Perl Documentation       Text::Smart(3)
2
3
4

NAME

6       Text::Smart - Processor for 'smart text' markup
7

SYNOPSIS

9         use Text::Smart;
10
11         my $markup = Text::Smart->new(entities => \%entities);
12
13         my $text = $markup->process($text, %opts);
14
15         my $text = $markup->process_divider($text);
16         my $text = $markup->process_itemize($text, %opts);
17         my $text = $markup->process_enumeration($text, %opts);
18         my $text = $markup->process_paragraph($text, %opts);
19         my $text = $markup->process_smart($text, %opts);
20
21         # Virtual methods for subclasses to implement
22         my $text = $markup->generate_divider();
23         my $text = $markup->generate_itemize(@items);
24         my $text = $markup->generate_enumeration(@items);
25         my $text = $markup->generate_paragraph($text);
26         my $text = $markup->generate_bold($text);
27         my $text = $markup->generate_italic($text)
28         my $text = $markup->generate_monospace($text);
29         my $text = $markup->generate_link($text, $url);
30         my $text = $markup->escape($text);
31

DESCRIPTION

33       This module provides an interface for converting smarttext markup into
34       an arbitrary text based markup language, such as HTML, Latex, or Troff.
35
36   SMARTTEXT MARKUP
37       Smarttext markup can be split into two categories, block level and
38       inline. Block level elements are separated by one or more completely
39       blank lines.  Inline elements encompass one or more words within a
40       block. Valid inline markup is:
41
42         *foo* - Puts the word 'foo' in bold face
43         /foo/ - Puts the word 'foo' in italic face
44         =foo= - Puts the word 'foo' in fixed width face
45         @foo(bar) - Makes the word 'foo' a link to the url 'bar'
46
47       There are six pre-defined entities
48
49         (C) - Insert copyright symbol
50         (TM) - Insert trademark symbol
51         (R) - Insert registered symbol
52
53         1/2 - insert a fraction
54         1/4 - insert a fraction
55         3/4 - insert a fraction
56
57       There are six levels of heading available
58
59         &title(Main document heading)
60         &subtitle(Secondary document heading)
61         &section(Section heading)
62         &subsection(Secondary section heading)
63         &subsubsection(Tertiary section heading)
64         &paragraph(Paragraph heading)
65
66       There are three special blocks. Horizontal dividing bars can be formed
67       using
68
69         ---
70         ___
71
72       Numbered lists using
73
74        + item one
75        + item two
76        + item three
77
78       Bulleted lists using
79
80        * item one
81        * item two
82        * item three
83
84       Anything not fitting these forms is treated as a standard paragraph.
85
86   OPTIONS
87       All the "process_XXX" family of methods accept a number of options
88       which control which pieces of markup are permitted in the text. The
89       following options are recognised:
90
91         no_links
92         no_symbols
93         no_lists
94         no_rules
95         no_inline
96
97       To use this options pass them as a named parameter:
98
99         $markup->process($text, no_links => 1, no_lists => 1);
100
101   SUBCLASSING
102       This module provides the basic parsing routines and framework for
103       outputting text, however, it must be subclassed to generate the markup
104       language specific tags. The primary subclass is Text::Smart::HTML which
105       is used to generate HTML markup.
106

METHODS

108       The 'generate_XXX' methods are virtual and need to be implemented by
109       subclasses.
110
111       my $proc = Text::Smart->new();
112           Create a new smart text processor. This constructor would not
113           normally be called by application code, since this module must be
114           sub-classed to be useful. The primary subclass is for generating
115           HTML, Text::Smart::HTML.
116
117       my $markup = $proc->process($text)
118           Converts a piece of smart text, passed in as the parameter into the
119           target markup language of this processor. The markedup text is
120           returned
121
122       my $markup = $proc->generate_divider()
123           Called to generate a horizontal section divider. The generated text
124           must be returned in string format. This method must be implemented
125           by subclasses.
126
127       my $markup = $proc->generate_itemize(@items)
128           Called to generate an itemized list of bullet points. The (already
129           marked up) text for each item is passed as a list of parameters.
130           The generated text must be returned in string format. This method
131           must be implemented by subclasses.
132
133       my $markup = $proc->generate_enumeration(@items)
134           Called to generate an itemized list of numbered points. The
135           (already marked up) text for each item is passed as a list of
136           parameters. The generated text must be returned in string format.
137           This method must be implemented by subclasses.
138
139       my $markup = $proc->generate_paragraph($text)
140           Called to generate a paragraph of text. The (already marked up)
141           text for the body of the paragraph is passed in as the only
142           parameter. The generated text must be returned in string format.
143           This method must be implemented by subclasses.
144
145       my $markup = $proc->generate_bold($text)
146           Called to generate bold text. The plain text is passed in as the
147           parameter, and the marked up text should be returned in string
148           format. This method must be implemented by subclasses.
149
150       my $markup = $proc->generate_italic($text)
151           Called to generate italic text. The plain text is passed in as the
152           parameter, and the marked up text should be returned in string
153           format. This method must be implemented by subclasses.
154
155       my $markup = $proc->generate_monospace($text)
156           Called to generate fixed-width text. The plain text is passed in as
157           the parameter, and the marked up text should be returned in string
158           format. This method must be implemented by subclasses.
159
160       my $markup = $proc->generate_link($url, $text)
161           Called to generate a hyperlink. The destination of the link is the
162           first parameter, and the text being linked is the second parameter.
163           The marked up text must be returned in string format. This method
164           must be implemented by subclasses.
165
166       my $markup = $proc->generate_entity($name);
167           Called to generated a special named entity. There are 6 named
168           entities which need to be supported:
169
170           fraction12
171               The fraction 1/2
172
173           fraction14
174               The fraction 1/4
175
176           fraction 34
177               The fraction 3/4
178
179           copyright
180               The copyright symbol
181
182           trademark
183               The trademark symbol
184
185           registered
186               The rights registered symbol
187
188           The markup corresponding to the specified entity must be returned
189           in string format.
190
191       my $text = $proc->escape($text)
192           Called to escape any characters which have special meaning in the
193           destination markup language. For example, in HTML, this would
194           escape angle brackets and the ampersand symbol. The escaped text
195           must be returned in string format.
196

AUTHORS

198       Daniel Berrange <dan@berrange.com>
199

COPYRIGHT

201       Copyright (C) 2000-2004 Daniel P. Berrange <dan@berrange.com>
202

NAME

SYNOPSIS

DESCRIPTION

METHODS

AUTHORS

COPYRIGHT

SEE ALSO