##master-page:HomepageTemplate #format wiki #language en == Md. O. Shayan == = Abstract = Mercurial's built-in help is pretty descriptive and helpful. But, moving things around little bit it can be pretty useful for hgweb users and, there are some ares still can be improved. Some of then are cross linking of help topics. Prettier display for help pages. Dynamic display of history etc. Documentation improvements like adding example usage and improving glossary would be good. = Deliverables = Easy navigation between help topics. Direct link to all the links from every other help topic. All the man pages resides in doc section of mercurial, moving the required docs into code base. Nice web view for all the current help topics removing 
 tags. Single page  display of all the command reference, similar to  http://www.selenic.com/mercurial/hg.1.html. Adding example usage in  verbose section. Improving glossary

= Milestones =
== 1. Improve HTML rendering in hgweb view ==
Currently help text in displayed as plain text using 
  tags. But these help text is in reST format can be easily turned in html  using docutils. Fallback to plain text if docutils not found.

Implementation: From coding point of view, there's already some code  in doc/gencode.py which can extract reST text from doc resides in the  code base. I can use this code as reference to generate pretty pages. I  tried to implement this feature, and figured some problems. They are:  embedding customized stylesheet file using docutil api. I could  successfully extract the help text in reST format and convert it into  HTML format using docutils.core.publish_parts(). Custom stylesheet is to  be changed in runtime setting. After figuring out this this task is a  cake walk

Reference: 1. doc/gendoc.py. mercurial/help.py This generates hg.1.gendoc.txt which is rst format.

 2. runrst This script generates html format for hg.1 hg `runrst html` which gives hg.1.html

== 2. Improve cross linking between help topics: ==
There's no linking between the help topic. When we go to /help and  click on a link to a topic we see built-in help of the commands. From  that page if we want to go to other pages we have to go back to /help.  This has to be removed and linking should be given to all the pages.

Implementation: This involves changes in templates and listing help  topics each page. We can display all the available topics on the right  side of the page like contents column in  http://www.selenic.com/mercurial/hg.1.html. This is one idea. Discussion  is necessary how to link them for comfortable navigation.

Reference: hgweb/webcommands.py and mercurial/templates/

== 3. Migrating remaining contents from man pages to built-in help ==
As hgrc is being generated from the code itself, reaming man pages  i.e., hgignore and hgrc which are doc section will be moved to code base  so that they can be show in web view.

Implementation: Probably this can be done writing something similar  to doc/gendoc.py in hgewb/ or help module in mercurial. hgrc.5.txt and  hgignore.5.txt are doc file which are reST format and man page are  generated from there files using hgmanpage.py by runrst. docutils is the  tool for task.

== 4. Basic AJAX functionality for dynamic browsing: ==
Using AJAX browsing of log, graph log can be dynamic. Help topics  also can be fetched dynamically. Practically there are many other items  can be displayed with AJAX. Implementing some features(tags, bookmarks)  doesn't make sense.

Reference: templates/static/

== 5. Add example usage to verbose sections in help ==
Topic is self explanatory

Implementation: AFAI can understand changing commands.help_() to  check for verbose flag and display example usage. But main part would be  documenting the example usage. This is more of documentation than  coding. For documenting, It would be prefarable to put them in a 'table'  like datasrtucre in commands.py or helptable in help.py rather than  putting them in a textfile and reading them back.

Reference: mercurial/commands.py mercurial/help.py

== 6. Improve the glossary Documentation ==
This completely documation item. Collaborative editing is very effective way to improve docs

= Start of Program (May 24) =
1. Improve HTML rendering in hgweb view: - Around 10 days

 2. Improve cross linking between help topics - Around 10 days
 2. Migrate remaining contents from man pages into built-in help - Around 10 days
 2. Basic AJAX functionality for dynamic browsing - Around 10 days

== Midterm Evaluation (July 12) ==
5. Add example usage to verbose sections in help. I need to get familiar with each every command of mercurial. - Around 10 days

 6. Improve the glossary - Around a week
 6. Code clean up and writing tests 8. Submitting code to google

== Final Evaluation (Aug 16) ==
[[http://selenic.com/repo/hg/search/?rev=mdoshayan|Link]] to patches submitted

Email:mdoshayan@gmail.com

## You can even more obfuscate your email address by adding more uppercase letters followed by a leading and trailing blank.
...

----
CategoryHomepage