Not all external extensions provide docs; if you use such an extension, you
will experience a crash if you use "hg help --keyword <word>", and <word>
happens to match the extension name.
It seems like a good idea to document the revlog format.
There is a lot more that could be added to this documentation.
But you have to start somewhere.
If a sub-topic/section is requested and the main topic corresponds to
a topic with sub-topics, we now look for and return content for a
sub-topic if found.
With this patch, `hg help internals.X` now works. hgweb does not yet
render sub-topics, however.
Now that we have multiple directories where help topics can live,
we need a mechanism to access them. We already use "." to
separate topic from section. So it seems logical to also use "." to
denote the sub-directory of a topic.
This patch teaches the help command to parse out the possible
sub-topic and pass it to the help system.
We introduce the "internals" help topic, which renders an index of
available sub-topics. The sub-topics themselves are still not
reachable via the help system.
The help system currently only supports showing help topics from a
single directory. We'll need to teach it to show results from
different directories in order to show the internals topics.
The first step is to teach loaddoc() to load documentation from
a sub-directory.
Before, hg help -c was the same as hg help, now it only shows commands.
Before, hg help -e was the same as hg help, now it only shows extensions.
Before, hg help -k crashed, now it shows all topics.
Since Python 2.5 str has new methods: partition and rpartition. They are more
specialized than the usual split and rsplit, and they sometimes convey the
intent of code better and also are a bit faster (faster than split/rsplit with
maxsplit specified). Let's use them in appropriate places for a small speedup.
Example performance (partition):
$ python -m timeit 'assert "apple|orange|banana".split("|")[0] == "apple"'
1000000 loops, best of 3: 0.376 usec per loop
$ python -m timeit 'assert "apple|orange|banana".split("|", 1)[0] == "apple"'
1000000 loops, best of 3: 0.327 usec per loop
$ python -m timeit 'assert "apple|orange|banana".partition("|")[0] == "apple"'
1000000 loops, best of 3: 0.214 usec per loop
Example performance (rpartition):
$ python -m timeit 'assert "apple|orange|banana".rsplit("|")[-1] == "banana"'
1000000 loops, best of 3: 0.372 usec per loop
$ python -m timeit 'assert "apple|orange|banana".rsplit("|", 1)[-1] == "banana"'
1000000 loops, best of 3: 0.332 usec per loop
$ python -m timeit 'assert "apple|orange|banana".rpartition("|")[-1] == "banana"'
1000000 loops, best of 3: 0.219 usec per loop
The home of 'Abort' is 'error' not 'util' however, a lot of code seems to be
confused about that and gives all the credit to 'util' instead of the
hardworking 'error'. In a spirit of equity, we break the cycle of injustice and
give back to 'error' the respect it deserves. And screw that 'util' poser.
For great justice.
This allows us to hide {branches} template keyword in a better way. Currently
it is achieved by copying keywords table and deleting 'branches' from it.
This fixes listexts() to exclude translated "(DEPRECATED)" marker correctly.
On the other hand, help_() doesn't need translated keywords, but I don't think
it's worth to separate untranslated keywords just for it.
In some languages that have no caps, "DEPRECATED" and "deprecated" can be
translated to the same byte sequence. So it is too wild to exclude messages
by _("DEPRECATED").
support combining -c and -e
previously -k was misdocumented:
* the first line didn't mention it
* the help half implied you could do help -k keyword topic
with these changes, -k just changes the search method
support -c and -e for -k searches
There are a lot of non-human consumers of Mercurial. And the challenges
and considerations for machines consuming Mercurial is significantly
different from what humans face.
I think there are enough special considerations around how machines
consume Mercurial that a dedicated help topic is warranted. I concede
the audience for this topic is probably small compared to the general
audience. However, lots of normal Mercurial users do things like create
one-off shell scripts for common workflows that I think this is useful
enough to be in the install (as opposed to, say, a wiki page - which
most users will likely never find).
This text is by no means perfect. But you have to start somewhere. I
think I did cover the important parts, though.
Python 2.6 introduced the "except type as instance" syntax, replacing
the "except type, instance" syntax that came before. Python 3 dropped
support for the latter syntax. Since we no longer support Python 2.4 or
2.5, we have no need to continue supporting the "except type, instance".
This patch mass rewrites the exception syntax to be Python 2.6+ and
Python 3 compatible.
This patch was produced by running `2to3 -f except -w -n .`.
Merge tools were being double documented in help system output due
to functions being defined under multiple names in the merge tools
dictionary.
Establish a new dictionary for just the tools to document and
use it from the help system so we don't get double output.
Double documentation likely plagues other auto-documented items
as well. It might be a good idea to eventually compare function
instances to filter out duplicate entries from dictionaries
passed to ``makeitemsdoc``. However, without an easy way to break
ties, this may result in some functions being advertised over
their modern equivalents. This would be a noble patch series.
But it isn't one this author is willing to tackle at this time.
When using docstrings for documenting symbols such as revsets,
templates, or hgweb commands, documentation likely has leading
whitespace corresponding to the indentation from the Python source
file.
Up until this point, the help system stripped all leading and
trailing whitespace and replaced it with 2 spaces of leading
whitespace. There were a few bad side-effects. First, sections
could not be used in docstrings because they would be indented
and the rst parser would fail to parse them as sections. Also,
any rst elements that required indentation would lose their
indentation, again causing them to be parsed and rendered
incorrectly.
In this patch, we teach the topic symbols system how to dedent
text properly. I argue this mode should be enabled by default.
However, I stopped short of changing that because it would cause
a lot of documentation reformatting to occur. I'm not sure if
people are relying on or wanting indentation. So, dedenting has
only been turned on for hgweb symbols. This decision should be
scrutinized.
The capabilities and URL endpoints of the hgweb server can currently
only be inferred by looking at links in `hg serve` output or by reading
the source code. I've frequently found myself wanting to quickly see
what URLs and capabilities are available.
This patch teaches the help system how to display information about
web commands and their URLs. Using a mechanism similar to revsets,
templates, etc, we can now iterate over the docstrings of registered
web command functions and display them in the help output.
Unfortunately, web commands don't currently have docstrings, so the
output is currently empty. This will be addressed in the following
patches. I apologize for the patch bomb.
The search was introduced in 73b7669a499c without a convincing explanation why
it should be necessary ... except for consistency with templater handling.
Now, just keep it simple.
templates, help and locale data is normally stored as sub folders in the
directory containing the source of the mercurial module. In a frozen build they
live as sub folders next to 'hg.exe' and 'library.zip'.
These different kind of data were handled in different ways. Unify that by
introducing util.datapath. The value is computed from the environment and is
always used, so we just calculate the value on module load.
`hg help -k` on my machine was aborting because the hg-prompt extension
was inserting a string and not a function into help.helptable and help
was blindly calling it.
This patch changes keyword searching to be more robust against
unexpected types.
The output is slightly changed because of minirst formatting. Previously,
ui.pushbuffer() had no effect because "badalias" message was written to stderr.
"if not unknowncmd" should no longer be needed because there's no call loop.
