Re: How can one put a table into a pod
On Sun, May 01, 2011 at 10:07:46PM -0600, Karl Williamson wrote: 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 Jcenter Jspan 2 This is a wide, centered cell! (Where J is whichever of the available letters is most appropriate.) Ronald
Re: How can one put a table into a pod
On 11-05-04 03:16 PM, Ronald J Kimball wrote: =cell Jcenter Jspan 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 Jcenter Jmiddle Jrowspan 2 jcolspan 2 paragraph -- Just my 0.0002 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.
Re: How can one put a table into a pod
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. How about adding some modifiers to the PseudoPod tags, such as: =row center =row right =cell span 2 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
Re: Bad `=for` spec (WAS: How can one put a table into a pod)
On 04/24/2011 06:19 AM, Shawn H Corey wrote: I have just taken a look at this. They totally screwed up `=for`. A `=for` paragraph does not need a `=end for`. That was a decision made by the early developers of PseudoPod, and I kept it in my implementation for backward compatibility in parsing old O'Reilly manuscripts. It's entirely optional, though, and entirely separate from table parsing. It's kind of fundamental to the nature of subclassing that you can override any behavior you want. :) Allison
Re: Bad `=for` spec (WAS: How can one put a table into a pod)
On 11-04-26 01:06 PM, Allison Randal wrote: 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. -- Just my 0.0002 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.
Re: How can one put a table into a pod
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. 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
On Apr 25, 2011, at 8:09 PM, Karl Williamson wrote: 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
Re: How can one put a table into a pod
On Apr 25, 2011, at 8:39 PM, Russ Allbery wrote: 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
Re: Bad `=for` spec (WAS: How can one put a table into a pod)
On 11-04-23 08:23 PM, Allison Randal wrote: 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.0002 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.
How can one put a table into a pod
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 brFigure 1.brIMG SRC=figure1.pngbr =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?
Re: How can one put a table into a pod
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 brFigure 1.brIMG SRC=figure1.pngbr =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?
Re: How can one put a table into a pod
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
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
Karl Williamson pub...@khwilliamson.com 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) http://www.eyrie.org/~eagle/
Re: How can one put a table into a pod
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
On 04/23/2011 09:58 PM, Russ Allbery wrote: Karl Williamsonpub...@khwilliamson.com 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
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 pub...@khwilliamson.com 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) http://www.eyrie.org/~eagle/
Re: How can one put a table into a pod
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
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
