annotate doc/README @ 25777:1c2a8db33b8f

hgweb: allow symbolic revisions with forward slashes in urls

It's possible to have a branch/tag/bookmark with all kinds of special
characters, such as {}/\!?. While not very conveniently, symbolic revisions
with such characters work from command line if user correctly quotes the
characters. These characters also work in hgweb, when they are properly
encoded, with one exception: '/' (forward slash, urlencoded as '%2F'), which
was getting decoded before hgweb could parse it as a part of PATH_INFO.
Because of that, hgweb was seeing it as any other forward slash, that is, as
just another url parts separator.

For example, if user wanted to see the content of dir/file at bookmark
'feature/eggs', url could be: '/file/feature%2Feggs/dir/file'. But hgweb tried
to find a revision 'feature' and get contents of 'eggs/dir/file'.

To fix this, let's assume forward slashes are doubly-urlencoded (%252F), so
CGI/WSGI server decodes it into %2F. Then we can decode %2F in the revision
part of the url into an actual '/' character.

Making hgweb produce such urls will be done in the next 2 patches.

Mercurial's documentation is kept in reStructuredText format, which is
a simple plain text format that's easy to read and edit:

  http://docutils.sourceforge.net/rst.html

It's also convertible to a variety of other formats including standard
UNIX man page format and HTML. You'll need to install Docutils:

  http://docutils.sourceforge.net/

Use the Makefile in this directory to generate the man and HTML pages.