GSoC : Draft proposal - Improve built-in help

[Matt Mackall]

On Tue, 2011-04-05 at 03:06 +0530, Shayan Md wrote:
> 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.

I've literally quoted you talking about HTML from your original draft.
Stop arguing with me and fix your draft.

-- 
Mathematics is the supreme nostalgia of our time.