Re: Pre-RFC: markdown in pod

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

Re: Pre-RFC: markdown in pod

Thread Previous | Thread Next

From:

Oodler 577 via perl5-porters

Date:

November 12, 2021 16:20

Subject:

Re: Pre-RFC: markdown in pod

Message ID:

YY6TpjvXYVKiH/yZ@odin.sdf-eu.org

* Neil Bowers <neilb@neilb.org> [2021-11-12 13:54:02 +0000]:

> 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.

Peform any reader loses interest in my email, I want to point out
an amazing example of a document/rendering system written in Perl:

    https://metacpan.org/dist/LaTeXML/view/bin/latexml
    https://dlmf.nist.gov/LaTeXML/
    https://dlmf.nist.gov/ 
    In the process of developing the Digital Library
    of Mathematical Functions, we needed a means of
    transforming the LaTeX sources of our material into
    XML which would be used for further manipulations,
    rearrangements and construction of the web site.
    In particular, a true âDigital Libraryâ should
    focus on the semantics of the material, and so we
    should convert the mathematical material into both
    content and presentation MathML. At the time, we
    found no software suitable to our needs, so we
    began development of LaTeXML in-house.

It should be no surprise that I literally never think about what people
not familiar with Perl think and I don't care about them unless they want
to make an effort to *learn* Perl/perl. I recommend we all eschew the temptation
to do so. We do so at our own per[i]l. I imply this a lot, but here it is stated
very clearly.

We have almost 40 years of POD and the best text processing
environment in the universe. We can do better than jump over
to something that has yet to prove any longevity or stability.

> 
> I regularly find myself wanting to write markdown instead of pod, particularly when writing modules. Something like:

That's you. I like our dog food more than I hate it.

What I find myself wanting to do more intuitively in POD are:

* lists, sublists
* tables (mentioned below)
* inlined <code>...</code>
* verbatim/<pre/> sections
* better internal linking
* alt. to =headN for sections (maybe adopting MD's '#' behind
  the '=' sentinal, (e.g., "=#, =###, etc")

So rather than propose we embed a formatting syntax in a formatting
syntax, I recommend the approach to extend the POD "standard" to
allow (in a "safe" way) the above capabilies.

Alternative: better tooling, e.g., so you can maintain your POD/MD
chimera, and run it through POD pre-processor (e.g., exposed via
something like a Dist::Zill plugin since that's equally gross).

Ultimately, POD's limitations are also its strength. If not done
properly this could open a pandora's box of all kinds of abominations
that pass for "POD".

> 
> =format markdown
> 

Not a terrible thought, but what happens when we want,

=format SQL

=format asciidoc

etc?

> # 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.

Well, that is a big problem. I personally would prefer to see a
limited extension to POD be created that would make it easier
to do things like, idk - maintain RFC documentation in something
that POD or PODng. Maybe even a Perl-centric solution that resulted
in the tooling surrounding something like docbook (e.g.,). 

With this in mind, a missing "arm" of the documentation effort in
Perl has to do with tooling. I've expressed interest in the past of
helping out with this aspect (maintence, refactor, extending) - so
the idea of improving the joy, accuracy, and tooling around *our*
documentation DSL, the "docs" effort would encompass:

* actual documentation content 
* tools writers/maintainers *love* to use
* managing POD improvements via tooling

Finally, I'd love to use POD to do thing like write white papers
or RFCs, actual technical document. MD can't do those things well
either. Both activities require actually enjoying the act of writing
the text, which I get out of 2 things: plain text and latex. I'd
like to add POD to this mix - injecting MD into POD will not accomplish
that for me, not even close. In otherwords, anything we accept as
a defacto alternative to POD will not give us the same joy most of
us get in writing actual Perl (or provide the immediate gratification);
but I think with some thought and proper tooling, we get get there
with POD itself.

Cheers,
Brett

> 
> Neil

-- 
--
oodler@cpan.org
oodler577@sdf-eu.org
SDF-EU Public Access UNIX System - http://sdfeu.org
irc.perl.org #openmp #pdl #native

Thread Previous | Thread Next