GSoC : Draft proposal - Improve built-in help

Shayan Md mdoshayan at gmail.com
Sun Apr 3 20:26:18 CDT 2011


On Sat, Apr 2, 2011 at 10:26 PM, Matt Mackall <mpm at selenic.com> wrote:

> On Sat, 2011-04-02 at 17:11 +0530, Shayan Md wrote:
> > Improve built-in help:
> >
> > I am a grad student from IISc banglore. I worked on some web
> > development projects before. I am fairly good at python. I would like
> > to contribute to mercurial in this summer and also be part of Google
> > Summer of Code. I am interested in improving built-in help.
> >
> > Deliverables:
> >
> > * Cross linking between help topics
> > * Mange pages in built-in web help
> > * Example usage in verbose section in help
> > * Improved glossary
> > * Better mercurial web view
>
> The topics on our Ideas page are definitely meant as project
> suggestions, not as outlines. You should shape your proposal in a way
> that makes sense to you.
>
> > 2. Migrating remaining contents from man pages to built-in help
> >
> >    http://www.selenic.com/mercurial/hgrc.5.html is the html generated
> > man page of hgrc. Displaying this page in help section.
> >
> >    Doing the same for hgignore and hg.1
> >
> >    Implementation: Probably this can be done by writing something
> > similar to doc/gendoc.py in hgewb/ or help module in mercurial
>
> You need to familiarize yourself with the way the command line help
> system works and how most of the manpages are built from it. The goal
> here has nothing to do with hgweb or HTML - it's more general.
>

I think 'hg help command' generated output is the docstring of the command
and options are generated using table of options and globalopts for -v.
Same for extensions. For other topics it reads text files from help
directory using the code in help module. This is implemented
commands.help_(). Same function is used in webcommands in hgweb. I can't
mention all this in proposal. Can I?

I was talking about hgrc and hgignore man pages display in web. (I am sorry,
I was wrong about hg man page) I have to re-format those rst files in doc/.
I can  do this using docutils. It is already written. So, I mentioned I
should port that code to hgweb.

>
> > 5. Improve HTML rendering in hgweb view:
> >
> >    I don't understand what kind of improvements you expect. Once that
> > is clear I can think of implementation
>
> Look at this page and note how everything is <pre> formatted:
>
> http://www.selenic.com/hg/help/add
>
> Now compare it with this:
>
> http://www.selenic.com/mercurial/hg.1.html#commands
>
They're both generated from the same source:
>
> http://www.selenic.com/hg/file/0995eee8ffe4/mercurial/commands.py#l21
>

I see. I got the idea.

>
> --
> Mathematics is the supreme nostalgia of our time.
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://selenic.com/pipermail/mercurial-devel/attachments/20110404/e8a50ac5/attachment.htm>


More information about the Mercurial-devel mailing list