• Submitted patches

Improve Mercurial's built-in help

• Student Name: Yun Lee]

• Contact: <yun.lee.bj AT SPAMFREE gmail DOT com>, yunlee on #mercurial

Organization/Project: The Apatch Software Foundation/ Mercurial

Proposal 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.

Detailed Description:

• A.Who am I?

  • I'm a master from Graduate University of Chinese Academy of Sciences, you can visit my college on 'http://www.gucas.ac.cn/gscasenglish/index.aspx'. I major 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.

  B.What have I done with Mercurial?
  • 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.
  C.How can I plan this GSOC on Mercurial.
  • The improvement on help system contains 4 tasks: 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. 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. 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.

  • 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.

• 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.

  • 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.

• [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

2