[PATCH 3 of 3 v3] hg serve help: HTML output when docutils available

[Mads Kiilerich]

On 10/25/2010 03:33 PM, Erik Zielke wrote:
>     It is nice that the function documents its API - including that it
>     raises ImportError.
>
>     But FWIW I don't think a function ever should "leak" that internal
>     exception. That is not a nice API. Whenever we do an import that
>     might fail, we should explicitly do it in try/except.
>
>     I assume that the UnknownCommand part has a lot in common with what
>     already is done elsewhere.
>
>
> I had try/except around before, and then just raise. Should it be a
> different exception, or would it be better if the command to generate
> the ascii help would just be called here instead. This would put the
> responsibility generating html or rst into this method (which then has
> to be renamed), which then could be moved to e.g. help.
>
>     ...
>
>     But ... do all this belong in webcommands? The focus in webcommands
>     is not generating html but serving html.
>
>     Wouldn't it be better to extend the help module so it can generate
>     html? For example so it in principle would be possible to do "hg
>     help --html add > add.html".
>
>     We always use the templater for generating html. Perhaps it would
>     fit the existing design best if command help could be built into the
>     templater, so that a help "topic" could be referenced in all
>     templates and go through a "rawtexthelp" or "htmlhelp" filter ... or
>     the "best" representation was chosen automatically.
>
>     Hmm. Perhaps we just need a "rst" filter?
>
>
> I think a rst filter would be a good thing.

So the hypothesis is that what you are trying to do with this patch 
series can be done more elegantly with a "rst to html" template filter.

The natural location for such a filter would be templatefilters.py.

The filter could fall back to escaping and wrapping in pre in case 
docutils isn't available.

With that in place webcommands (and commands.help_?) could be changed to 
send the help rst through the templater, and the web templates could be 
changed to use that variable and filter it through the rst filter.

I am not sure how many changes in the help module would be needed, but 
we should avoid cyclic dependencies and also avoid duplicating code 
(especially from commands.help_ and perhaps also from runrst).

I think that would work and be an elegant solution, but if you want your 
patch applied it is up to you to "prove" that whatever you come up with 
is the best solution ;-)

An alternative approach could be to not use docutils on runtime. That 
could be because of its performance or stability - I don't know. Instead 
the html-encoded texts could be generated in the file system on 
make/install time.

/Mads