kcott has asked for the wisdom of the Perl Monks concerning the following question:

Firstly, just to clear up any confusion over names:

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

Replies are listed 'Best First'.
Re: Pod::Simple::Wiki::Textile alternatives
by LanX (Saint) on Aug 25, 2021 at 08:31 UTC
    I can't offer you an alternative, but may propose a strategy:

    The most probable reasons are

    I'd boil it down two 1-2 essential tests (ATM that's a lot to read and hard to spot) and check it with the most used wikis, because they should be the best tested. IMHO this should at least include mediawiki.°

    If the problem can't be reproduced then Pod::Simple::Wiki::Textile needs to be patched. (It's actually a very concise module)

    Otherwise share your tests with the author of Pod::Simple::Wiki and file a bug report.

    Cheers Rolf
    (addicted to the Perl Programming Language :)
    Wikisyntax for the Monastery

    °) ... and maybe markdown. Both happen to be the biggest backends, i.e. with most LOC.

[reply]

      G'day Rolf,

      ++ Thanks for responding. I think we're very much on the same page here.

      If I take the HTML produced by the "Textile to HTML converter", then modify it such that it renders the same (or at least equivalent) perldoc output, I have: 

      <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
<p>Point 1 Para 1</p>
<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>

<ul>
<li>Point 1.1
<p>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>
</li>

<li>Point 1.2
<p>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>
</li>
</ul>

</li>

<li>Point 2
<p>Point 2 Para 1</li>
<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>
</li>
</ul>

      [download]

      If I look at that in my browser, the only difference between it and perldoc is the characters used for the dot points: browser has disc (level 1) and circle (level 2); perldoc has asterisk for both levels (the indentation is correctly rendered in both cases).

      If I pass the HTML (above) through an HTML to Textile converter, everything after the "Test nesting." paragraph is pure HTML (there's no Textile at all here). It looks like this: 

      h1(#test-pod-to-wiki-textile). Test POD to Wiki (Textile)

Test conversion of various POD elements to Textile format.

h2(#lists). Lists

Test nesting.

<ul>
<li><p>Point 1</p>
<p>Point 1 Para 1</p>
<p>Point 1 Para 2</p>
<pre>
    Point 1 Para 2 Code1

    Point 1 Para 2 Code2
</pre>

<p>Point 1 Para 3</p>
<ul>
<li><p>Point 1.1</p>
<p>Point 1.1 Para 1</p>
<p>Point 1.1 Para 2</p>
<pre>
    Point 1.1 Para 2 Code1

    Point 1.1 Para 2 Code2
</pre>

<p>Point 1.1 Para 3</p></li>
<li><p>Point 1.2</p>
<p>Point 1.2 Para 1</p>
<p>Point 1.2 Para 2</p>
<pre>
    Point 1.2 Para 2 Code1

    Point 1.2 Para 2 Code2
</pre>

<p>Point 1.2 Para 3</p></li>
</ul>
</li>
<li><p>Point 2</p>
<p>Point 2 Para 1</p></li>
</ul>

      [download]

      The converter I've been using throughout is Pandoc.

      Although I've used Textile a lot, I wouldn't claim to be an expert. In HTML, an <li> is a block element allowing the inclusion of other block elements; e.g. <p>, <ul>, and so on. In Textile, you can implement <li> nesting only with very simple constructs, such as: 

      * Level 1
** Level 1.1
** Level 1.2
* Level 2
* Level 3
** Level 3.1
** Level 3.2

      [download]

      You can't turn any of those * contructs into real, block-level <li> constructs that allow complex block structures to be included.

      I believe this to be the fundamental, underlying problem. Textile neither has the capacity for, nor was designed for, this level of markup complexity.

      "Otherwise share your tests with the author of Pod::Simple::Wiki and file a bug report."

      Yes, I was definitely thinking along these lines myself; however, looking at https://github.com/jmcnamara/pod-simple-wiki/issues, I was wondering if a fix would be provided in a timely manner, or if I'd just get "Thanks for the report. Can you provide a patch?".

      I'll await other input and then make a decision on how to procede. Thanks again for your response.

      — Ken

[reply]
[d/l]
[select]

Back to Seekers of Perl Wisdom