comment on

Firstly, just to clear up any confusion over names:

Pod::Simple::Wiki::Textile is part of the Pod-Simple-Wiki distribution. It converts POD into Wiki Textile format. Its doco indicates that it shouldn't be used directly; but instead called via Pod::Simple::Wiki.
Pod::Simple::Wiki, also part of the Pod-Simple-Wiki distribution, allows converting POD into various Wiki formats; e.g. Pod::Simple::Wiki->new('textile').
pod2wiki, also in Pod-Simple-Wiki, is a front-end utility to Pod::Simple::Wiki. It can be used like: 'pod2wiki --style textile file.pod > file.wiki'.

For the purposes of this SoPW, I'm only interested in the conversion to Textile.

A brief background. At $work, I have a requirement to convert POD to Textile. I was pointed towards an existing in-house script which supposedly did this; however, I found many flaws in the output. I spent some time investigating this but couldn't see any easy way to fix it (short of writing my own parser). Writing a parser may be the way to go but, before doing so, I wanted to ask if anyone knew of any alternatives.

The following <readmore> block describes one of the major problems (it's rather long and non-essential reading):

I wrote test.pod:


=encoding utf8

=head1 Test POD to Wiki (Textile)

Test conversion of various POD elements to Textile format.

=head2 Lists

Test nesting.

=over 4

=item * Point 1

Point 1 Para 1

Point 1 Para 2

    Point 1 Para 2 Code1

    Point 1 Para 2 Code2

Point 1 Para 3

=over 4

=item * Point 1.1

Point 1.1 Para 1

Point 1.1 Para 2

    Point 1.1 Para 2 Code1

    Point 1.1 Para 2 Code2

Point 1.1 Para 3

=item * Point 1.2

Point 1.2 Para 1

Point 1.2 Para 2

    Point 1.2 Para 2 Code1

    Point 1.2 Para 2 Code2

Point 1.2 Para 3

=back

=item * Point 2

Point 2 Para 1

Point 2 Para 2

    Point 2 Para 2 Code1

    Point 2 Para 2 Code2

Point 2 Para 3

=back

=cut
[download]

This renders as expected with perldoc test.pod:

Test POD to Wiki (Textile)
    Test conversion of various POD elements to Textile format.

  Lists
    Test nesting.

    *   Point 1

        Point 1 Para 1

        Point 1 Para 2

            Point 1 Para 2 Code1

            Point 1 Para 2 Code2

        Point 1 Para 3

        *   Point 1.1

            Point 1.1 Para 1

            Point 1.1 Para 2

                Point 1.1 Para 2 Code1

                Point 1.1 Para 2 Code2

            Point 1.1 Para 3

        *   Point 1.2

            Point 1.2 Para 1

            Point 1.2 Para 2

                Point 1.2 Para 2 Code1

                Point 1.2 Para 2 Code2

            Point 1.2 Para 3

    *   Point 2

        Point 2 Para 1

        Point 2 Para 2

            Point 2 Para 2 Code1

            Point 2 Para 2 Code2

        Point 2 Para 3
[download]

However, when using 'pod2wiki --style textile test.pod > test.out', I get:

h1. Test POD to Wiki (Textile)

Test conversion of various POD elements to Textile format.

h2. Lists

Test nesting.

* Point 1
Point 1 Para 1

Point 1 Para 2

<pre>
    Point 1 Para 2 Code1

    Point 1 Para 2 Code2
</pre>

Point 1 Para 3

** Point 1.1
Point 1.1 Para 1

Point 1.1 Para 2

<pre>
    Point 1.1 Para 2 Code1

    Point 1.1 Para 2 Code2
</pre>

Point 1.1 Para 3

** Point 1.2
Point 1.2 Para 1

Point 1.2 Para 2

<pre>
    Point 1.2 Para 2 Code1

    Point 1.2 Para 2 Code2
</pre>

Point 1.2 Para 3

* Point 2
Point 2 Para 1

Point 2 Para 2

<pre>
    Point 2 Para 2 Code1

    Point 2 Para 2 Code2
</pre>

Point 2 Para 3
[download]

The inherent problems with this may not be obvious to anyone unfamiliar with Textile. To help with this, I ran that through a Textile to HTML converter:

<h1 id="test-pod-to-wiki-textile">Test POD to Wiki (Textile)</h1>
<p>Test conversion of various POD elements to Textile format.</p>
<h2 id="lists">Lists</h2>
<p>Test nesting.</p>
<ul>
<li>Point 1<br />
Point 1 Para 1</li>
</ul>
<p>Point 1 Para 2</p>
<pre><code>    Point 1 Para 2 Code1

    Point 1 Para 2 Code2</code></pre>
<p>Point 1 Para 3</p>
<p><strong></strong> Point 1.1<br />
Point 1.1 Para 1</p>
<p>Point 1.1 Para 2</p>
<pre><code>    Point 1.1 Para 2 Code1

    Point 1.1 Para 2 Code2</code></pre>
<p>Point 1.1 Para 3</p>
<p><strong></strong> Point 1.2<br />
Point 1.2 Para 1</p>
<p>Point 1.2 Para 2</p>
<pre><code>    Point 1.2 Para 2 Code1

    Point 1.2 Para 2 Code2</code></pre>
<p>Point 1.2 Para 3</p>
<ul>
<li>Point 2<br />
Point 2 Para 1</li>
</ul>
<p>Point 2 Para 2</p>
<pre><code>    Point 2 Para 2 Code1

    Point 2 Para 2 Code2</code></pre>
<p>Point 2 Para 3</p>
[download]

Then passed that HTML to lynx:


                                               Test POD to Wiki (Texti
+le)

   Test conversion of various POD elements to Textile format.

Lists

   Test nesting.
     * Point 1
       Point 1 Para 1

   Point 1 Para 2
    Point 1 Para 2 Code1

    Point 1 Para 2 Code2

   Point 1 Para 3

   Point 1.1
   Point 1.1 Para 1

   Point 1.1 Para 2
    Point 1.1 Para 2 Code1

    Point 1.1 Para 2 Code2

   Point 1.1 Para 3

   Point 1.2
   Point 1.2 Para 1

   Point 1.2 Para 2
    Point 1.2 Para 2 Code1

    Point 1.2 Para 2 Code2

   Point 1.2 Para 3
     * Point 2
       Point 2 Para 1

   Point 2 Para 2
    Point 2 Para 2 Code1

    Point 2 Para 2 Code2

   Point 2 Para 3
[download]

If you compare that with perldoc output above, you'll see that formatting within list items has been corrupted and the list nesting has been lost altogether.

— Ken

In reply to Pod::Simple::Wiki::Textile alternatives by kcott

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		`&`
	<		`<`
	>		`>`
	[		`[`
	]		`]`

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.