Improve Mercurial's built-in help
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.new feature of 'hg help -k keyword'; 3.add example usages to verbose sections in help; 4.mark up more keywords in hg text role to link topics to each other tightly 5.Improve HTML rendering in hgweb view to support hype link
Milestones
The improvement on help system contains 5 tasks, and milestones are provided in the 5 tasks accordingly. I will begin my GSOC work just from late April. As I'm not so free before summer, I will spent 12 hours on GSOC per week, while 40 hours in Summer.
1.migrate remaining contents from manpages into built-in help (April 20 to April 30)
- 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 April.
2. new feature of 'hg help -k keyword' (May 1 to June 25)
- 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:
2.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.
2.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.
2.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:
- I will begin my GSOC work just from late April. As I'm not so free before summer, two months will be spent on it. In the first 3 weeks, a prototype (the first milestone) will be developed, just supporting searching help information for commands. Supporting for topics will be merged in the next 2 weeks (the second milestone), and the next 2 weeks for extensions (the third milestone). The final patch will be provided in late June.
3.add example usages to verbose sections in help (June 1 to July 5)
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:
- The discussion can be started in early June, in parallel with Task 2. After that 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 early July.
4.mark up more keywords in hg text role to link topics to each other tightly (July 6 to July 12)
MileStone:
- One week is planned for adding markup. Serials of patches will be submitted, each for a topic.
5.Improve HTML rendering in hgweb view to support hype link (July 13 to August 15)
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:
In the first week, a prototype will be developed, just supporting paragraph(<br>). In the next week, a simple hype link transform for text role will be added, with which we can get hype link from text role of commands. Supporting for topics in the next week. In the 4th week, a supporting for extensive topic, such as extensions and content in glossary will be implemented.
About Me
I'm a girl postgraduate, 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.
Contact Info
Name: Yun Lee
Email: yun.lee.bj@gmail.com
[1.]
[2.]