Front page | perl.perl5.porters |
Postings from November 2021
On Fri, 12 Nov 2021 at 22:04, Felipe Gasper <felipe@felipegasper.com> wrote: > > On Nov 12, 2021, at 08:54, Neil Bowers <neilb@neilb.org> 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