GSoC : Draft proposal - Improve built-in help

[Shayan Md]

On Tue, Apr 5, 2011 at 3:10 AM, Matt Mackall <mpm at selenic.com> wrote:

> 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.
>
I apologise. It was not my intention to argue with you. I am sorry.


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