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
_______________________________________________
http://lists.parrot.org/mailman/listinfo/parrot-dev
