Front page | perl.perl5.porters |
Postings from November 2021
Re: Pre-RFC: markdown in pod
From: Nicholas Clark
November 15, 2021 19:59
Re: Pre-RFC: markdown in pod
Message ID: YZK77MgkYIi/szM8@etla.org
On Fri, Nov 12, 2021 at 01:54:02PM +0000, Neil Bowers wrote:
On Mon, Nov 15, 2021 at 03:45:15PM +0100, Tomasz Konojacki wrote:
> On Fri, 12 Nov 2021 13:54:02 +0000
> Neil Bowers <email@example.com> wrote:
> > Markdown has long since won the battle of simple text-based documentation formats. People, not just developers, are used to writing it in lots of different places. Odds are that developers trying out Perl, coming from other language experience, will be familiar with markdown, and pod will just seem weird.
> > I regularly find myself wanting to write markdown instead of pod, particularly when writing modules. Something like:
> > =format markdown
> > # NAME
> > ...
> > ## Functions
> > ...
> > =cut
In core we use Pod to generate man pages, text documentation and HTML.
We seem to mention `perldoc` [or should I say C<perldoc>? :-)] more than
the other two.
(If I understand =for correctly) then using exactly the syntax you're
suggesting would mean that perldoc would render module documentation as a
Hence this *exact* syntax likely doesn't work, but that doesn't rule the
idea out. Moreso - my rough understanding of (common) markdown is that it
basically offers the same formatted output styles as Pod can already do,
so implementing "markdown" as an equal alternative is *more* about parsing
than outputting. The solution seems to be more about implementing a markdown
parser that generates the same internal format as a Pod parser parses to,
and sharing the same text, troff and HTML backends.
> > There are some things that pod provides that markdown doesn't, and there's the whole table issue. But on the very rare occasion I've wanted a table in documentation I've used a manually formatted ASCII table. And most modules have fairly simple documentation, in terms of the pod syntax currently used.
> > I think this would provide one less huh?/wtf? barrier to people trying Perl, and would let people use the broad range of markdown tools out there.
> > The biggest problem I'm aware of is that this would require coordination of changes in multiple places, and I don't even know what all of those places are. And there are different markdown formats, so we'd have to pick one.
[description of =for that I expanded above]
> In my opinion, allowing to write a whole documentation in Markdown would
> be too drastic of a change and I don't support it. Also, keep in mind
> that Markdown isn't really standarized and there are several competing
> syntaxes for e.g. tables. If we allowed "=for markdown", we would have
> to write a complete specification for our Markdown dialect.
Yes, this is my biggest concern. I'm not sure if there *is* an obvious
Markdown spec to implement. The "obvious" choice is CommonMark:
But *that* doesn't have tables.
Implement CommonMark and what do we get that Pod doesn't have?
Yay. Not really worth it.
I'm not sure if there *is* a third party spec that also has tables, but then
doesn't also have a bunch of cruft we don't want to (or can't) implement.
As best I can tell, all of GitHub, GitLab and Bitbucket extend Markdown
with basically the same table syntax:
(note that Bitbucket markdown doesn't have a published spec. That page lies
by linking only to CommonMark)
but there doesn't seem to be a common ancestor of the three that has just
what we might need.
Whereas all those three
1) offer things that we likely can't support, such as ~~strikethrough text~~
(useful, but not something that can be done in troff or plaintext?)
2) specify a bunch of domain specific "autolinking" rules that we simply
don't want to offer
And I guess there's also the elephant in the room - even CommonMark is no
good as-is, because *all* markdown permits you to inline HTML, which makes
sense for it. We need to specify "Markdown, but without inline HTML", else
how do we target perldoc?
Again, this doesn't rule the idea out, but it looks likely that to be useful
we want images, tables and no HTML escape hatch, meaning that we'd need to
create "Perl flavoured markdown", rather than being able to document that
we implement standard X.
> I think we should fix POD instead. There are two big problems with it:
> the lack of images and the lack of tables. Both are fixable. I will
> probably submit pre-RFCs soon.
I'm of an open mind on "instead". But I'd welcome Pod-like solutions for
images and tables. If I understand it correctly, markdown's image syntax
restricts you to declaring
* image URL
* image title
* image ALT text
and the rest is under its control, not yours.