Front page | perl.perl5.porters |
Postings from November 2021
* 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