develooper Front page | perl.perl5.porters | Postings from November 2021

Re: Pre-RFC: markdown in pod

Thread Previous | Thread Next
Tom Molesworth via perl5-porters
November 12, 2021 15:47
Re: Pre-RFC: markdown in pod
Message ID:
On Fri, 12 Nov 2021 at 22:04, Felipe Gasper <> wrote:

> > On Nov 12, 2021, at 08:54, Neil Bowers <> 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
> This already works, right? What kind of support do you envision?

Indeed, the `=for` syntax is already there - some people (maybe just me)
embed Markdown in Perl files already - so this feels more like a
toolchain+MetaCPAN discussion than a core Perl feature?

One issue with the pre-RFC here is that it preserves the non-semantic
convention of `# NAME` (following `=head1 NAME` from pod) as above...
that's not great, everyone else writing markdown gets to put their module
name right after the `# ` so Perl markdown is still going to look a bit
primitive if it's `# NAME\nSome::Module`. "Not great" because this ends up
with the important detail - the name - indistinguishable from the rest of
the meƤndering text around it.

Put another way: semantic markup!

If we actually had specific `=module Some::Module` markup (or `=class
Some::Class\n\n=method some_method`, to go with our shiny new ~Object::Pad~
core OO system), we'd gain something that's machine-readable... and not
subject to the complexity of a thousand different minor variations. I can't
even reliably link to a method/function name in another module, because
some people like to use the `=head2 method($example, $parameters)` form.
Justifiably so - you get to see at a glance what the parameter structure is
just by skimming the index. Even if you get the L<> syntax right for that
version, it's fragile.

That would, of course, be an entirely different pre-RFC.

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About