Mailing List Archive

reStructuredText WAS Re: Pre-RFC: markdown in pod
> On Nov 15, 2021, at 14:58, Nicholas Clark <nick@ccl4.org> wrote:
>
> 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?

Another way to say this is: Markdown *targets* HTML, more or less by design. It doesn’t really intend to render to plain text—at least, a while back when I looked for a Markdown-to-text renderer I came up empty.

A bit earlier in this thread I mentioned reStructuredText. From what I can see, this format is basically “like Markdown but renders to text”. What if Perl went this route instead?

-FG
Re: reStructuredText WAS Re: Pre-RFC: markdown in pod [ In reply to ]
Just throwing this out there,

https://stackoverflow.com/questions/7612374/how-to-convert-asciidoc-to-perl-pod

After my email the other day about hating "=head1 ALLCAPS", I
relaized that POD also has value as a pure text format.

I raise this because any "table" should also look like a table in
plain text. This gives means we can't *just* use something that's
already out there and nobody seems to be suggesting HTML. Docbook
(SGML, technically) does tables this way,

https://tdg.docbook.org/tdg/4.5/table.html

Latex does it this way,

https://en.wikibooks.org/wiki/LaTeX/Tables

Finally, it is important to note when we fully consider that
traditionally, POD has been concerned with flow in one direction.
Here we must think about it both. And this leads me to suggest that
if we're going to inline *anything* foreign, it might be wise to
consider *adapting* something we already have, see [1].

Brett

1. `perldoc perlform`

* Felipe Gasper <felipe@felipegasper.com> [2021-11-15 17:31:37 -0500]:

>
> > On Nov 15, 2021, at 14:58, Nicholas Clark <nick@ccl4.org> wrote:
> >
> > 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?
>
> Another way to say this is: Markdown *targets* HTML, more or less by design. It doesn?t really intend to render to plain text?at least, a while back when I looked for a Markdown-to-text renderer I came up empty.
>
> A bit earlier in this thread I mentioned reStructuredText. From what I can see, this format is basically ?like Markdown but renders to text?. What if Perl went this route instead?
>
> -FG

--
--
oodler@cpan.org
oodler577@sdf-eu.org
SDF-EU Public Access UNIX System - http://sdfeu.org
irc.perl.org #openmp #pdl #native
Re: reStructuredText WAS Re: Pre-RFC: markdown in pod [ In reply to ]
* Oodler 577 via perl5-porters <perl5-porters@perl.org> [2021-11-15 23:18:50 +0000]:

> traditionally, POD has been concerned with flow in one direction.
> Here we must think about it both. And this leads me to suggest that ...

Oof..sorry. I meant *dimension*. The main point is that a table in POD
needs to look like a table the POD; not just in it's rendered form
which is secondary. I don't even see how asciidoc has solved that one.

Cheers,
Brett

> Just throwing this out there,
>
> https://stackoverflow.com/questions/7612374/how-to-convert-asciidoc-to-perl-pod
>
> After my email the other day about hating "=head1 ALLCAPS", I
> relaized that POD also has value as a pure text format.
>
> I raise this because any "table" should also look like a table in
> plain text. This gives means we can't *just* use something that's
> already out there and nobody seems to be suggesting HTML. Docbook
> (SGML, technically) does tables this way,
>
> https://tdg.docbook.org/tdg/4.5/table.html
>
> Latex does it this way,
>
> https://en.wikibooks.org/wiki/LaTeX/Tables
>
> Finally, it is important to note when we fully consider that
> traditionally, POD has been concerned with flow in one direction.
> Here we must think about it both. And this leads me to suggest that
> if we're going to inline *anything* foreign, it might be wise to
> consider *adapting* something we already have, see [1].
>
> Brett
>
> 1. `perldoc perlform`
>
> * Felipe Gasper <felipe@felipegasper.com> [2021-11-15 17:31:37 -0500]:
>
> >
> > > On Nov 15, 2021, at 14:58, Nicholas Clark <nick@ccl4.org> wrote:
> > >
> > > 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?
> >
> > Another way to say this is: Markdown *targets* HTML, more or less by design. It doesn?t really intend to render to plain text?at least, a while back when I looked for a Markdown-to-text renderer I came up empty.
> >
> > A bit earlier in this thread I mentioned reStructuredText. From what I can see, this format is basically ?like Markdown but renders to text?. What if Perl went this route instead?
> >
> > -FG
>
> --
> --
> oodler@cpan.org
> oodler577@sdf-eu.org
> SDF-EU Public Access UNIX System - http://sdfeu.org
> irc.perl.org #openmp #pdl #native

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