/ 
MKDoc-Text-Structured-0.1
River stage zero No dependents
/ MKDoc::Text::Structured

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

Sections

Sections are represented as follows:

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

Which produces:

<h2>This is a section</h2>

Note: There is no way to do H1 since this is used by MKDoc for the title of the document.

Sub-sections

H3's are represented as follows:

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

Which produces:

<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.

Would produce:

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

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

Bulleted Lists

Bulleted lists can be constructed as follows:

* An item
* Another item
* Yet another item

Which would produce:

<ul>
  <li>An item</li>
  <li>Another item</li>
  <li>Yet another item</li>
</ul>

Note: MKDoc::Text::Structured does not support nested lists. I have no idea on how to support this with the current implementation. Patches are always welcome :)

Ordered Lists

Ordered lists can be constructed as follows:

1. An item
2. Another item
3. Yet another item

Which would produce:

<ol>
  <li>An item</li>
  <li>Another item</li>
  <li>Yet another item</li>
</ol>

Note: Same remark as above.

Strong / Bold

Bold portion of text can be constructed as follows:

*This will appear in bold*.

Will produce:

<strong>This will appear in bold</strong>.

Note 1: If you do not want the star to act as a 'bold' marker, you can do this using spacing. For example:

* This will not appear in bold *
3 * 3 = 9

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 / Italic

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

/This is an emphasized portion of text/.

Same notes as for bold / strong apply.

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