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

Hi,

to document my perl app i use a tool chain with Markdown as intermediate format. I use Pod::Markdown to convert POD to Markdown. There is one problem with this module: if i try to embed Markdown into an =item then it adds too much indentation, so the embedded Markdown is always verbatim. Simple example:

=over

=item *

Huhu!

=begin markdown

This should be **bold** using markdown.

=end markdown

=back

[download]

this results in:

- Huhu!

        This should be **bold** using markdown.

[download]
I'd expect: 
- Huhu!

  This should be **bold** using markdown.

[download]
A three year old bug report exists, but without any response: https://rt.cpan.org/Public/Bug/Display.html?id=131585. I looked into the code to see if i can fix this by myself, but it seems that this is caused by a base class method. Here i stopped since i am not familiar with the POD parser classes. Does anyone know of a solution or workaround for this problem?

Replies are listed 'Best First'.
Re: Pod::Markdown: problem with =begin markdown ... =end markdown inside an =item
by kcott (Archbishop) on Jan 02, 2023 at 20:02 UTC

    G'day Darkwing,

    I didn't have Pod::Markdown so I installed it and got the latest version, 3.300. I was able to reproduce your results: so rt:131585 is still outstanding. By the way, I'm using Perl v5.36.0.

    That bug was raised on 28-Jan-2020. The last module update was on 1-Nov-2020. So maintenance was at least active at the time that the bug was reported. You could try contacting the module author, Randy Stauner, directly: there are some (links to) contact details in https://metacpan.org/author/RWSTAUNER. (I note that he's a registered monk, rwstauner, but as he hasn't been seen wandering the cloisters in about a decade, contact via /msg is probably a dead-end.)

    In terms of a workaround, I'm not really across why you want "=begin markdown" when you're converting to Markdown. Removing both the "=begin" and "=end" paragraphs, and changing "**bold**" to "B<bold>", would appear to provide the output you're looking for. 

    $ cat test.pod

=over

=item *

Huhu!

This should be B<bold> using markdown.

=back


$ pod2markdown < test.pod > test.md

$ cat test.md
- Huhu!

    This should be **bold** using markdown.

    [download]

    Plugging that into https://codebeautify.org/markdown-viewer, I get

    • Huhu!

      This should be bold using markdown.

    If you could provide a few more details regarding your ultimate goal, we may be able to provide an improvement upon my simplistic workaround offered above.

    — Ken

[reply]
[d/l]
[select]

      Hi Ken,

      thanks. I'll send a mail.

      The example, of course, is a minimal example. In reality, i do something else. Main purpose of using markdown embedded in POD is displaying tables without the need to switch to a non-standard such as PseudoPOD. Example (the real table has more rows):

      =for ! begin markdown unindent=|

   Option           Import   Trace    Export
  --------------   -------- -------  --------
    `-b`              o        o        -
    `-c`              o        o        o
    `-D`              o        o        o
    `-e`              -        o        -
    `-E`              o        o        o
    `-f`             -/m      -/m      -/m
    `-I`              o        o        o
    `-m`              -        o        -
    `-M`              o        -        -
    `-n`              o        -        -
    `-o`              o        o        o
    `-O`              o        o        o

=for ! end markdown

      [download]
      When typing perlpod TheTool.pl, the =for lines are ignored and the user sees an ascii formatted table. When i produce the HTML and LaTeX code i first pass this to a filter script that converts the =for ... lines to =begin markdown and =end markdown (the unindent=| in the first =for is an additional argument for this filter). So i get a nicely formatted HTML/LaTeX table. This works fine outside a list but unfortunately it does not inside an =item, here i also get only ascii formatting even in HTML and LaTeX which again is caused by this unwanted indentation.
[reply]
[d/l]
[select]

        Thanks for the follow-up and the "filter script" clarification.

        Please let us know how you go chasing this up with the author.

        — Ken

[reply]

Back to Seekers of Perl Wisdom