Attention GSoC candidates - post your proposals here for feedback

[yun lee]

Abstract
Mercurial's built-in help is quite good, but could be better. The
improvement on help system contains 4 tasks:
  1.migrate remaining contents from manpages into built-in help;
  2.add example usage to verbose sections in help ;
  3.new feature of 'hg help -k keyword';
  4.improve crosslinking between help topics.



Milestones

The improvement on help system contains 4 tasks, and milestones are
provided in the 4 tasks accordingly:

1.migrate remaining contents from manpages into built-in help

  We hope the built-in help contains as more usable information as
possible, so it's significative to move help information from /doc/ to
the codebase. At this moment, the content about 'Command Elements' and
'Files' in 'hg.1.text' can be moved from /doc/ to /mercurial/help/ as
new independent topics, and the helptable should be updated
accrodingly.

  MileStone:
  One week is planned for this aspect. And the Final patch will be
provided in late May.


2.add example usage to verbose sections in help

  In Mercurial, a markup of '.. container:: verbose' is used to
indicate information just shown in the result of 'hg -v help topic',
such as 'add' command. Example usages can be added in this markup.

  A discussion in the mailing list will be lauched to decide what
examples be added. After that, exmaples will be added into the
built-in help one by one.

  MileStone:
  Two weeks are planned for this aspect. And serials of patches, each
for one command or one topic, will be provided, and this task will end
in middle June.


3. new feature of 'hg help -k keyword'

  Just now, 'hg help' lists all commands and topics. Then how to get
all information on the specified keyword? This is what 'hg help -k
keyword' does. For example, 'hg help -k add' will list all information
on 'add'.

  Then, 3 things should be decided:
  3.1 Where is the information from?
  The source of help info should be the same with the current help
command, containing help for commands, extensions and topics.

  3.2 How to judge a 'help infomation block' hits the keyword
  A block of help content, such as help on a topic, command or
extension, could be called a 'help information block'(HIB), which
consists of a title and a concrete description. For the simplest
situation, we think it hits the keywords if a HIB contains the
keyword.

  3.3 How does the results organize?
  After searching and matching, we get some HIBs. Before display to
users, the aimed keyword in the description of a HIB should be
processed by minrst and then be highlighted, such as embraced by '[]'.
The HIBs can be sorted in this order----commands, topics and then
extentions. We can just list all the HIBs one by one.

  MileStone:
  One month will be spent on it. Two weeks are planned for searching,
and two weeks for the display of result. A final patch will be
provided in middle July.


4.improve crosslinking between help topics
  The task on crosslinking contains:

  4.1 mark more keywords in hg text role to link topics to each other tightly

  4.2 realise hype link supporting for hgweb
  At this moment, crosslinking is just significative for Docutils, as
htmls generated by Docutil can provide hype links. Links processed by
minrst just display in pale "", and the whole content is embraced by
"<pre>". It's better to remove "<pre>" markup, and before displayed
the content should be transformed by a Docutils-Similar module, may be
called DSM. DSM supports simple html transform, as to hgweb, it's
enough to support paragraph(<br>) and hype link(<a>). Maybe some code
can be extracted from DocUtil.

  MileStone:
  One month will be spent on it. One week is planned for adding
markup, and three weeks for simple html supporting. The Final patch
will be provided in middle August.



About Me
I'm a girl master, majoring in Computer Science. I have passed GSOC
2010 with DERBY as my project[1]. And this year, I'm interested in
Mercurial and wish to do some contribution for this smart distributed
VCS.
I have set up the development environment on Ubuntu, read the code
related to help system and done some hacking on it. Furthermore, I
have created some issues on BTS and provied some patches[2.], some of
them are accepted, and some are in queue. Much of my work relates
closely to my proposal title "Improve Mercurial's built-in help".
Besides, in my communication in mailing list and IRC, I have got much
advice and encouragement.




[1.]
https://issues.apache.org/jira/browse/DERBY-4776
https://issues.apache.org/jira/browse/DERBY-4777
https://issues.apache.org/jira/browse/DERBY-4732
https://issues.apache.org/jira/browse/DERBY-3898
https://issues.apache.org/jira/browse/DERBY-4052
https://issues.apache.org/jira/browse/DERBY-4707
https://issues.apache.org/jira/browse/DERBY-4713
https://issues.apache.org/jira/browse/DERBY-4718
https://issues.apache.org/jira/browse/DERBY-4738
https://issues.apache.org/jira/browse/DERBY-4765
https://issues.apache.org/jira/browse/DERBY-4767
https://issues.apache.org/jira/browse/DERBY-2442
https://issues.apache.org/jira/browse/DERBY-3801
https://issues.apache.org/jira/browse/DERBY-4696

[2.]
http://mercurial.selenic.com/bts/issue2751
http://mercurial.selenic.com/bts/issue2734
http://mercurial.selenic.com/bts/issue2732
http://mercurial.selenic.com/bts/issue2749
-- 
Yun Lee