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.
We used to have two slightly different message which people wouldn't read...
and then complain that they couldn't find the global options or examples.
So we unify them into one message that's upfront that STUFF IS
INTENTIONALLY HIDDEN and that looks more like our normal hint style.
When `hg help foobar` fails, it now suggests using `hg help --keyword foobar`
instead of printing a full page of basic commands.
This should greatly increases discoverability of the `hg help --keyword`
argument.
Before this changeset, when no topic were matching the provided keyword ( in
command such as `hg help --keyword babar`) the output was empty. This is
confusing and unhelpful for new users seeking assistance in the help.
We now display:
$ hg help --keyword babar
abort: no matches
(try "hg help" for a list of topics)
This send users in a new direction where they may find what they are looking for.
When using a different language than English, deprecated options were only
removed from the output of `hg help anycmd` when "DEPRECATED" in the options
description was translated.
Before this patch, "hg help -k KEYWORD" fails, if there is the
extension of which name includes ".", because "extensions.load()"
invoked from "help.topicmatch()" fails to look such extension up, even
though it is already loaded in.
"help.topicmatch()" invokes "extensions.load()" with the name gotten
from "extensions.enabled()". The former expects full name of extension
(= key in '[extensions]' section), but the latter returns names
shortened by "split('.')[-1]". This difference causes failure of
looking extension up.
This patch adds "shortname" argument to "extensions.enabled()" to make
it return shortened names only if it is True. "help.topicmatch()"
turns it off to get full name of extensions.
Then, this patch shortens full name of extensions by "split('.')[-1]"
for showing them in the list of extensions.
Shortening is also applied on names gotten from
"extensions.disabled()" but harmless, because it returns only
extensions directly under "hgext" and their names should not include
".".
We move the logic for generating the unformatted ReST source to the
help module, in order to eventually avoid calling commands.help_()
from hgweb.
No functionality change.
Before this patch, there is no information about whether help document
is fully displayed or not.
So, some users seem to misunderstand "-v" for "hg help" just as "the
option to show list of global options": experience on "hg help -v" for
some commands not containing verbose containers may strengthen this
misunderstanding.
Such users have less opportunity for noticing omitted help document,
and this may cause insufficient understanding about Mercurial.
This patch indicates help omitting, if help document is not fully
displayed.
For command help, the message below is displayed at the end of help
output, if help document is not fully displayed:
use "hg -v help xxxx" to show more complete help and the global
options
and otherwise:
use "hg -v help xxxx" to show the global options
For topics and extensions help, the message below is displayed, only
if help document is not fully displayed:
use "hg help -v xxxx" to show more complete help
This allows users to know whether there is any omitted information or
not exactly, and can trigger "hg help -v" invocation.
This patch causes formatting help document twice, to switch messages
one for omitted help, and another for not omitted. This decreases
performance of help document formatting, but it is not mainly focused
at help command invocation, so this wouldn't become problem.
This makes the 'additional help topics' list consistent with the output from
keyword search (for instance subrepo/subrepos).
The sorting by longest name was introduced in 4cbe49492ad3. There might have
been a good reason for it back then, but now it seems like a better idea to
place the preferred name first in the list in helptable.
The {parents} keyword does not appear in the generated documentation for
templates because it is added by `changeset_templater` (and this is because
its behavior depends on `ui`, so it can't be defined as a normal template
keyword; see comments in `changeset_templater._show()`).
Add it to the documentation synthetically by creating a stub documentation
function.
Test plan: built the docs and examined the man page to verify that this
keyword is now documented. I'm not sure how to test the i18n extraction part,
but assume it will just work given that this patch doesn't do anything too
crazy.
This patch fixes the synopsis shown for extension commands in keyword search
results. A previous patch erroneously caused the extension synopsis to be shown
instead.
Test cases for keyword search are missing, so I added a one.
Keyword search in help (introduced in d455a324f54f and ff267c569bea by Augie
Fackler) tries to translate already translated strings, which results in
Unicode errors in gettext when non-ASCII locale is used. Also command
descriptions should be translated before searching there (thanks to FUJIWARA
Katsunori for pointing this out and actual fix), (issue3482).
There is currently no clear link between the help for log
and the help on templates. The log option is --template
but the template help is 'help templating' or 'help templates'.
This patch makes 'hg help template' work and also adds a
note into the log help explaining where to find more info.
When a dochelp string contains doctest code, the doctest
code is not stripped, so the help also displays the doctest.
Just stop parsing dochelp at the first hint of a doctest
section (starting with >>>).
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
