bigpresh / bigpresh/Pod-Readme

=for readme syntax creates problems with other POD processors -- and itself

Open
#19 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Perl
Stars
7
Forks
12
PR merge metrics
No merged PRs in 30d

Description

The Pod::Readme syntax for in-line commands (based on `=for`) doesn't conform to POD syntax rules, and creates confusion. Pod::Readme thinks that `=for` is distinct from `=begin =end`, but it's not. 0.11 managed to deal with this better.

In pod, `=for` lines indicate that the rest of the paragraph goes to the specified translator; it is otherwise identical to an `=begin =end` block.

Pod::Weaver (frequently run by `Dist::Zilla` packaging scripts to generate Author, Copyright, BUGs and other boilerplate paragraphs) will optimize a single paragraph `=begin =end` block into the corresponding `=for`.

Pod::Readme becomes confused when the `=for` is not a command.

Consider:

```
=begin :readme

See figure 1.

=end :readme
```

This is transformed into:

```
=for :readme See figure 1
```

And of course "See figure 1" is not a valid Pod::Readme command.

```
Unknown command: 'See' at input line 1689
```

Perhaps the easiest solution is to require that the `=for` commands are somehow recognizable in plain text, and treat unquoted text as paragraph text. e.g.

```
=for :readme {start} See figure 1
=for :readme {include foo.txt start=beginning} etc
```

This still leaves the problem that given:

```
=for :readme {include ...}
Paragraph
```

Pod::Readme thinks that "Paragraph" is common text, but any other translator thinks that "Paragraph" belongs only to `:readme` and will ignore it.

Perhaps something like this is a solution:

```
=begin :readme
{commands}

{include ...}

=end :readme
```

It's rather annoying to change the command syntax at this point, but Pod::Readme's syntax choice is clearly wrong. Unfortunately, it has _almost_ worked since day 1...

Perhaps you have a better solution. I don't like this one. But Pod::Readme does need to play by the POD rules so it can interoperate with other translators.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.