bigpresh / bigpresh/Pod-Readme
=for readme syntax creates problems with other POD processors -- and itself
- 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.