How can one put a table into a pod
Karl Williamson
using as-is formatting, but it's not very good.
The documentation in perlpod seems to indicate that in
----------------------------------------------------
=begin html
<br>Figure 1.<br><IMG SRC="figure1.png"><br>
=end html
=begin text
---------------
| foo |
| bar |
---------------
^^^^ Figure 1. ^^^^
=end text
----------------------------------------------------
the 'text' part acts as a fall back, and that an html formatter will not
output it, even though it knows how to. Is that the case? If so, that
could be used to put a table into the pod that works for the formatters
that one knows how to specify tables for, and have the as-is function as
a fallback. But how does one guarantee that the format version and the
fallback aren't both output?
Karl Williamson
It's worse than I thought. I ran some experiments. It appears that the
various formatters don't recognize 'text', and so there's no way to
specify a fall back. Perhaps there is a 'text' formatter. I don't know
what it would be.
There also doesn't appear to be a way to extend the pod language in a
backwards compatible way.
Am I missing something?
Karl Williamson
> On 04/23/2011 03:12 PM, Karl Williamson wrote:
>> On 04/23/2011 01:09 PM, Karl Williamson wrote:
>>> I don't know how to put a table into a pod. One can simulate it by using
>>> as-is formatting, but it's not very good.
>>
>> backwards compatible way.
>>
>> Am I missing something?
>
> all normal pod, plus tables. For a good example of this, see
> Pod::PseudoPod. The table formatting it uses is demonstrated in:
>
> http://search.cpan.org/~arandal/Pod-PseudoPod-0.16/lib/Pod/PseudoPod/Tutorial.pod#Tables
>
>
> (Or, perhaps this implementation of tables will be enough for your
> purposes, and you won't need your own subclass.)
>
> Allison
>
That explains how to do it. Thanks. I would like something like this
for the core Perl 5 documentation. Are there reasons besides inertia
for this to not be shipped with the Perl core?
Russ Allbery
> It's worse than I thought. I ran some experiments. It appears that the
> various formatters don't recognize 'text', and so there's no way to
> specify a fall back. Perhaps there is a 'text' formatter. I don't know
> what it would be.
pod2text (Pod::Text).
There have been many proposals over the years for a table representation
in POD, but the general consensus has always been that tables are
inherently complex enough that the result would be straying away from the
"plain" in Plain Old Documentation. Table markup in wikis is probably
about as simple as one can get away with and still generate a useful
table, and it's still pretty complex. Tables are inherently hard to do
properly, and there's an immediate demand for additional features (row
spanning, column spanning, headings, etc.).
I don't object to supporting it in Pod::Text and Pod::Man, but I'd have to
ask someone else to write the initial implementation. I think support in
Pod::Man at least would be fairly important before deciding to add tables
to Perl's core documentation, but the research on how to use tbl properly
is more than I currently have time for.
--
Russ Allbery (r...@stanford.edu) <http://www.eyrie.org/~eagle/>
David E. Wheeler
> That explains how to do it. Thanks. I would like something like this for the core Perl 5 documentation. Are there reasons besides inertia for this to not be shipped with the Perl core?
Tuits. If you or someone else would like to propose an addition to perlpodspec for tables, I'm sure discussion would be welcome here, and we could come to some consensus on how it should work. Then it's a SMoP.
Best,
David
Karl Williamson
I used to be considered a [nt]roff guru. I would still rather use it
than MS Word, but I find the Linux implementations lacking, and actually
don't have much need to write documents. Anyway, I could easily write
the Pod::Man part (famous last words); but I don't know how widespread
tbl is, or its quality on Linux. I imagine the nroff output of tbl
could be used for Pod::Text, again spoken with no investigation.
Russ Allbery
> I used to be considered a [nt]roff guru. I would still rather use it
> than MS Word, but I find the Linux implementations lacking, and actually
> don't have much need to write documents. Anyway, I could easily write
> the Pod::Man part (famous last words); but I don't know how widespread
> tbl is, or its quality on Linux.
tbl is comfortably universal at this point on any system that uses *roff,
I think. I'm not worried about that. Avoiding any GNU-specific features
may be a bit harder, but hopefully not too hard. If you know how to write
it, that would be great.
> I imagine the nroff output of tbl could be used for Pod::Text, again
> spoken with no investigation.
Pod::Text unfortunately can't rely on tbl or nroff to do rendering, since
Pod::Text is designed to convert POD anywhere to something that's
immediately readable. Its intention is to be the lowest common
denominator output that works on Windows, VMS, etc. The best way to deal
with it may be to use a markup for tables that's sufficiently readable
that Pod::Text can just dump the markup into the output, at least to start
with. If someone feels energetic, they could then improve that.
Tom Christiansen
I always just include pod-embedded =for tbl tables for the
books and let the production crew handle it. That's not
a solution that works here, though.
--tom
Karl Williamson
I was thinking that PseudoPod implemented most of what might be needed,
and so why not ship that.
Its table spec looks quite simple, and perhaps sufficient. tbl's is
also pretty simple; it allows, without my looking at the documentation,
at least columns that have justification of left, center, and the
default 'alpha' which is essentially left, but I can't remember the
difference, and numeric, so the decimal points line up. You can also
create spans, and bold, etc. The other specification I'm familiar with
is html, and it offers far more power than needed.
David E. Wheeler
> I was thinking that PseudoPod implemented most of what might be needed, and so why not ship that.
>
> Its table spec looks quite simple, and perhaps sufficient.
+1
> tbl's is also pretty simple; it allows, without my looking at the documentation, at least columns that have justification of left, center, and the default 'alpha' which is essentially left, but I can't remember the difference, and numeric, so the decimal points line up. You can also create spans, and bold, etc.
I expect one can use B<> and friends within PseudoPod tables, yes?
I do think we should keep Pod as Pod; troff is something else entirely.
> The other specification I'm familiar with is html, and it offers far more power than needed.
Yeah, and one can always =begin html to do that.
Best,
David
Shawn H Corey
> The table formatting it uses is demonstrated in:
>
> http://search.cpan.org/~arandal/Pod-PseudoPod-0.16/lib/Pod/PseudoPod/Tutorial.pod#Tables
>
I have just taken a look at this. They totally screwed up `=for`. A
`=for` paragraph does not need a `=end for`.
Example:
=head1 TEST
=for ignore
This should not be seen.
This should.
=cut
--
Just my 0.00000002 million dollars worth,
Shawn
Confusion is the first step of understanding.
Programming is as much about organization and communication
as it is about coding.
The secret to great software: Fail early & often.
Eliminate software piracy: use only FLOSS.
Karl Williamson
> On Apr 23, 2011, at 10:09 PM, Karl Williamson wrote:
>
>> I was thinking that PseudoPod implemented most of what might be needed, and so why not ship that.
>>
>> Its table spec looks quite simple, and perhaps sufficient.
>
> +1
However, in thinking about this some more, I think we need to be able to
at least specify centered column headings, and spans. This is easily
done with html and tbl.
David E. Wheeler
> However, in thinking about this some more, I think we need to be able to at least specify centered column headings, and spans. This is easily done with html and tbl.
But they'er not Pod, are they?
Best,
David
Russ Allbery
Yes, but my assumption is that the discussion here is about inventing POD
syntax to represent tables natively, and to do that we have to figure out
what the requirements are and confirm that it's viable to convert such POD
tables into our most common output formats. Which is what I was assuming
that Karl was doing.
David E. Wheeler
> Yes, but my assumption is that the discussion here is about inventing POD
> syntax to represent tables natively, and to do that we have to figure out
> what the requirements are and confirm that it's viable to convert such POD
> tables into our most common output formats. Which is what I was assuming
> that Karl was doing.
Oh, okay. I'll STFU then.
Best,
David
Shawn H Corey
> It's kind of fundamental to the nature of subclassing that you can
> override any behavior you want.:)
>
"The nicest thing about standards is that everyone can make their own."
Karl Williamson
>
>
> On 04/25/2011 08:09 PM, Karl Williamson wrote:
>> On 04/23/2011 11:53 PM, David E. Wheeler wrote:
>>> On Apr 23, 2011, at 10:09 PM, Karl Williamson wrote:
>>>
>>>> I was thinking that PseudoPod implemented most of what might be
>>>> needed, and so why not ship that.
>>>>
>>>> Its table spec looks quite simple, and perhaps sufficient.
>>>
>>> +1
>>
>> However, in thinking about this some more, I think we need to be able to
>> at least specify centered column headings, and spans. This is easily
>> done with html and tbl.
>
>
> =row center
>
> =row right
I'm thinking this would mean that the first column in the first row
would be centered, and the first column in the second row would be right
justified, and any other columns would have the default? Is that
correct? Thus for three columns, one could say
=row center left left
>
> =cell span 2
I would think that it would be better to put the span info on the =row
tag because the =cell tag already accepts text after it, and it is
sufficient to put it on the row tag, like this:
=row center left span 2
denotes three columns, with the final 2 merged.
Also, I would think it would be best if =row's that have no modifiers
would inherit the modifiers from the latest =row that does have them. So
=row center left span 2
...
=row
...
=row
has 3 rows each with 3 columns in the same layout.
I'm tempted to not have defaults; the first =row must list each column,
and it would be an error to have a different number of cells than
specified by that =row. (Again, subsequent =row's wouldn't have to list
the modifiers)
I think it must be the case in PseudoPod that there can be a full
paragraph of text after the =cell. Or must everything be on that line?
Is it possible to specify more than one =headrow? I think even simple
tables need to be able to have sub-headings.
>
>
> Worth thinking through the desired characteristics. It'll have to be a
> bit of "least common denominator", since we don't want to give people
> the idea that they can build hugely complicated table specifications in
> Pod when there's no way to represent them in the various output formats.
>
> For HTML output, I tend to create a stylesheet that does all the fancy
> display work on the tables. (The generated HTML pages do a very
> tolerable impression of the O'Reilly printed table format.)
>
> We also need to remember LaTeX and DocBook XML as common table output
> formats.
>
> Allison
>
Ronald J Kimball
> On 04/26/2011 10:51 AM, Allison Randal wrote:
> >
> >How about adding some modifiers to the PseudoPod tags, such as:
> >
> >=row center
> >
> >=row right
>
> I'm thinking this would mean that the first column in the first row
> would be centered, and the first column in the second row would be right
> justified, and any other columns would have the default? Is that
> correct? Thus for three columns, one could say
>
> =row center left left
>
> >
> >=cell span 2
>
> I would think that it would be better to put the span info on the =row
> tag because the =cell tag already accepts text after it, and it is
> sufficient to put it on the row tag, like this:
>
> =row center left span 2
>
> denotes three columns, with the final 2 merged.
This is an interesting approach. However, I think it would be difficult to
edit tables, especially if one wants to move cells around within a table,
because settings that belong to a specific cell would not be placed with
the cell.
Putting the modifiers on the =cell tag would be much better, except that,
as Karl points out, the text following the =cell tag already has meaning as
the contents of the cell.
Perhaps a new inline character tag could be used to mark these modifiers?
=cell J<center> J<span 2> This is a wide, centered cell!
(Where J is whichever of the available letters is most appropriate.)
Ronald
Shawn H Corey
> =cell J<center> J<span 2> This is a wide, centered cell!
>
What if you want a cell to span two columns and two rows at the same time?
=cell J<center> J<middle> J<rowspan 2> j<colspan 2> paragraph