develooper 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 16, 2021 02:38
Subject:
Re: Pre-RFC: markdown in pod
Message ID:
YZMZpOB+fAtJgs6y@odin.sdf-eu.org
* Yuki Kimoto <kimoto.yuki@gmail.com> [2021-11-16 09:44:36 +0900]:

> 2021-11-15 23:45 Tomasz Konojacki <me@xenu.pl> wrote:
> 
> >
> > I think we should fix POD instead. There are two big problems with it:
> > the lack of images and the lack of tables. Both are fixable. I will
> > probably submit pre-RFCs soon.
> >
> >
> Currently I write images and tables in POD using "=begin html" and "=end
> html" syntax.
> 
> If these are implemented, I'm glad.

I don't see how we're going to be able to do tables in a tabular
way and not short the value POD has as a readable format in its
own right.

=html
<table>
  <tr>
    <th>Column 1</th><th>Column 2</th><th>Column 3</th>
  </tr>
  <tr>
    <td>...... 1</td><td>...... 2</td><td>...... 3</td>
  </tr>
  <tr>
    <td>...... 1</td><td>...... 2</td><td>...... 3</td>
  </tr>
  <tr>
    <td>...... 1</td><td>...... 2</td><td>...... 3</td>
  </tr>
</table>
=end

To this end, this problem will not be solved by syntax because
the problem "space" is literaly 2D. What I mean there is that
POD has the constraint that is not solvable by "markup" - the
plain text view (e.g., source code) view of the POD must make
sense and look good. Markup/down is meant as an intermediate
format to get to a rendered state. For us the intermediate state
is also a final state.

The solution will be a combination of:

* tool(s)

- a "podtidy" (several exist on CPAN)
- a "parser" renderers may use to take an ASCII table into
  an abstract form that can then be used to output whatever
  (e.g., HTML, groff, PDF, etc)

* syntax

- the syntax must also look like a table (2D)
- the official "syntax" being some form of an ASCII table
  (e.g., see Text::ASCIITable)
- drop table into a "=table"/"=end" block

* workflow adoption (same as w/perltidy)

The following seems to be a reasonable and familiar workflow:

1) in POD, create table by hand using best effort "ASCIITable"
   format (focus on content and partions, but not alignment)

2) run "podtidy" (e.g., via vim using the '%!podtidy` format,
   which will take a valid NxM table and line things up

3) maintaining the table consists of modifying the table in
   question, then re-running "podtidy"

Challenges:

* yes there are some, but more familiarity with the tools needs
  to be acheived 

* using 2 tools (perltidy, podtidy) seems cumbersome; maybe perltidy
  needs to adopt this role once it's vetted

Other things this could support:

* =verbatim
* =blockquote

Thoughts?

Brett

Note: Tables are not the same problem as images or inline monospaced
code.

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


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About