GSoC : Draft proposal - Improve built-in help

[Shayan Md]

On Mon, Apr 4, 2011 at 7:16 PM, Matt Mackall <mpm at selenic.com> wrote:

> On Mon, 2011-04-04 at 06:56 +0530, Shayan Md wrote:
> > 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.
>
> That's about half true. One piece you're missing is that we've got a
> rather elaborate internal formatting engine. Another piece is that all
> of it gets our i18n treatment. You wrote:
>
> "http://www.selenic.com/mercurial/hgrc.5.html is the html generated
> man page of hgrc. Displaying this page in help section."
>
> This is just not a good statement of the problem or solution. For
> starters, HTML is not part of the problem, so if you're talking about
> HTML, your reader knows you don't understand what's wanted.
>

I am not talking about HTML.

>
> What's wanted is to move the ReStructured Text markup from doc/ into
> Mercurial's codebase. Ideally, this is done in such a way that the docs
> live in the .py files next to the code that implements them, like the
> add command.
>

This is exactly what I intended.

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