[MKDoc-commit] [MKDoc-Text-Structured] documented Inline module

[bruno at mkdoc.demon.co.uk]

Log Message:
-----------
[MKDoc-Text-Structured] documented Inline module

Modified Files:
--------------
    MKDoc-Text-Structured:
        Changes
    MKDoc-Text-Structured/lib/MKDoc/Text/Structured:
        Inline.pm

-------------- next part --------------
Index: Changes
===================================================================
RCS file: /var/spool/cvs/MKDoc-Text-Structured/Changes,v
retrieving revision 1.24
retrieving revision 1.25
diff -LChanges -LChanges -u -r1.24 -r1.25
--- Changes
+++ Changes
@@ -4,6 +4,7 @@
     - fix for <pre> indenting bug when first line is more indented than second
     - method to insert spaces into long words
     - strip mailto: when linking and displaying email addresses
+    - documented MKDoc::Text::Structured::Inline
 
 0.82 Thu Mar 31 13:45:00 2005
     - fixed failure to change " to &quot; bug
Index: Inline.pm
===================================================================
RCS file: /var/spool/cvs/MKDoc-Text-Structured/lib/MKDoc/Text/Structured/Inline.pm,v
retrieving revision 1.13
retrieving revision 1.14
diff -Llib/MKDoc/Text/Structured/Inline.pm -Llib/MKDoc/Text/Structured/Inline.pm -u -r1.13 -r1.14
--- lib/MKDoc/Text/Structured/Inline.pm
+++ lib/MKDoc/Text/Structured/Inline.pm
@@ -7,6 +7,40 @@
 
 our $LongestWord = 78;
 
+=head1 NAME
+
+MKDoc::Text::Structured::Inline - convert text to HTML without handling block-level tags
+
+=head1 SYNOPSIS
+
+  my $text = some_structured_text();
+  my $this = MKDoc::Text::Structured::Inline::process ($text);
+  my $that = MKDoc::Text::Structured::Inline::process_entities_only ($text);
+
+=head1 SUMMARY
+
+L<MKDoc::Text::Structured::Inline> is used by L<MKDoc::Text::Structured> to
+generate inline HTML elements such as hyperlinks, emphasis and entities.
+
+This module is also useful directly when the full block-level rendering of
+L<MKDoc::Text::Structured> is unwanted.
+
+=head1 USAGE
+
+=head2 Processing text and adding HTML tags
+
+For example, when processing text that is going to end up in an <h1> header,
+you wouldn't want any block level tags generated:
+
+  $header = "< My (c) symbol should be *bold* > -- and http://example.com/ 'linked'";
+  $header = MKDoc::Text::Structured::Inline::process ($title);
+
+$header is now:
+
+  &lt; My &copy; symbol should be <strong>bold</strong> &gt; &mdash; and <a href="http://example.com/">http://example.com/<a> &lsquo;linked&rsquo;
+
+=cut
+
 sub process
 {
     local $Text;
@@ -46,14 +80,16 @@
 
 =head2 Processing text without adding tags
 
-Example:
+Another example, if you were processing text that will end up in an HTML
+<title> tag, this tag should never contain any other tags, so you should use
+the MKDoc::Text::Structured::Inline::process_entities_only() method:
 
-  $title = "My (c) symbol shouldn't be *bold* -- or http://example.com/ 'linked'";
+  $title = "< My (c) symbol shouldn't be *bold* > -- or http://example.com/ 'linked'";
   $title = MKDoc::Text::Structured::Inline::process_entities_only ($title);
 
 $title is now:
 
-  My &copy; symbol shouldn't be *bold* &mdash; or <a href="http://example.com/">http://example.com/</a> &lsquo;linked&rsquo;
+  &lt; My &copy; symbol shouldn't be *bold* &mdash; &gt; or http://example.com/ &lsquo;linked&rsquo;
 
 =cut