Re: [be] Documentation

[Teus Benschop]

Hi Peter,

These two scripts do a wonderful job!

How have we been struggling with getting the pages off the Google Wiki,
and how easy it now has become, thanks to your sweat!

I am quite satisfied with the system you used to download the data, and
to re-assemble the xml file into the html pages, and to create a menu
and add it to each page. I feel that the menu is basic and more than
sufficient to navigate nicely through the pages. As for me, this is all
that is needed - no javascript or anything else to bloat the pages.

The style sheet looks good too. It allows the reader to concentrate on
the information provided, and not to get distracted by the bells and
whistles.

I had to install a couple of libraries on Ubuntu, and then the two Perl
scripts ran well, and a fine site was created.

I can update the link to the license file, or create one since it
probably does not yet exist in the form that the scripts require.

Shall I add the scripts and files you created to the Bibledit-Gtk
sources?

With thanks,

Teus


On Tue, 2011-06-07 at 18:03 +0100, Peter von Kaehne wrote:
> Dear Teus,
> 
> Attached is a zipped collection of 4 files:
> 
> 1) retrieval.pl
> 
> This copies via the Google sites' API the pages, does some minor
> cleaning up and creates a large XML file with the complete content
> ("site.xml").
> 
> 2) menus.pl
> 
> This works on the "site.xml" XML file and re-creates a site, using the
> additional files "license" and "style.css". The site is functional, has
> the complete content AFAICT, internal links are working (if not
> elegantly so) and the menus are as I discussed, simple and functional
> (Home, Parent, siblings and children). A bread crumb thread would be
> nicer, really complete and JS driven menus would be perfect.
> 
> I have separated the two tasks (retrieval and recreation) as latter
> needed a lot of fine tuning and repetition, but did not need the very
> lengthy repeated download again and again. Keeping it separate makes
> probably continued improvement easier.
> 
> 3) the license text is a short preamble taken from the EFF website re
> GFDL and what should be in a file. The link to the GFDL needs
> correcting, please. Not sure where you store it
> 
> 4) the style sheet is primitive. It can benefit from work. But it works
> 
> So, this is task (1 - retrieving) and task (2 - creation of a HTML
> collection with menus) complete. You now have Debian compliant HTML
> documentation. What this documentation lacks in comparison to the
> previous one (but not Debian compliant) is  the much poorer menu and the
> lack of a search function.
> 
> The Perl I wrote is probably abysmal, but the best I can do, in fact I
> worked well beyond the comfort zone + constantly looked things up and
> learned more.
> 
> I obviously welcome critique and improvements. I have used a bunch of
> modules, most but 1 or 2 seem to be part of a normal Ubuntu system. The
> rest is easily installed via synaptic.
> 
> (3) - creation of DocBook XML remains. I will give this a go now, but
> please do not wait for that. This would recreate really decent menus and
> decent search by using provided system facilities.
> 
> Peter
>