Attention GSoC candidates - post your proposals here for feedback

yun lee yun.lee.bj at gmail.com
Fri Apr 8 11:27:25 CDT 2011


Thanks for your advice, Matt.

I have modified my application and submitted it.

Good luck for all the GSOC applicant!

2011/4/8 Matt Mackall <mpm at selenic.com>:
> On Thu, 2011-04-07 at 21:19 +0800, yun lee wrote:
>> 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'
>
> This should probably be higher priority than (2).
>
>>   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
>
> This title should probably mention HTML rendering.
>
>>   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.
>
> Please take a look at my advice to Idan about scheduling.
>
> --
> Mathematics is the supreme nostalgia of our time.
>
>
>



-- 
Yun Lee


More information about the Mercurial-devel mailing list