Project

General

Profile

Actions

Feature #3780

closed

nfdc status commands

Added by Junxiao Shi over 7 years ago. Updated over 7 years ago.

Status:
Closed
Priority:
Normal
Assignee:
Category:
Tools
Target version:
Start date:
Due date:
% Done:

100%

Estimated time:
9.00 h

Description

In nfdc, re-implement these commands with StatusReport without converting to legacy nfd-status syntax:

  • status report
  • status show
  • face list
  • channel list
  • strategy list
  • fib list
  • route list

Add help command and update manpages for top-level help and the above commands.

Deprecate legacy nfd-status.


Related issues 2 (0 open2 closed)

Related to NFD - Feature #2542: Redesign nfdc combining nfdc and nfd-statusClosedJunxiao Shi

Actions
Blocked by NFD - Feature #3749: nfdc one-shot modeClosedJunxiao Shi

Actions
Actions #1

Updated by Junxiao Shi over 7 years ago

  • Related to Feature #2542: Redesign nfdc combining nfdc and nfd-status added
Actions #2

Updated by Junxiao Shi over 7 years ago

Actions #3

Updated by Junxiao Shi over 7 years ago

  • Subject changed from nfdc help command and manpage to nfdc status commands
  • Description updated (diff)
  • Assignee set to Junxiao Shi
  • Estimated time changed from 6.00 h to 9.00 h
Actions #4

Updated by Junxiao Shi over 7 years ago

  • Status changed from New to In Progress
Actions #5

Updated by Junxiao Shi over 7 years ago

  • % Done changed from 0 to 20

https://gerrit.named-data.net/3224 adds help command.
I'm adopting the design of git help: nfdc help shows a list of commands; help for individual commands opens the manpage.

patchset1 only contains the help command itself.

I'll add unit testing and manpages in later patchsets.

Actions #6

Updated by Junxiao Shi over 7 years ago

There's a design choice on the granularity of each manpage:

Option A: create one manpage for each noun.

man nfdc-route contains help for nfdc route list, nfdc route add, and nfdc route remove commands.
These three commands operation on the same entity "RIB route", so it makes sense to have them on the same manpage.

However, man nfdc-status would contain help for nfdc status show and nfdc status report, and those two commands are quite different.

Option B: create one manpage for each subcommand.

This makes more sense to keep man nfdc-status-show and man nfdc-status-report separate, but there would be information duplication among man nfdc-route-list, man nfdc-route-add, and man nfdc-route-remove.

I propose this solution as a trade-off:

  • Each subcommand should have its own manpage name, such as man nfdc-route-list.
  • A manpage can have multiple names (implemented through symbolic links). man nfdc-route-list, man nfdc-route-add, and man nfdc-route-remove open the same manpage that contains information for all three commands. man nfdc-status-show and man nfdc-status-report open two distinct manpages.
  • Aliases are not limited to within the same noun. man nfdc-create and man nfdc-destroy both operate on faces, so they can share a manpage.
Actions #7

Updated by Davide Pesavento over 7 years ago

I propose this solution as a trade-off:

uhm... maybe. But instead of littering the filesystem with symlinks, I propose to make nfdc slightly smarter: open nfdc-<noun>-<verb> if it exists, otherwise fall back to nfdc-<noun>. Aliasing from a noun to a different one can still be provided via symlinks.

There is also the minor problem that an uninstalled nfdc will open the installed (and possibly older) version of the manpages.

Actions #8

Updated by Junxiao Shi over 7 years ago

open nfdc-<noun>-<verb> if it exists, otherwise fall back to nfdc-<noun>

I disagree with this.

This implies there isn't a consistent name for calling manpages directly with man command, which can be confusing.

an uninstalled nfdc will open the installed (and possibly older) version of the manpages

Running a command without first installing it is an unsupported scenario.

Uninstalling software with a source code version other than the version used during installation is an unsupported scenario.

Actions #9

Updated by Alex Afanasyev over 7 years ago

My vote would be for option A. I don't see a major difference between status show and report, but fracturing the documentation (it's not that big to be fractured, btw) would only complicate figuring out how to use nfdc.

Actions #10

Updated by Davide Pesavento over 7 years ago

Then I also vote for option A.

Actions #11

Updated by Junxiao Shi over 7 years ago

https://gerrit.named-data.net/3224 patchset4 adds two manpages nfdc-status and nfdc-face.
The organization is:

  • Each manpage includes nfdc commands under a certain noun.
  • Legacy nfdc commands related to this noun are also shown on the same manpage, and symlinks are be created. For example, nfdc create is documented on man nfdc-face.
  • When a legacy command is later re-implemented, take nfdc create as an example: nfdc create is deleted from man nfdc-face. man nfdc-create becomes a separate page that indicates nfdc face create should be used instead; nfdc create syntax is no longer documented.

I need a review on this structure.

Once these are reviewed, I'll add other manpages, figure out how to create symlinks, and update man nfdc.

Actions #12

Updated by Eric Newberry over 7 years ago

How are some commands, like nfdc create, considered to be under a certain noun even if they don't contain that noun in their command? Are they sorted based upon the category of the command?

Other than that, I see no issue with the currently proposed organization of the manpages.

Actions #13

Updated by Junxiao Shi over 7 years ago

Answer to note-12:

This occurs for legacy commands only. They are categorized by the noun of its future replacement. In implementation, a symlink will be used.

Actions #14

Updated by Eric Newberry over 7 years ago

Junxiao Shi wrote:

Answer to note-12:

This occurs for legacy commands only. They are categorized by the noun of its future replacement. In implementation, a symlink will be used.

Makes sense, although it might be worth mentioning the planned changes on the man page. Otherwise, the man page templates look good.

Actions #15

Updated by Junxiao Shi over 7 years ago

  • % Done changed from 20 to 30

https://gerrit.named-data.net/3224 patchset5 adds other manpages.
I haven't figured out how to create symlinks.

nfdc channel list is currently in man nfdc-face. I merged them because channel is closely related to face, and there's no more command under channel.
Similarly, nfdc fib list is currently in man nfdc-route.
Implementation should use symlinks.

An issue I notice is: nfdc help face brings up a list of commands under nfdc face (which eventually would contain nfdc face list, nfdc face create, and nfdc face destroy), instead of opening man nfdc-face. nfdc help face list is needed to open the manpage.
I'm unsure whether the current approach is better or worse than opening the manpage directly from nfdc help face.

Actions #16

Updated by Junxiao Shi over 7 years ago

https://gerrit.named-data.net/3224 patchset6 completes help command.

nfdc help face now brings up the manpage instead of a list; otherwise, nfdc help register would not work.
helpList function still supports filtering commands by noun, which will be re-enabled for interactive mode.

Actions #17

Updated by Junxiao Shi over 7 years ago

  • Target version changed from v0.5 to v0.6
  • % Done changed from 30 to 70

https://gerrit.named-data.net/3337 re-implements status commands.

The next Change(s) will switch nfd-status-http-server to use nfdc status report format xml command, and deprecate nfd-status.

Actions #18

Updated by Junxiao Shi over 7 years ago

  • % Done changed from 70 to 90

https://gerrit.named-data.net/3346 updates nfd-status-http-server to invoke nfdc status report xml instead of nfd-status -x.

Actions #19

Updated by Junxiao Shi over 7 years ago

  • Status changed from In Progress to Code review
  • % Done changed from 90 to 100

https://gerrit.named-data.net/3347 deprecates legacy nfd-status.

I did not update top-level nfdc(1) manpage in this issue. I plan to defer this until final completion of nfdc refactoring, so that the subcommands and examples in that manpage would reflect the latest syntax.

I also did not implement dataset filtering (such as face list [[remote] <uri>] [local <uri>] [scheme <scheme>]) in this issue. They will be added when we implement commands belong to the same module (such as face create) and change output formats.

Actions #20

Updated by Junxiao Shi over 7 years ago

disagree with this deprecation. nfd-status is too commonly used. It is not even equivalent in typing the same number of characters.
nfd-status should be kept as an alias and I don't see the reason not to have it perpetually.

While nfd-status is commonly used, its command line options are rarely used.
How about keeping nfd-status (without options) as a permanent alias of nfdc status report, while deprecating any invocation with command line options?
This would allow eventual removal of nfdc legacy-nfd-status subcommand.

Actions #21

Updated by Alex Afanasyev over 7 years ago

While nfd-status is commonly used, its command line options are rarely used.
How about keeping nfd-status (without options) as a permanent alias of nfdc status report, while deprecating any invocation with command line options?
This would allow eventual removal of nfdc legacy-nfd-status subcommand.

This sounds good to me.

Actions #22

Updated by Junxiao Shi over 7 years ago

  • Status changed from Code review to Closed
Actions

Also available in: Atom PDF