Typos and improvement help and messages

[buhtignew]

I've decided to create this issue so in case there are typos or improvements to make in the help we can put everything here, so it doesn't interfere with the main testing process.

Right now I've found the following typo in transaction list help:

Only show received transactions (not in combination with -x, -n, -c, -b or -g). Only show received transactions (not in combination with -n, -c, -b or -g).

Seems like almost the same text is included into this line twice, probably the second sentence is the old one.
_
If it can be useful I've found another one in the card list help.
In the description sections is written:

    Usage:

    pacli card list
    pacli token list

While if I've got it right in the card list command has become token transfers command.

_

1. In token transfers help there is the following line:

NOTES
    You can also use flags syntax for POSITIONAL ARGUMENTS

I don't know whether it's relevant in that context.

_
In the token list help there is the following explanation about the -o flag:

 Shows only the P2TH address of each token/deck. When used with -d, shows all P2TH addresses of the dPoD tokens.

However the both the token list -o and the token list -o -d commands output the same number of decks. I assume the -p flag was formerly -d in this case and the description wasn't changed after the change.

2. By the way the token list -o -b seems to work as well. Maybe we should mention that in the -o flag description as well?

3. I've also discovered that there is no P2TH address in the token list output. Thus it's not clear what is being this flag's output compared to (it's not something extracted from the token list output, for instance). I think I know what is the meaning though - the flag probably means p2th-addresses-only, but by putting "only" ahead of "p2th" the meaning seems to become less evident. For that reason I'd suggest us to consider the -l flag which would mean --list-p2th-addresses-of-the-decks. What do you think?

_
Like in the issue #87 there is no difference between token list, token list -d, token list -q and token list -d -q, which is probably expected.

_
As mentioned here I'd suggest to add an additional information into the transaction list's -l description. Something like: "The flag grants a quicker output in case the blocks were stored using deck/token cache/init or address cache commands previously, otherwise it will be ignored".

_
The pacli token balances [ADDRESS|-w] usage mode description states:

Shows balances of all tokens, either on the specified address or on the whole wallet (with -w flag).
    If ADDRESS is not given and -w is not selected, the current main address is used.

It seems to me to remember that previously it was mentioning that this usage mode outputs the main dPoD and PoB desks info only.

_
The -a flag output for the token balances [ADDRESS|-w] -t DECK usage mode is the same as without the -a flag. Would it make sense to edit the -a flag description from See above. Shows balances of all tokens in JSON format. Not in combination with -o. into See above. Shows balances of all tokens in JSON format. Not in combination with -o and -t.?

[d5000]

First error (token transfers) was already changed in an earlier commit.

1. Please ignore this for now, it can't be changed.
   1b. You're correct, this was an error, fixed it to -p.
2. -o works with all types of decks. The addition is only because dPoD decks have several P2TH addresses.
3. Don't agree because -o only lists P2TH addresses, the deck ID is only shown to identify the deck.
4. -d and -q are only used in some of the options, in the others they won't have effect, but as mentioned elsewhere -d always shows a traceback when there is an error.
5. (transaction list mention of speedup for block locators): Done.
6. (token balances) You're correct the current description fits the -a mode. I added the mode without -a.
7. (change for -a flag) Makes sense, changed.

Fixes are in commit 709830a.

[buhtignew]

I've got all the above. Letting this issue open to add other small notes of the kind.

[buhtignew]

The token init help describes the -a flag as following:
In combination with -s, store blockheights for all initialized tokens/decks.
Probably the -s flag should be edited into -c flag in that description.

_

Relatively to the new -f flag introduced here for the address cache and token cache commands maybe we can add in the flag's description: "Has a priority against the -b flag - if used both the -b flag is ignored.".

_
I've just discovered that the address set -f command not only creates a fresh address but also set it as a main one, maybe we should consider to change the message that is being output during the fresh address creation from Address already is saved in your wallet, ready to use. into Address already saved in your wallet and set as main.?
_
I'd suggest us to add in the -f flag description of the token show command that it's incompatible with other flags, in case the -f flag is used all the others (I can't say it for sure for the -q and -d flags though) are ignored.

[d5000]

All done in commit 7166bef.

[buhtignew]

Regarding you commit 10dc4a0 mentioned here maybe we could add the description of token list -s -p and token list -s -b mode of use in the token list help.

[d5000]

Done, will be uploaded in the next update.

[buhtignew]

Regarding your reply here, maybe we can include that info into the token transfers and card list help, specifically in the Usage mode section.
If I've got it right the above commands are not usable without the token_id, label or name, while from the help as we have it now it seems like they are.

_
Maybe we can improve the help of token transfers in the Name section.
Editing List all transactions (cards, i.e. issues, transfers, burns) of a token (with support for deck labels). into List all existing transactions (issues, transfers, burns) of a token.
The issue I'm trying to solve here is to make it clear that it's not only in-wallet transactions but basically all transactions registered on the net.

[d5000]

You're correct, the TOKEN positional argument was missing as mandatory, I added it for the next update.

Second addition also makes sense, added it.

[buhtignew]

Second addition also makes sense, added it.

I still don't understand the meaning of the word cards in the Name section of our token transfers help:
pacli token transfers - List all existing transactions (cards, i.e. issues, transfers, burns) of a token.

[d5000]

A card (short form for CardTransfer) is an unit used for any kind of token transaction (issuance, transfer or burn transaction). There can however be more than one card in one Slimcoin transaction. For example when you transfer tokens to two recipients, this will be counted as two cards/CardTransfers.

[buhtignew]

I've got the meaning now. Wouldn't it make sense to change card into CardTransfer in that sentence for those like me who wouldn't be enough conscious of the short form of the term? But does the issuance transaction
make part of CardTransfer or it's a CardIssue transaction?
_
I agreement to your replies here and here, wouldn't it make sense specifying in relative help that the True and False words are case sensitive, or it's somehow obvious given the context?
_
We've edited "In advanced mode" into "In advanced mode (-a)" for the -w flag of the address list command. Maybe we should do the same for the -o flag as well.
_
For the better clarity I'd suggest us to edit the line "Without flags, sets the LABEL as the main address." into "Without flags, sets the address that has that LABEL as the main address."
_
While testing pobtoken burn_coins command it was not enough clear for me where the burned amount goes if no deck is mentioned (see here). Then I've realized the standard PoB deck is being used in that case.
Maybe we can make it explicit for the pacli pobtoken burn_coins AMOUNT usage mode?
_
While I've been running the transaction list command I've noticed that the message Locator mode not supported if no addresses or decks are selected. Locators will not be used. is always displayed in case the -x flag is used without an address or a deck, regardless whether the command is launched with the -l flag or not. Maybe we can display it only when there is an -l flag as well.
_
In pobtoken burn_coins help there is the following line: Burns coins checking for compatibility (e.g. deadlines) with token (deck) TOKEN. I understand the meaning, but I was wondering whether we can find a better wording for the end of the sentence. Maybe it can be changed basically into this: Burns coins checking for compatibility (e.g. deadlines) with token/deck TOKEN.?
_
The same for the pobtoken create_tx we can change Send coins to the gateway (e.g. donation, investment) address of token (deck) TOKEN. into Send coins to the gateway (e.g. donation, investment) address of token/deck TOKEN. if you like it.
_
The usage modes of the pobtoken create_tx help is mentioning attoken instead of pobtoken, maybe we should edit it for better understanding?
_
IDK whether it would make sense for the average user, but during my testing I've realized that it would be useful to have the address list displaying the block on which the data is displayed.
_
In agreement to the issue #142 where the use of the global labels for the pobtoken burn_coins command with the -i flag (pobtoken burn_coins 1 -i ATTokenNewSpec, for instance) was implemented and since the local labels were already usable with that flag I'd suggest us to make some modification of the -i flag description and maybe of the extended form of the flag itself as well.
I.e. we can change --idstr into --id_or_label and its description can be changed from ID of the Token or Deck you want to check compatibility with. into ID or label of the Token/Deck you want to check compatibility with.
_
I haven't included this info into the issue #162, but the attoken claim command complains about ambiguity if run it with the -d flag.
_
I was thinking whether it would make sense to change the name of the category at_address in the token show TOKEN -f -i output (or in the token info TOKEN if we decide to opt for the solution expressed in the issue #159) into gateway_address in order to have it aligned with the terminology (the flag -g) we've introduced for the transaction list command.
_
After I've understood, thanks to your explanation here, on how the decks with the same global name are being managed by the code I've begun noticing the message More than one matching deck found: included in the outputs where the ambiguity occurs. I also remember we've decided in the past to treat the older decks as the decks that were really meant by the user, but as we've seen in the issue mentioned above sometimes it can happen that the older doesn't mean the right one, so I was wondering whether it would make sense to just stop executing command in case of ambiguity and output the message Error: deck's global name ambiguity, please use the meant deck's id or its local label. just after the More than one matching deck found: message.
_
Another thing we should be careful about is that since the local label is being automatically copied from the global name during the deck initialization, in case of the same global name used twice or more for different decks there is at least one local label that is exactly the same as those multiple global names. So it's possible that the user means the local label, but the code means the global names which could lead the users to misunderstand the messages our code outputs, even if the user is trying to use the local labels only while working with the decks. Maybe we should consider to add some suffix to the local labels when they are copied from the global names (something like GLOBALNAME_l, for instance)
However knowing that general rule the scammers may create decks that have that suffix in their names in order the user to send funds to the wrong deck while using the local label (since the global name have the priority). For that reason we probably should also make a check between the local labels and the global names and if there are matches the code should output the error message and just stop executing the command it was about to run.
_
If we decide to add a suffix to the local labels created by the pobtoken deck_spawn command we may also implement it for the attoken deck_spawn.
_
I think it would be comfortable if the address set command had an output, the address show -l output would be fine for instance, because with the quite output we have right now it's not clear whether the change of the main address has really happened or the command hasn't done anything. So each time I run address set I also run address show -l to check whether everything is fine.
Maybe it would even make sense to add the address balance output as well.
_
It seems like the local addresses' labels are not usable in case of the claim requests for the multiple receivers (for instance as mentioned in #165 it's not possible to run the attoken claim johns_attoken2 c6a73f51fc3d336689e43c60a6715110486fca80b9940cafb38c6ddba0b90ddd -r "[usage_checked, old_default, new_after_refill9, fresh_after_refill9, flag-l]" -a "[0.7, 0.1, 0.01, 0.3, 0.02]" command). I don't know whether it would make sense to additionally stress this fact in the help of the attoken claim, pobtoken claim and podtoken claim commands.
_
I've run attoken create_tx 3f5920b3b26ca8089479691d2900d7d31970013b5cb874194876e4cebca02156 1.1234567890 and got the following message:

Error: End deadline for burn or gateway transactions of this token is is block 505942.

Maybe we can edit it into `Error: Final deadline for the burn or gateway transactions of this token is the block 505942.'?

[buhtignew]

The previous post has become too long. I'm opening a new one.
_
Maybe we can consider editing the line Specify a multiplier for the reward.. into Specify an integer multiplier for the reward. in the help of the pobtoken spawn and attoken spawn command?
_
Since the name of the deck_spawn was renamed (as mentioned here) into spawn for the pobtoken and attoken groups, we can also edit deck_spawn into spawn in the attoken spawn -h output (there is still the old term in the Description section).
_
Would it make sense editing pacli dex exchange DECK PARTNER_ADDRESS PARTNER_INPUT CARD_AMOUNT COIN_AMOUNT line into pacli dex exchange DECK PARTNER_ADDRESS PARTNER_INPUT TOKEN_AMOUNT COIN_AMOUNT both in dex exchange -h Synopsis and Description?
_
Would it make sense editing the word AMOUNT both in Synopsis as in Description of the dex lock -h into TOKEN_AMOUNT?
_
I've run both proposal list 3369f3eb703656c0b46b613dcfb4df78fc05657a0b75f44551634de6321d9d9c -o and proposal list a2459e054ce0f600c90be458915af6bad36a6863a0ce0e33ab76086b514f765a -o and got:

No active and/or completed proposal states found for deck

However if I run the same commands without the -o flag I can see some completed proposal. Would it make sense making the message more specific in this case, i.e. No active proposal states found for deck?
_
We probably should edit pacli proposal period, pacli proposal period -a, pacli proposal period PERIOD and pacli proposal period -b BLOCK into pacli proposal period FULL_PROPOSAL_ID PERIOD, pacli proposal period FULL_PROPOSAL_ID -a and pacli proposal period FULL_PROPOSAL_ID -b BLOCK in proposal period -h Usage options section.
_
Maybe we could edit Show a parameter of the proposal state dictionary (only in combination with -s) into Only in combination with -s. Extract the parameter value(s) from the output provided by proposal show command if run with the -s flag only. (or something similar) in the proposal show -h. At least as you can see from the issue #179 which I've solved by myself it was not that clear to me the usage of that flag, because the -s flag follows the -p flag in the Flags section of the help so the expression proposal state dictionary was not that clear to me when I've begun testing the -s flag.
Another idea can be at least to rename the --state flag into --state_of_proposal
_
Maybe we can edit pacli proposal show LABEL_OR_ID -s [-p PARAM] [-a] into pacli proposal show LABEL_OR_ID -s [-p PARAM |-a|-b] in the Usage modes section of the proposal show -h output, since the -b flag is also to be used with the -s flag only and all the three flags (-p, -a and -b) can't be used together.

[buhtignew]

I'm beginning with another post, since the previous one was becoming too long to manage.
_
In agreement to this maybe we can add in the proposal list -h the same info already added for the podtoken state -h and podtoken votes -h: If deck is not specified, the default dPoD deck is used.

_
In attoken spawn -h output the Usage mode still mentions the old name of the command, i.e. attoken deck_spawn.

_
We call our donation token as dPoD token, but our commands are referring to the PoD token. Would it make sense consider renaming them?
There is also a number of PoD token mentions in the help text of different commands.
_

The podtoken electorate -h output still refers to the proposal electorate (which is the old command).

_
Maybe we can consider adding Usage mode into the podtoken electorate -h for the -e flag explaining that it should be followed by the number of epoch (and not the blockheight, for instance).
_
Maybe we can add into the podtoken electorate -h that the flag -s is not to be used in combination with -n and -e, that the flag -n shouldn't be used with -s and -e and the flag -e shouldn't be used with -n and -s.

[d5000]

I'm currenlty working on the first long batch of suggestions (on a whole I agree with them and have modified the docstrings accordingly) and stumbled upon this, which is a misunderstanding:

While testing pobtoken burn_coins command it was not enough clear for me where the burned amount goes if no deck is mentioned (see #138). Then I've realized the standard PoB deck is being used in that case.

Burning coins is "neutral", a burn transaction is valid for all PoB token decks. It even gives you proof-of-burn "score" for the slimcoin algorithm. It doesn't matter if you use the pacli command or slimcoind burncoins.

---

Another comment: In reality I like the token (deck) wording more, because token/deck would suggest that token is a complete synonym for deck. It is true that token commands can replace deck commands but the other way around is not true. I'll try to be consistent with that wording though.

---

at_address is used because it is a system parameter of this dictionary. It stands both for gateway and burn address.

---

So it's possible that the user means the local label, but the code means the global names

Local labels have always priority so this will not occur. When the label is first stored when deck is initialized, the code checks for local labels if they exist, and if not it puts out a message inviting the user to select the deck's label himself.

---

Some other suggestions were already solved (e.g. the ambiguity of -d in attoken claim and the local labels support in receiver lists of the claim commands)

[d5000]

In the next update most suggestions of the "big" batches from August 1 and 8 were implemented, with the following exceptions:

• proposal period: was recently changed so it accepts also miniids and labels.
• proposal list message issue about completed proposals: needs more review. fixed in next update.
• last proposal show issue: As it's already common in other commands I don't show exclusive flags in the command string of the Usage modes sections anymore. Doing this with every command consistently would be simply too complicated to explain and maintain.
• proposal list message about default dPoD deck: was already implemented before.
• dPoD instead of PoD: Help texts were modified. I'm considering changing the PoDToken class into DPoDtoken, but decision has not been taken still. According to class conventions in Python the class should start with an uppercase letter which looks here a bit strange. However as the commands themselves are all lowercase it would not really matter for the interface.

[buhtignew]

Burning coins is "neutral", a burn transaction is valid for all PoB token decks. It even gives you proof-of-burn "score" for the slimcoin algorithm. It doesn't matter if you use the pacli command or slimcoind burncoins.

Of course, I've realized it later on.

Another comment: In reality I like the token (deck) wording more, because token/deck would suggest that token is a complete synonym for deck. It is true that token commands can replace deck commands but the other way around is not true. I'll try to be consistent with that wording though.

Agreed

at_address is used because it is a system parameter of this dictionary. It stands both for gateway and burn address.

I see now. Does it mean that it's not possible to change that parameter in the dictionary at all? If not so, i.e. if it's changeable, I think it would make sense replacing it with some more expressive word both for the AT and PoB tokens.
Also because the issuer address is positioned earlier in the token show TOKEN -i output and so it's easy to pick up the wrong address from the list.
Maybe we should consider at least putting the at_address higher than the issuer address?

When the label is first stored when deck is initialized, the code checks for local labels if they exist, and if not it puts out a message inviting the user to select the deck's label himself.

I'm not sure it works like described above for the moment or maybe I've taken wrong the context we are speaking about.
For instance I've just initialized the test_issuerisgateway, which was not initialized on my side, by running deck init test_issuerisgateway and my output was:

Deck not named locally. Searching global deck name ...
Using matching deck with global name test_issuerisgateway, with id: 1d4d470601e6359a1f3b7901d120620cd11741b316e610ad532c30f91053a49c
Importing deck: 1d4d470601e6359a1f3b7901d120620cd11741b316e610ad532c30f91053a49c
Importing P2TH address from deck.
Trying to store global deck name test_issuerisgateway as a local label for this deck.
Stored deck:
Label: test_issuerisgateway
Value: 1d4d470601e6359a1f3b7901d120620cd11741b316e610ad532c30f91053a49c
Done.

So I was not asked to chose the label, the deck's global label was chosen automatically as local label.
_
Seems like the replies to the following 3 proposal I've made are missing or I haven't understood the answer:

In agreement to the issue #142 where the use of the global labels for the pobtoken burn_coins command with the -i flag (pobtoken burn_coins 1 -i ATTokenNewSpec, for instance) was implemented and since the local labels were already usable with that flag I'd suggest us to make some modification of the -i flag description and maybe of the extended form of the flag itself as well.
I.e. we can change --idstr into --id_or_label and its description can be changed from ID of the Token or Deck you want to check compatibility with. into ID or label of the Token/Deck you want to check compatibility with.

[...] Maybe it would even make sense to add the address balance output as well.

It seems like the local addresses' labels are not usable in case of the claim requests for the multiple receivers (for instance as mentioned in #165 it's not possible to run the attoken claim johns_attoken2 c6a73f51fc3d336689e43c60a6715110486fca80b9940cafb38c6ddba0b90ddd -r "[usage_checked, old_default, new_after_refill9, fresh_after_refill9, flag-l]" -a "[0.7, 0.1, 0.01, 0.3, 0.02]" command). I don't know whether it would make sense to additionally stress this fact in the help of the attoken claim, pobtoken claim and podtoken claim commands.

_
I'm not sure if this:

proposal list message issue about completed proposals: needs more review. fixed in next update.

is a reply to this:

I've run both proposal list 3369f3eb703656c0b46b613dcfb4df78fc05657a0b75f44551634de6321d9d9c -o and proposal list a2459e054ce0f600c90be458915af6bad36a6863a0ce0e33ab76086b514f765a -o and got:
No active and/or completed proposal states found for deck
However if I run the same commands without the -o flag I can see some completed proposal. Would it make sense making the message more specific in this case, i.e. No active proposal states found for deck?

_
I've run address set n3MtPoPaAREU5GEhAErBPuju83bVog2opz and got:

Error: Invalid or non-wallet address.

But actually the issue was different in this case: I should've used the -a flag before the address.
So maybe we can change this error message into something like Invalid label or No such label in this wallet?
_
Maybe it would make sense editing the line TOKEN can be a token (deck) ID or a label. in token transfers -h Description section into TOKEN can be a token(deck) ID or label.?
_
I wouldn't like to reopen this and I'm not even sure it worth mentioning the topic here or it would be better to move it in "Nice to have..." (if so please let me know).
But if you may consider it I'd at least suggest to split the error message Error: If using -e or -s options you have to provide a block height or epoch. in two:

• one for the -e flag, something like this Error: Please provide the epoch number after the -e flag.
• and the other for the -s flag, for instance: Please provide the blockheight number after the -s flag.

If not it's like we are supplying the user with too much info in just one message: he may be potentially never interested in the other option we are informing him about.
And also the order of the words epoch and blockheight in the error message is reverse compared to the order of the relative -s and -e flags in the same message, so it may be not comfortable for the user.
Another idea for the -s flag could be just ignoring it if used without the blockheight, thus providing the standard podtoken electorate output.

[d5000]

Does it mean that it's not possible to change that parameter in the dictionary at all?

It is not "impossible" but currently what's being output is the original structure of the object. For future versions there may be a "ELI5" interface.

I'm not sure it works like described above for the moment

I see now, my answer there was misleading. Yes, the deck init stores the global name if possible and only if there is a conflicting local label then the message about storing a label manually is print out.

Regarding the three items you thought I'd not "answered": I will not comment on all small decisions I do regarding these messages. Normally if I don't comment on them I've implemented them at least partly, not necessarily "exactly" like you proposed. These are not things we have to discuss every time.

But here are the answers:

1. Regarding --id_or_label: Positional arguments will normally not have "speaking" names. The other part was implemented.

2. balance output for address set was already implemented.

3. Local labels for attoken claim were also already implemented.

4. Your proposal list proposal was also implemented, thus I striked it through.

For token transfers, the message was edited.

Regarding the podtoken electorate message you proposed to output if the user uses the command incorrectly, I repeat my stance on this:

I'll normally not provide an error message for users using the commands incorrectly. There are potentially thousands of possible messages that would have been implemented in this case.

In some cases however you already saw I did implement a message. This is the case when I have to catch a system error, where otherwise a long traceback is shown which will confuse the user. But then the messages will be very simple and generic. So in the case with -eand -s it's perfectly fine if I only provide one message for both cases. This message will almost never been printed out, because users will use -e or -s only if they want to see the state at a specific epoch or blockheight. Or why should they use those flags?

Yes I'm maybe a bit salty again but it's always the same problem with some of your proposals. I can't hold the hand of the user all the time if he's not willing to read about the correct usage, much less with the Fire/pacli package which is normally meant for advanced/technical users.

What I've done to clarify is that I've changed the message to If using -e or -s options you have to provide an epoch (for -e) or block height (for -s). (next update)

The same goes for the issue with the -a flag before an address. I however changed the message a bit because such errors can appear in several commands: Invalid or non-wallet address (or incorrect command usage).

Another idea for the -s flag could be just ignoring it if used without the blockheight, thus providing the standard podtoken electorate output.

I've already commented on this in the podtoken electorate issue. Makes no sense because why should the user enter -s without any blockheight? The flag's "point" is to provide the interface to enter the blockheight.

[buhtignew]

I will not comment on all small decisions I do regarding these messages. Normally if I don't comment on them I've implemented them at least partly, not necessarily "exactly" like you proposed.

I've understood that you are using this approach, but in the three cases I've mentioned I haven't found the way to understand what have been changed, that's why I've asked.
For me it's important to understand it to test the new functionality or change in order to avoid us accidentally adding bugs where an improvement was intended.

Regarding --id_or_label: Positional arguments will normally not have "speaking" names. The other part was implemented.

Would it make sense to document this change somewhere in the pobtoken burn_coins help by adding a hint about the possibility to use the label along with the token's id after the -i flag? (If not I'm afraid I'll pop up with the "improvement" proposal again once I've forgot about this discussion :-) )
By the way, maybe I don't understand the terminology in this case, but --idstr doesn't seem to be a positional argument.

balance output for address set was already implemented.

You are right, I've probably confused that my proposal with this one:

IDK whether it would make sense for the average user, but during my testing I've realized that it would be useful to have the address list displaying the block on which the data is displayed.

If possible it may be useful to change the line +Balances of addresses with labels in wallet: in the output into the line +Balances of addresses with labels in wallet at block [current_blockheight].

Your proposal list proposal was also implemented, thus I striked it through.

I'm seeing that it's struck through, but I'm not seeing any change in the output. So assume I have to wait for the next update to see the change, haven't I?
Solved with the recent update.

Local labels for attoken claim were also already implemented.

Then I'm doing something wrong on my end, because when I try to run attoken claim johns_attoken2 c6a73f51fc3d336689e43c60a6715110486fca80b9940cafb38c6ddba0b90ddd -r "[usage_checked, old_default, new_after_refill9, fresh_after_refill9, flag-l]" -a "[0.7, 0.1, 0.01, 0.3, 0.02]" I'm getting Error: Receiver invalid: [ error.

For token transfers, the message was edited.

On my end if I run token transfers -h I can still see TOKEN can be a token (deck) ID or a label. in Description. I think if we cut out the "a" before the "label" the message would become more clear.
I think we don't have to edit the "a" article here, because with the "a" it means that not only the local label, but also the global label can be used, which is how it works.

...much less with the Fire/pacli package which is normally meant for advanced/technical users.

This was enlightening for me, TBH. I haven't thought about it that way so far. Thank you.
_
There is the following sentence in the pacli podtoken electorate [TOKEN] -n [BLOCKHEIGHT] explanation of the podtoken electorate -h:

If no block height is given, the potential state taking into account the transactions of voting and dPoD tokens at the current block is calculated.

I think it should be edited somehow, because there are two verbs in it so the meaning is a bit obscure, and also it doesn't seem that clear that we are speaking about the epoch following the current one.

[buhtignew]

I'm creating this new post, since the previous one has become a bit long to manage.
_
When I run token cache dt_111021 -v on the deck that has been never cached I'm getting the following message: This address was never cached., maybe we can edit it into This deck was never cached.?