Re: About the generate_html package

[Julien Bect]

Le 17/08/2014 22:03, Carnë Draug a écrit :
> On 15 August 2014 19:03, Julien Bect <address@hidden> wrote:
> > By the way, the current generate_html package is from october 2012 and
> > several changes have been made to it recently (including the new "NEWS" and
> > "Package Documentation" links, which can already be seen in the doc of the
> > optim package). Perhaps now would be a good time for a 0.2 ? Please tell me
> > if there's anything I can do to help.
> I have just made a 0.1.6 release. I'd reserve a 0.2 release if there's
> an actual change on the structure of the site.

Well, new links have been added, that's why I was suggesting 0.2 instead 
of 0.1.6. Nevermind.

> You mentioned a series of problems on the current website which I
> agree do exist and would welcome fixes for it. Both generate_html and
> the website now have hg repos. The main problem would be that big
> changes would require rebuild of all packages documentation. Since
> most of the changes would be text that is equal on all pages, we could
> work around this by editing the file in places with some per script.

Here is my opinion on this:

1) Since the HTML documentation cannot easily be regenerated by the OF 
website maintainer (it requires the installation of the package, not 
always easy, + sometimes various customizations performed by the 
packages maintainer), it must be considered as part of the source code 
of the website.

2) Assuming no heavy customization of the html generated by 
generate_package_html, it is easy to extract separate the actual content 
of all the existing pages from the header+footer decoration. Actually, I 
already have a script to do it (looking for <div id="doccontent"> 
</div>) and I have done it locally for the 94 packages that are 
currently documented online (61 maintained + 33 unmaintained). Only a 
few problems (<div> without a matching </div>) that I can report later 
if you like.

3) Considering 1) and 2) I would suggest a) archiving the "doccontent" 
part of all the existing documentation on the project-web repository, b) 
extracting the content of the static pages in a similar fashion, and 
then c) writing a script that recreates the website (entirely, or for 
one package only) based on this + the header and the footer.

In this way of doing things, the process for releasing a package would 
be slightly modified (but not more complicated, hopefully). When the 
package maintainer sends its HTML documentation, the OF maintainer would 
simply (I hope) have to run a script that does the following : a) 
separate the content (to be saved) from the header and footer (to be 
discarded); b) replace the old content by the new content on mercurial 
("hg addremove"  should be useful for that) and c) generate the full 
HTML pages from the current header and footer (the package maintainer 
might have used an older version) ready to be uploaded.

A necessary condition for this to work is that package maintainer 
refrain from doing any customization of the HTML generated by 
generate_package_html outside the <div id="doccontent"> </div> pair.

What do you think ? Does it seem like a reasonable plan to you, or am I 
again missing something ?

@++
Julien