Re: How can one put a table into a pod

[David E. Wheeler]

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

> 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

Re: How can one put a table into a pod

[Karl Williamson]

On 04/23/2011 10:13 PM, David E. Wheeler wrote:

On Apr 23, 2011, at 6:38 PM, Karl Williamson wrote:


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




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.

Re: How can one put a table into a pod

[Russ Allbery]

Karl Williamson  writes:

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

-- 
Russ Allbery (r...@stanford.edu) 

Re: How can one put a table into a pod

[Tom Christiansen]

Karl, sorry, I don't know how deal with tables in pod.
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

Re: How can one put a table into a pod

[Karl Williamson]

On 04/23/2011 09:58 PM, Russ Allbery wrote:

Karl Williamson  writes:


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.



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.

Re: How can one put a table into a pod

[David E. Wheeler]

On Apr 23, 2011, at 6:38 PM, Karl Williamson wrote:

> 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

Re: How can one put a table into a pod

[Russ Allbery]

Karl Williamson  writes:

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

Re: How can one put a table into a pod

[Karl Williamson]

On 04/23/2011 06:23 PM, Allison Randal wrote:

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.


There also doesn't appear to be a way to extend the pod language in a
backwards compatible way.

Am I missing something?


You can subclass Pod::Simple to produce a formatter capable of parsing
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?

Re: How can one put a table into a pod

[Allison Randal]

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.


There also doesn't appear to be a way to extend the pod language in a
backwards compatible way.

Am I missing something?


You can subclass Pod::Simple to produce a formatter capable of parsing 
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

Re: How can one put a table into a pod

[Karl Williamson]

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.

The documentation in perlpod seems to indicate that in

=begin html

Figure 1.

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



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?

How can one put a table into a pod

[Karl Williamson]

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.


The documentation in perlpod seems to indicate that in

  =begin html

  Figure 1.

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