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