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