New module name? Pod::Pdf2

[Lee]

Apologies if this is posted to the wrong place. Also posted to the
module list.

I have an almost-publishable module to turn POD into PDF. Pod::Pdf is
rather old, doesn't handle multiple files nicely[1], and is very hard
to extend since it uses neither Pod::Parser nor PDF::API2.

Thinking of calling the module Pod::Pdf2.

[1] I have submitted an updated version to the Pod::Pdf author, to both
publish his =inclue POD extnesion for including multiple files, and to
allow a POD PDF of a (recursed) directory, but wrote the new module in
the week sine.

[John Bokma]

"Lee" <leegee@gmail.com> wrote:

> Apologies if this is posted to the wrong place. Also posted to the
> module list.
>
> I have an almost-publishable module to turn POD into PDF. Pod::Pdf is
> rather old, doesn't handle multiple files nicely[1], and is very hard
> to extend since it uses neither Pod::Parser nor PDF::API2.
>
> Thinking of calling the module Pod::Pdf2.
>
> [1] I have submitted an updated version to the Pod::Pdf author, to both
> publish his =inclue POD extnesion for including multiple files, and to
> allow a POD PDF of a (recursed) directory, but wrote the new module in
> the week sine.

How about trying to contact the author and see if he's willing to let you
maintain Pod::Pdf? That way you can put your new module into action
without adding another module to CPAN. Especially if it's possible to
support all old methods.

Personally I think that cluttering CPAN with almost similar modules is a
bad idea, even if they are better.

--
John Bokma Freelance software developer
&
Experienced Perl programmer: [url]http://castleamber.com/[/url]

[Lee]

John Bokma wrote:

> "Lee" <leegee@gmail.com> wrote:
>

> > ... I have an almost-publishable module to turn POD into PDF. Pod::Pdf is
> > rather old, doesn't handle multiple files nicely[1], and is very hard
> > to extend since it uses neither Pod::Parser nor PDF::API2.
> >
> > Thinking of calling the module Pod::Pdf2.
> >
> > [1] I have submitted an updated version to the Pod::Pdf author, to both
> > publish his =inclue POD extnesion for including multiple files, and to
> > allow a POD PDF of a (recursed) directory, but wrote the new module in
> > the week sine.

>
> How about trying to contact the author and see if he's willing to let you
> maintain Pod::Pdf? That way you can put your new module into action
> without adding another module to CPAN. Especially if it's possible to
> support all old methods.
>
> Personally I think that cluttering CPAN with almost similar modules is a
> bad idea, even if they are better.

I quite agree about cluttering with near-identical modules.

I'm not sure I'd call my module 'better' - rather it is clearer to the
average non-PDF-reader (like myself) since it does not write direct PDF
like Pod::Pdf, but uses the excellent perl interface (PDF::API2). It
also sub-classes Pod::Parser, which makes extension quite easy.

Doesn't that count as additionaly functionality...?

I'd not want to overwrite the existing module, though, it produces such
beautiful output....

[James E Keenan]

John Bokma wrote:

>
>
> How about trying to contact the author and see if he's willing to let you
> maintain Pod::Pdf?

Ironically, about 12 months ago I contacted Alan Fry about just that. I
had discovered bugs and figured out work-arounds and was hoping that the
module would continue to be developed. Particularly because I write my
conference talks in POD but often have to present them either as HTML
slides or PDF text.

Mr Fry wrote me with a long history of the development of Pod::Pdf. Let
me quote a few paragraphs:

"The best approach IMHO is pod2latex plus tex2pdf. A simple 'bash'
script produces a PDF file about as quickly as pod2pdf. Typography is a
matter of opinion, but I reckon LaTeX takes some beating. An added bonus
is of course that there are other '.tex' translators available, for
instance tex2ps/html/text.
....

"So I really don't know what is best to be done with Pod::Pdf, if
anything, which is basically why I have done nothing for the last few
years. If you can see a way through the maze I would be content for you
to take over the maintenance.
....
"But I would suggest, before you invest your life in the project you
have a word with Jon Allen and Wybo Dekker (particularly) to see what
they're thinking about to avoid undue duplication. If you do decide to
take it over I would certainly do my best to help."

In other words, he didn't think that Pod::Pdf in its current form was
worth a whole lot of effort. But he did lay out some direction for its
recuperation. Since I didn't know a lot about Latex (and still don't),
I felt that I wouldn't have been the best person to tackle the job.

So, if anyone is interested in taking over maintenance, I would
recommend contacting Alan Fry as well as the two others he named.
Contact me off line (jkeenan [at] cpan [dot] org) if you want to read
more of what Fry wrote me.

Thank you very much.
Jim Keenan

[John Bokma]

James E Keenan <jkeen_via_google@yahoo.com> wrote:

> In other words, he didn't think that Pod::Pdf in its current form was
> worth a whole lot of effort. But he did lay out some direction for its
> recuperation.

But do you think it's possible that your current Pod::Pdf2 module can
replace Pod::Pdf?

If so, I still would recommend to do so. If there is another way, but no
one is willing to pick it up CPAN has an outdated Pod::Pdf which can be
considered dead, and a new Pod::Pdf2, which might become obsolete one day,
and might be very well a better alternative to Pod::Pdf in the mean time.

The nice thing about modules is that the implementation is hidden, so if
Pod::Pdf2 can be made 1:1 compatible interface wise with Pod::Pdf, I would
certainly recommend to consider it an update to Pod::Pdf instead of a new
module that lives along Pod::Pdf.


--
John Bokma Freelance software developer
&
Experienced Perl programmer: [url]http://castleamber.com/[/url]

[James E Keenan]

John Bokma wrote:

> James E Keenan <jkeen_via_google@yahoo.com> wrote:
>
>
>
> But do you think it's possible that your current Pod::Pdf2 module can
> replace Pod::Pdf?
>
>

Let's first see what Lee hears from the author of Pod::Pdf. IIRC, I
simply did a few small bug fixes. If Lee can do more than that, that
would be preferable.

jimk

[Lee]

James E Keenan wrote:

> John Bokma wrote:
>

> > How about trying to contact the author and see if he's willing to let you
> > maintain Pod::Pdf?

>
> Ironically, about 12 months ago I contacted Alan Fry about just that. I
> had discovered bugs and figured out work-arounds and was hoping that the
> module would continue to be developed. Particularly because I write my
> conference talks in POD but often have to present them either as HTML
> slides or PDF text.
>
> Mr Fry wrote me with a long history of the development of Pod::Pdf. Let
> me quote a few paragraphs:
>
> "The best approach IMHO is pod2latex plus tex2pdf. A simple 'bash'
> script produces a PDF file about as quickly as pod2pdf. Typography is a
> matter of opinion, but I reckon LaTeX takes some beating. An added bonus
> is of course that there are other '.tex' translators available, for
> instance tex2ps/html/text.
> ...
>
> "So I really don't know what is best to be done with Pod::Pdf, if
> anything, which is basically why I have done nothing for the last few
> years. If you can see a way through the maze I would be content for you
> to take over the maintenance.
> ...
> "But I would suggest, before you invest your life in the project you
> have a word with Jon Allen and Wybo Dekker (particularly) to see what
> they're thinking about to avoid undue duplication. If you do decide to
> take it over I would certainly do my best to help."
>
> In other words, he didn't think that Pod::Pdf in its current form was
> worth a whole lot of effort. But he did lay out some direction for its
> recuperation. Since I didn't know a lot about Latex (and still don't),
> I felt that I wouldn't have been the best person to tackle the job.
>
> So, if anyone is interested in taking over maintenance, I would
> recommend contacting Alan Fry as well as the two others he named.
> Contact me off line (jkeenan [at] cpan [dot] org) if you want to read
> more of what Fry wrote me.

You don't feel you want to take it over yourself, Jim?

My opinion about *a* pod to pdf convertor is that it should not try to
be fast, since this is far from a real-time application. Neither do I
feel latext or any other mark-up/typography system is relevant to a pod
to pdf convertor.

I would very much emphasise that typography is a matter of opinion,
though, and so my own Pod::Pdf2 uses as many user-suppliable variables
as possible, to control the formatting of headings, paragraphs, page
size, content, table of contents: line spacing, font faces and styles.
For my own ease these can be supplied through a script or sub-classing
or as an XML file (love is not too strong a word for my feelings
towards XML::Simple).

My use of a pod to pdf convertor is mainly for project documentation,
which is why I adjusted the current Pod::Pdf to reveal it's internal
"=include" feature, as well as to parse directory trees into a "book."
My problem with it is that it is basically a script turned into a
module in a hurry. It really does need a complete rewrite, since there
are global variables floating around all over the place (ugly, immoral,
and a pain for when I will write my Apache::Pod::Pdf service). There is
no way I could volunteer to properly clean it up and/or maintain it,
since my knowledge of raw PDF is just not good enough, and I currently
cannot justify investing time to improve my knowledge.

Which is why I have taken the PDF::API2 route, and combined it with
Pod::Parser.

Certainly one day I may no longer be available to maintain my
Pod::Pdf2, but I have tried to write clean, clear OO code, and the use
of these two well-known and well-maintained modules would certainly
help anyone else maintain the module.

Anyway, Pod::Pdf2 is available, just not yet on CPAN. It works nicely,
it is reasonably clean and getting cleaner over the devlopment
itterations. It is quite customisable and getting more customisable. It
also *requires* no more user input than
Pod::Pdf2::new->parse_from_file($_)->save().

Different philosophy to Pod::Pdf, though.

I'm rambling and will stop now....Sundays....
Lee

[Lee]

Since lasting posting, I completely refactored by subclassing the
Pod::Parser, Pod::Checker.

The advantages are that the active maintainance of the two base classes
ensures my pod-to-pdf parser remains relatively free of bugs,
maintained by experts in the field (check-out their authors).

It also means slightly unweirldy code, in the manner of Pod::Checker.

Currently my pod-to-pdf module renders via PDF::API2* but unless I can
be bothered to get my head around that module's 'streaming' of data, Im
considering reaping the current Pod::Pdf, and merging it with my
current features, because my current understanding of the nature of
PDF::API2 is that it does not really support rendering either formatted
blocks of text nor serialised data. My code can make it perform as
reqired, but it was a pain in the neck to write, and will be a pain in
the foot to maintain. I think it is fair to say POD deserves a more
typographical system, and in my limited experience and vague memories
of University LaTEX seminars/assignments, I think something along those
lines is perhaps called for. I shall certainly give it a try, and post
here again.

Those current features are rather ephemera once the POD syntax checks
and PDF renderng have been done. I spent a fair amount of time writing
routines to corretly flow first a line then a pargraph then two columns
of text in PDF::API2 - no-one seems to have made anything fully
functional public, and with the experience behind me, I can almost see
why.

The ephemeral features are:

* Automatic document table of contents. Easy but nice to have. It's an
option, and is not created unless requested.

* User-defined XML-based stylesheets to set formatting to each POD
element, from textblock, thourgh all the headings, to inline POD
sequences for italic, bold, and so on. Each style has settings for font
face, variation and style, as well as line and, when apt, block layout
spacing.

* Implimentation of POD's X<...> index sequence to (optionally) create
an index that is appended to the POD PDF. This has been extended to
index the 'n' most infrequent words used, where 'n' is a number of the
users choice, and defaulting to about five for each page in the
document.

As you can probably read, I was involoved in project documentation at
the time. It seemed very handy to produce an auto-indexed,
clearly-formatted document containing the POD for every module. As a
consequence, I may have missed something: please do point it out.


Lee