GSoC : Draft proposal - Improve built-in help

[Matt Mackall]

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.

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. 

-- 
Mathematics is the supreme nostalgia of our time.