|
⇤ ← Revision 1 as of 2011-04-17 12:25:18
Size: 6199
Comment:
|
Size: 6739
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| * [[http://selenic.com/repo/hg/search/?rev=Yun%20Lee|Submitted patches]] = Improve Mercurial's built-in help = |
[[http://selenic.com/repo/hg/search/?rev=Yun%20Lee|submitted patches]] |
| Line 4: | Line 3: |
| * '''Student Name''': [[[YunLee|Yun Lee]]] * '''Contact''': <<MailTo(yun.lee.bj AT SPAMFREE gmail DOT com)>>, yunlee on #mercurial |
= Improve Mercurial's built-in help = |
| Line 7: | Line 5: |
| 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. |
== 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 |
| Line 33: | Line 14: |
| 2.add example usage to verbose sections in help | |
| Line 35: | Line 15: |
| 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. |
== Milestones == |
| Line 39: | Line 17: |
| 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. | 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. |
| Line 42: | Line 27: |
| 3. new feature of 'hg help -k keyword' | === 2. new feature of 'hg help -k keyword' (May 1 to June 25) === |
| Line 44: | Line 29: |
| 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'. | 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'. |
| Line 46: | Line 31: |
| 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. |
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. |
| Line 50: | Line 35: |
| 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. |
==== 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. |
| Line 53: | Line 38: |
| 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. |
==== 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. |
| Line 56: | Line 41: |
| 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. | ==== 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. |
| Line 59: | Line 45: |
| 4.improve crosslinking between help topics The task on crosslinking contains: |
=== 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. |
| Line 62: | Line 69: |
| 4.1 mark more keywords in hg text role to link topics to each other tightly | |
| Line 64: | Line 71: |
| 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. |
== 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. |
| Line 69: | Line 75: |
| [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 |
== Contact Info == *'''Name''': Yun Lee *'''Email''': yun.lee.bj@gmail.com [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 |
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.]