Dearest monks,

First, a very happy 2007 to you all. May the new year bring more warming of world relations, less warming of the climate, and more exciting Perl in our lives.

I have been building documentation for my programs, and since I am lazy (I am 1/3 of the way there), I want to write my docs in one place only... POD to rescue. Then, I want to generate html, rtf, postscript, quarkexpress, and lithographs all at the click of a button.

I am finding POD to be, well, a bit too plain for my liking, and I am hoping you will assist me.

1. My documentation, when generated into html, follows the same hierarchy as my modules. So, lib::Foo::Bar::Baz.pm results in http://../lib/Foo/Bar/Baz.html. I want to build a breadcrumb trail, but the only way I can figure out to do that is to embed a

=for html 
<div id="title">
  <img src="../../../../images/logo.gif" width="121" height="22"><br /
+>
  My Documentation<br />
  <span class="sub_title"><a href="../../../../index.html">Home</a> &g
+t; lib &gt; Foo &gt; Bar &gt; Baz.pm</span>
</div>
[download]

Obviously, this is less than satisfying as I have to do this in all the modules, adjust the path to index.html and the logo. The question here is -- is there any way I can embed variables in POD that get interpolated when POD (and, by extension, pod2html) is generated?

Lists in POD are less than satisfying as well. They result in

<ul>
<li><p>item one</p></li>
<li><p>item two</p></li>
</ul>
[download]

What's with those p tags? Do I have to go tinker with POD::HTML?

Update 1: adjusted list items as per ikegami's suggestion. Really wanted to *not* have those p tags appear, but diddling with stylesheets is more or less satisfactory.

Then, even though I have enabled --noindex option, I get

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<!--
<ul>
    <ul>
        <ul>
            <li><a href="#name">NAME</a></li>
            <li><a href="#version">VERSION</a></li>
            <li><a href="#synopsis">SYNOPSIS</a></li>
            ..
        </ul>
    </ul>
</ul>
-->
<!-- INDEX END -->
[download]

The index is still generated, just that it is hidden. What's with that?

Update 2: Building a breadcrumb trail, and getting around the index at the top of the page was achieved by first writing out all the html files, then opening them again, and replacing the index with a header and breadcrumb trail, and writing them out again. Kludgy, but works.

There are several other issues, but I will stop here for now. I guess, in other words, I am looking for a tutorial on creating customized, beautiful html documentation, as well as RTF documentation from POD... Powerful One Documentation.

Many tia.

Update 3: Having stellar documentation tools to be able to create stellar documentation will be a great boon. I hope the new year will bring such tools into the world of Perl.

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.