I agree with your comments, this area needs better documentation. And it
would also be nice (and natural) if we could accept subsets of the 40-digit
revision hashes like we do in other parts of Mercurial.

I wont have time to look at this right now, but I will eventually come back
to it. Please feel free to add me to the nosy list of other help and
documentation related bugs, if you file more :-)

In the help for the convert command, the paragraph about the splicemap file states:

"The key is the revision ID in the source revision control system whose parents should be 
modified (same format as a key in .hg/shamap)."

Considering that:

1. if the source is a Mercurial repository, the full, 40-digit revision hash is required;
2. said full revision hash is only obtainable using the --debug option;
3. if the source is a Subversion repository, the key format is completely counter/intuitive 
(where would I get the idea of including the repository type, its UUID and the path when svn 
revisions are reliably identified by number only???);
4. on the first conversion attempt you don't have a shamap file yet;
5. the convert command silently ignores almost anything it does not understand (short Mercurial 
revision hashes, numeric-only svn revision numbers, two parents separated by a space instead of a 
comma), see my next bug report;

I think there is a dire need for improvement to this section of the convert command help, 
specifically by example. Mainly:

1. explicitely state that the full, 40-digit, only-obtainable-using-the-debug-option revision 
hash is required for Mercurial revisions;
2. give an example splicemap line for both cases: one and two parents, with any one of the 
available source formats (just maybe not Mercurial);
3. give a commented example ("this part is the repository UUID available with the foo command, 
etc.) revision ID for each of the available source formats.