otto has asked for the wisdom of the Perl Monks concerning the following question:

POD is nice, especially if one is familiar with writing man pages in *roff.

But sometimes I really would like to add images. The old saying of a picture is worth a 1000 words can be quite true.

Thoughts, pointers, other people's adventures/mis-adventures would be appreciated. And what might it be like to have images in the pod as seen thru cpan...

Update
So far I've gotten 2 replies that have pointed to ascii images, which indicates I really did not ask my question quite right. I would like to utilize actual images (eg gif, png, svg, ...) type images.

My only current solution is to embed a url and have the user click on it. But if you distribute the file, then it will always go to the same url. But it would be nice to have the images delivered with the other code/pod and have the url go to that local copy. Regards,

Update
More specifically, suppose I make a nice image file, png say, and include that in a distribution and upload it to cpan. How can I write the pod so that when the pod is displayed in cpan, the image shows up in the html.
..Otto

Replies are listed 'Best First'.
Re: pod and images
by almut (Canon) on Dec 08, 2008 at 01:25 UTC

    AA-lib  :)

    There was also a similar on-line service jpg2asc, it doesn't seem to work at the moment, though — but you get the idea...

[reply]
Re: pod and images
by CountZero (Bishop) on Dec 08, 2008 at 06:23 UTC
    POD and its representation is not the same!

    Adding links to POD is trivially simple thanks to the =begin formatname ... =end formatname or (which is the same) =for formatname commands. And of course L<name> already supports links.

    But that is all beside the point. It are the Pod Processors who make any meaning out of the POD-commands.

    Just write a new type of Pod Processor supporting graphic links (which is a SMOP) and make it so succesful that it replaces the current generation of Pod Processors and you're done!

    CountZero

    A program should be light and agile, its subroutines connected like a string of pearls. The spirit and intent of the program should be retained throughout. There should be neither too little or too much, neither needless loops nor useless variables, neither lack of structure nor overwhelming rigidity." - The Tao of Programming, 4.1 - Geoffrey James

[reply]
[d/l]
[select]
Re: pod and images
by oko1 (Deacon) on Dec 08, 2008 at 02:03 UTC

    Here's a rather nice gadget - from right here at PerlMonks - that might do: EasterRock: your custom ascii art maker. I've played with it a little and liked it.

    Note that EasterRock generates HTML as output. Converting it to plain text would be a SMOP :) - you could either parse it or modify the module so it doesn't HTMLify the output.


    --
    "Language shapes the way we think, and determines what we can think about."
    -- B. L. Whorf
[reply]
Re: pod and images
by LanX (Saint) on Dec 08, 2008 at 19:05 UTC
[reply]
      I was interested and fiddled abou it. And this seems to work without any extra podparser.

      Download this code to pod_img.pl 

      for (1.10) {
  print;
}

=for html 
   <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAAyCAY
+AAAAeP4ixAAAAAXNSR0IArs4c6QAAAAZiS0dEAP8A/wD/oL2nkwAAAAlwSFlzAAALEwAA
+CxMBAJqcGAAAAAd0SU1FB9gEEgIJDgjXTxYAAAE3SURBVGje7VhBDsMwCAPU/3+ZXbdKC
+RDMlLRwjJBqg4lpWFWVioOZqz9BQg+JxxC5bhKAaWAkWVVloGS1pXWEtKJSYfB19C2VqB
+QlqXetJDE7DxOxwCLIWGA9ZAQBMkPGW3Er7/m3VrTKK13xdsOT3z5yDJGoR6x4SnRdmeW
+/Q1reKmcc3tsVK0+yIBFrigXSQ1YyFQev/Zzp2FU5zNXD3z6yc3C/orS0mshcvkRUPiN/
+GMOW1nbx4+xKwFdAGvzNMeHuYqV+aTxDWlGpIKV4l0pUipLR+3AOUCRm5+EfKwMshIwF1
+kFGECBTZJwVt/Je8BwUrPJSVzS4Hk3y20eOIRL1iCVPia4rk/x3SMtb5ZTDe7ti5EkWJG
+RNscg4yEqm4tBdawTW2bGrdJirh799ZOPoV5Td4gPKYZdm2PperwAAAABJRU5ErkJggg=
+=" title="img-tag, normal" alt="Inlineimage">

print "dummycode";

      [download]
      and call 
      pod2html pod_img.pl >pod_img.html

      [download]
      the resulting html-file shows an image in most modern browsers! (Officially also in IE7, but I couldn't test it! So please tell me if ...)

      PLEASE NOTE: The image data is in one long line, the linebreaks were inserted by the perlmonks-formatter.

      Cheers Rolf

[reply]
[d/l]
[select]

        How did you create the src string?

        "data:image/png;base64,iVBORw0K...=="
[reply]
[d/l]
Re: pod and images
by jmcnamara (Monsignor) on Nov 18, 2011 at 00:37 UTC

    You can get search.cpan.org to display an image if the HTML is embedded in the Pod on a single line like this: 

    =pod

... some Pod here

=begin html

<p><center><img src="http://jmcnamara.github.com/excel-writer-xlsx/ima
+ges/examples/rich_strings.jpg" width="640" height="420" alt="Output f
+rom rich_strings.pl" /></center></p>

=end html

... more Pod here.

=cut

    [download]

    You can see the result here. Metacpan also supports this.

    The image above links off-site to a GitHub repository but you could probably link back to search.cpan.org by working out the final destination of the images when expanded on the site. You can also use this method for local documentation and images.

    --
    John.

[reply]
[d/l]
Re: pod and images
by JavaFan (Canon) on May 01, 2009 at 09:40 UTC
    The old saying of a picture is worth a 1000 words can be quite true.
    I'd like to point out that the IETF's RFC have been distributed as plain text since 1969. The few images that are present are ASCII, fixed font width images.

    There are many reasons for this. Using plain text makes that documentation written 40 years ago can still be read without problems. Furthermore, making it hard to create images forces the authors to write clear documentation. Also, there are programmers/admins that are visual impaired, or even blind. Translating plain text to sound or Braille is a problem solved long time ago. Translating images to sound or Braille is an open problem.

    BTW, my posting contained far less than a thousand words. Can you replace my posting with an image that tells the same message? (Disallowing images that just contain the words of my posting). Just because it may take a 1000 words to describe an image doesn't mean any 1000 word message can be told with an image.

[reply]
[reply]

Back to Seekers of Perl Wisdom