NAME

MKDoc::Text::Structured - Another Text to HTML module

SYNOPSIS

    my $text = some_structured_text();
    my $html = MKDoc::Text::Structured::process ($text);

SUMMARY

MKDoc::Text::Structured is a library which allows very simple text construct to be turned into HTML. These constructs are the ones you would be using when writing a text email or newsgroup message.

MKDoc::Text::Structured follows the KISS philosophy. Comparing with similar modules which try to implement as many HTML constructs as possible, this module is incredibly restrictive, minimalistic and conservative.

And in fact that's why we use it :)

CONSTRUCTS

Titles

Titles are represented as follows:

    =========================
    This is a beautiful title
    =========================

Titles are transformed using <h1> tags:

    <h1>This is a beautiful title</h1>

Sections

Sections are represented as follows:

    This is a section
    =================

Sections are transformed using <h2> tags:

    <h2>This is a section</h2>

Sub-sections

Sub-sections are represented as follows:

    This is a sub-section
    ---------------------

Sub-sections are transformed using <h3> tags:

    <h3>This is a sub-section</h3>

Paragraphs

Paragraphs are made simply by separating two blocks of text with a carriage return.

    This is a first paragraph which has lots of
    interesting stuff, including an exclusive outlook
    on things and other ghizmos.

    This is a second paragraph, which has more interesting
    stuff to say. It's very good, too.

Paragraphs are transformed using <p> tags.

Quoted text

Quoted blocks are used usually to quote somebody:

    This is a paragraph:

    > > Ahha! This is some nested quoted text!
    > > Cool huh?
    > Of course, this is not nested.
    This is another paragraph.

Quoted blocks are transformed using <blockquote> tags.

Preformatted text

Preformatted text is pretty much like written in text emails or POD documentation.

    This is a paragraph.

        This is some <pre> text.
        I can do ASCII art in there and it'll work.
        Proof:
           -.-
            ^

    This is another paragraph.

Preformatted text is transformed using <pre> tags.

Definition lists

Definition lists can be constructed as follow.

    Orange:
      Round fruit with orange color
 
    Banana:
      Bent fruit with yellow color
 
    Apple:
      Round crunchy fruit with green,
      yellow or red color

They are transformed using <dl> <dt> and <dd> tags.

Ordered and unordered lists

Ordered lists and unordered lists can be constructed as follows:

    * An item
    * Another item
        1. A sub-item
        2. Another sub-item
        3. Yet another sub-item
    * Yet another item

They are transformed using <ul>, <ol> and <li> tags.

Strong / Bold

Bold portion of text can be constructed as follows:

    *This will appear in bold*.

Bold text is transformed using <strong> tags.

Note 1: The star character will act as a 'bold' marker only when:

- The "opening" star is preceded by whitespace or carriage return,

- The "closing" star is followed by whitespace or carriage return, or punctuation immediately followed by whitespace or carriage return.

In other words, you can write 3*3*2 = 18 safely. The module tries to follow the DWIM ("Do What I Mean") philosophy as much as possible.

Note 2: This can only work within one block level element. It will not work across paragraphs or lists.

Example 1:

   * Hello, *I will not
   * be bold*
   * but
   * *I will be*

Example 2:

   This is a paragraph. *Nothing in this paragraph
   is going to be bold.

   Nor in this one*.

Emphasis

To emphasize a portion of text, use the following construct:

    /This is an emphasized portion of text/.

Emphasis is transformed using <em> tags.

Same notes as for bold / strong apply.

Hyperlinks

MKDoc::Text::Structured has *NOTHING* to do with automagic hyperlinking.

At a low level you can use MKDoc::XML::Tagger, part of the MKDoc::XML distribution to do this.

Automagically hyperlinking HTML will be the job of another MKDoc module. It is out of the scope of operation of this current module.

AUTHOR

Copyright 2003 - MKDoc Holdings Ltd.

Author: Jean-Michel Hiver <jhiver@mkdoc.com>

This module is free software and is distributed under the same license as Perl itself. Use it at your own risk.

SEE ALSO

  Petal: http://search.cpan.org/author/JHIVER/Petal/
  MKDoc: http://www.mkdoc.com/

Help us open-source MKDoc. Join the mkdoc-modules mailing list:

  mkdoc-modules@lists.webarch.co.uk

cpanm MKDoc::Text::Structured

perl -MCPAN -e shell
install MKDoc::Text::Structured