GSoC Status Update
Hello everyone, Another week has passed and it is time to update all of you on my status. As per usual, the irc meeting with my mentors that I had today is available athttps://github.com/rjbs/TPF-GSoC-Pod . I excitedly announce that I have a working version of the new Pod::Html! It successfully takes a pod file and converts it to html via Pod::Simple (no more home made parser, woohoo!). Although it currently implements a lot of the old Pod::Html's features, there is still some work to do on it. The biggest feature I need to implement, the one I have been working on for more than I should have, is the cross referencing. I am not going to explain what is confusing me right now, as I will be doing that in an email I am going to compose shortly after this one, which will be addressed to pod-people. Once I get that figured out, I am going to reimplement the --norecurse feature of Pod::Html which I had removed to simplify the transition. I believe I will have to subclass Pod::Simple::Search to add a --norecurse feature there, and then just pass the global $Recurse from Pod::Html to my subclass of ::Search. And, of course, I need to do testing. I am confident in the tests that I have already made, but once I finish the crossreferencing I will be doing many more. There are some things that I am not going to have time for (during the summer, anyway). Pod::Html used to automatically determine the title of the html page. Pod::Simple::Xhtml does not offer such a feature, and although I want to implement it, I fear doing so would take time away from future modules to convert. In addition, I wanted to add the cache feature back in, but I will not have time. If any of you want to take a gander at my progress (or lack thereof, if you are mean), it is available on my github, https://github.com/marcgreen. I welcome any and all questions. Thank you, Marc
Pod::Html's use of --htmldir and --htmlroot for cross referencing
Hello,
I am having difficulty understanding how Pod::Html uses --htmldir and
--htmlroot. Rather, I understand how it uses them in the code, but I cannot
grasp their overall function or purpose. Do any of you have experience with
this matter or have knowledge that can be shared? Below is an example of my
confusion.
-
The documentation says that --htmldir
"Sets the directory in which the resulting HTML file is placed. This is used
> to generate relative links to other files. Not passing this causes all links
> to be absolute, since this is the value that tells Pod::Html the root of the
> documentation tree,"
>
but that still leaves questions. If $Htmldir sets the directory in which the
resulting file is placed, does that mean it will move it there, or does that
mean I need to repeat the path of the --outfile, as that is where the
--outfile will be? What is the point of that? Further, is it essentially a
boolean switch to determine if I want absolute or relative paths? Are there
any other factors that determine if the path is relative or absolute?
The comments of Pod::Html describe --htmldir as
"The directory to which the html pages will (eventually) be written."
Why is "pages" pluralized? Is --htmldir supposed to be the directory where
all the cross referenced .html pages are? Is the resulting file written
elsewhere but moved there later?
The explanation given in the usage of Pod::Html says that
"--htmldir - directory for resulting HTML files,"
which hints that it should be the directory where all the .html files that
are cross referenced live. Either that, or Pod::Html converts more than one
pod file at a time, which I do not believe is true.
-
I am faced with similar questions regarding --htmlroot, but I don't see a
point in listing them right now.
Some background information: I am in the middle of converting Pod::Html to
use Pod::Simple instead of its own parser. The feature that I am currently
migrating is the cross referencing of links. I use Pod::Simple::Search to
find all POD files in @Podpath, and using a hash of { name => path } of the
POD files I need to correctly link to them from the resulting html file. My
work is on github, https://github.com/marcgreen/pod-simple for the subclass
of Pod::Simple::Xhtml that I use, and https://github.com/marcgreen/perl for
the new Pod::Html.
I appreciate any help given,
Marc
