[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: About the generate_html package
Re: About the generate_html package
Tue, 19 Aug 2014 02:31:51 +0100
On 18 August 2014 21:52, Julien Bect <address@hidden> wrote:
> Le 18/08/2014 19:17, Julien Bect a écrit :
>> 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"
>>>> "Package Documentation" links, which can already be seen in the doc of
>>>> optim package). Perhaps now would be a good time for a 0.2 ? Please tell
>>>> 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.
I have pushed your patch. Thank you.
On 18 August 2014 18:17, Julien Bect <address@hidden> wrote:
> 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"
>>> "Package Documentation" links, which can already be seen in the doc of
>>> optim package). Perhaps now would be a good time for a 0.2 ? Please tell
>>> 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
This does not mean it should be committed to the repository. You can
consider that the website we have live is one build and given
different options (different graphics toolkit to run the demos,
different versions of Texinfo that create different html).
> 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 ?
The repository with the website would grow in size very quickly. It's
not only html pages, there's also the images from running all the
demos. And at the moment there's around 100 packages in there. And
this would solve the problem of having a complete backup of the
website under revision control (I'm using rsync now to do it), but not
the problem of easily changing style, fix links on the headers, etc.
I think that a better approach is to not have the generate_html
creating any header and footer at all. The generated_html could either
be an html page that would only have a small header plus an include at
the top and bottom and include them them with php. If the
generated_html is properly labeled, it would be easy to control the
style with CSS. Pretty much everything from the start of the page
until "doccontent" could be replaced with an include, even the page
Alternative, it could simply be pieces of html (not an html page), and
there'd be a php that would take as argument the page to be displayed
and would simply echo it. All the style could then be kept on that
single page. But I'm unsure about the safety of this one, it may be
slower if it needs to find the page every time, and makes it hard to
give links to others, so I'd prefer the previous.