Front page | perl.perl5.porters |
Postings from November 2021
Re: Pre-RFC: markdown in pod
Thread Previous
From:
Oodler 577 via perl5-porters
Date:
November 13, 2021 17:54
Subject:
Re: Pre-RFC: markdown in pod
Message ID:
YY/7cptMRnVal6ri@odin.sdf-eu.org
* Dan Book <grinnz@gmail.com> [2021-11-13 10:54:22 -0500]:
> On Fri, Nov 12, 2021 at 8:54 AM 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
> >
> > 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.
> >
>
> I would echo other comments in saying that the ability to notate this is
> already present, and add that it should not be the job of Pod parsers to
> parse markdown - the Pod spec is intentionally simple. So in my view the
> bigger question is: what toolchain do you propose should handle displaying
> Pod and markdown within the same file? I don't have a good answer for this.
I do not have a good answer either, other than it should be possible to do
with POD what we do with Perl, make some incremental improvements that get
to the heart of what is wanted from markdown. It might be as simple as just
extending POD, such that:
# NAME -> =head1 NAME
Though, that would necessarily need to be differentiated from comments. The
idea of semantic based tags is a good one and would allow POD to "get out of
the way". Add support for MD (or mediawiki) style tables and backticks, then
it would meet a lot of my needs (because I don't know what the others' wants
are). E.g.,
=name -> =head1 NAME
=synopsis -> =head1 SYNOPSIS
=description -> =head1 DESCRIPTION
=subroutines ..
=options ...
=author ...
=copyright ...
Other:
1. allow "=head1" auto capitalize via perldoc
2. all other "=headN" should capitalize based on convention
Code/verbatim:
1. `inline code` -> C<inline code>
2. generalize "=over N, =back" to be a block quote
2. add, "=code [language], =back" + plus some plug-in for rendering "language"
if supported (could be highlighting, could be rendering)
Regarding, "getting POD out of the way", the biggest pain I find is the need
to type a string of capitalized letters to stay consistent with the style
(e.g., "=head1 NAME").
Just some thoughts. I am interested in helping with any tooling surrounding
documentation, but I have no idea where to start. Any help or information
in that regard would be helpful to me. Also, it's hard for me to jump in
when I don't see an official effort or something sort of sanctioned working
group that gives me the confidence that any of my (or anyone's time) spent
on this would actually benefit Perl/perl (eventually).
Cheers,
Brett
>
> -Dan
--
--
oodler@cpan.org
oodler577@sdf-eu.org
SDF-EU Public Access UNIX System - http://sdfeu.org
irc.perl.org #openmp #pdl #native
Thread Previous