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 <pre> 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 <pre> 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.
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
- Improve cross linking between help topics - Around 10 days
- Migrate remaining contents from man pages into built-in help - Around 10 days
- 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
- Improve the glossary - Around a week
- Code clean up and writing tests 8. Submitting code to google
Final Evaluation (Aug 16)
Link to patches submitted
Email:mdoshayan@gmail.com
...