Brad Appleton wrote:
> Thanks for CC:ing the pod-people list (I'm behind in reading news ;-)
> On Tue, Jan 04, 2000 at 08:54:53PM +0000, Reini Urban wrote:
> > Bugs, Future directions of pod2rtf.pl
> ...
> > - A Pod::Parser based pod2rtf and merging with Aldo Capini's Pod::RTF
> > is in the works, but advances are slow.
>
> Let me know what I can do to help with the above (short of writing code,
> I'm still behind on PodParser updates ;-). If you need clarification of
> any PodParser functionality, or think you need an important piece of
> functionality added to PodParser, I'll try to do what I can.
Basically I want to merge RTF::Document and Pod::Parser with
the actual pod2html problem:
links and targets must be well-conformed.
The current state of affairs is only for good-looking rtf's,
but I need winhelp rtf with it's index problems and more gui weirdnesses:
macros, see-also popups, navbar, 2nd windows.
We must do two-passes otherwise we cannot resolve all the links and
match them to the targets.
Performance (size and time) is not a problem for me, so I don't care
that much for additions for callbacks, one-pass, compiler.
So far I have the same huge parse-tree as you in memory.
It's much easier to munge and spit out this tree in a second pass.
So I don't think that I'll need more from Pod::Parser. I'll check it.
But for real-time conversions, as needed by aldo's podview.pl (Win32::GUI)
and some cgi rtf/html creation, a one-pass attempt -maybe without
cross-indexing or only backwards (=known) links- would be a second goal.
hcrtf (and old hc/hcp) links are more strict than links for html urls.
html links fail only on embedded C<> and path slash mixtures:
path\to/page.html. (still unsolved)
So my goal is stricter than pod2html. I'll better wait for a
Pod::Parser based pod2html and use that as base then.
The cache approach as by tom is fine for the perl docs but I don't
need/like that for my other projects.
I'd also like to improve rtf2html (RTF::Parser) to take advantages for
winhelp style links.
And maybe later an addon for automatical indexing against keywords
(html, rtf, texi).
For now I do all the indexing and toc creation manually.
(i.e with short, not generalizable, scripts and editor commands)
e.g. an improved perlguts at my website, various common lisp and more specs.
rtf and html tables are also a major issue (as one can see in text2html).
I solved that for my source->winhelp converters, but for pod I would need a
clever rationale.
So far I generate tables only for the main index on the index page.
(one should see more at a glance, that's why I needed tables)
chm (compressed html) and winhelp generate indices also automatically in
a flat list in a seperate navbar.
pagebreak rationale (just some private winhelp/chm considerations)
-------------------
when to introduce a winhelp pagebreak?
with html it's easy: one page per file. or one page per chapter.
and an automatic toc at the page header.
but users don't like to scroll, on the other side too short pages need
clicking on the back and forth links which is also hard work.
(only solved fine by tex2html with consistent nav buttons)
For the perl winhelp I used a simplified and different approach:
A pagebreak occurs after a list (=back) and on each new file.
This works out fine in practice but is not generalizable for other docs.
automatic tocs at the header as with html typically disturb a
winhelp document because tocs are provided in a seperate navbar. (CNT)
POD itself doesn't need one more structural element just for this case.
I'm happy with perlfunc as one big list but I'm not happy with
=head1 chapters over several pages. Scrolling down is acceptable
for list but not for several long chapters.
with man you scroll down, with texinfo/html you click on the
navbar or toc on the page header.
for winhelp a toc header is only sometimes acceptable. (same for chm)
Probably a user option should decide between --pagetoc or --nopagetoc
--
Reini Urban
http://xarch.tu-graz.ac.at/autocad/urban/perl/
