html_cleanup branch ready to merge
James E Keenan
jkeen at verizon.net
Sun Jan 9 16:01:25 UTC 2011
Michael Hind wrote:
> Hi,
>
> The html_cleanup branch is ready to merge.
Mike,
On behalf of all the Parrot developers, I would like to thank you for
your long and considerable efforts in this cleanup effort.
>
> Can parrot developers have a look at the branch and see if you encounter any
> problems there.
>
I called 'make html' and then inspected the locally created HTML in my
browser. I scanned about half of the pages that are linked to from the
index page and they look good.
> tools/docs/make_html_docs.pl
>
> this uses .json files in docs/index/*.json to generate the .html files
>
> index.json is for the main (Home) page of the documentation, the other files
> there are at group header pages linked to the index page. At the moment,
> they are all linked to the index page.
>
> Individual page titles are taken from either the title in the *.json file,
> or directly from the .pod.
Am not a JSON expert, but this works for me.
This is different in that in the previous
> incarnation of make html there are a whole bunch of files in lib/Parrot/Docs
> which were uses to generate the .html files. Now only
> lib/Parrot/PodToHTML.pm and HTML_Page.pm are needed. We can look at
> removing the other files after the merge.
>
What would be the rationale for postponing deletion of files (e.g.,
lib/Parrot/Docs/POD2HTML.pm) until after the merge? Which files are no
longer needed by 'make html'? Are they used anywhere else in Parrot?
If not, they're dead code; let's rip them out now.
> I would like some comments on tools/doc/make_html_docs.pl, this script was
> originally written by Coke and I had to hack it quite a lot to generate the
> index/header files. There are probably better ways of doing some of the
> steps, but I was time constrained to a certain extent so some perusal might
> be a good idea.
tools/doc/make_html_docs.pl currently works, but its Perl could probably
be improved along the following lines:
transform_input() is not fully encapsulated. $target_dir and
%file_titles are used within it but declared outside its scope. This
makes subroutine declaration dependent on its position in the file.
Since adding $target_dir and %file_titles to the argument list for
transform_input() will make that list grow to 5 members, consider having
transform_input() take a single hashref of key-value pairs.
However, it looks like %file_titles is being assigned to within
transform_input() and then being looked up in later on. If so, this is
a case for making %file_titles the data structure in an object,
extracting subs into a class, and reducing tools/docs/make_html_docs.pl
to a series of method calls.
But I don't think making this program more elegant needs to be done
before the merge.
Thank you very much.
kid51
More information about the parrot-dev
mailing list