Feature #3780
closednfdc status commands
100%
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
.
Updated by Junxiao Shi over 8 years ago
- Related to Feature #2542: Redesign nfdc combining nfdc and nfd-status added
Updated by Junxiao Shi over 8 years ago
- Blocked by Feature #3749: nfdc one-shot mode added
Updated by Junxiao Shi over 8 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
Updated by Junxiao Shi over 8 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.
Updated by Junxiao Shi over 8 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
, andman nfdc-route-remove
open the same manpage that contains information for all three commands.man nfdc-status-show
andman nfdc-status-report
open two distinct manpages. - Aliases are not limited to within the same noun.
man nfdc-create
andman nfdc-destroy
both operate on faces, so they can share a manpage.
Updated by Davide Pesavento over 8 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.
Updated by Junxiao Shi over 8 years ago
open
nfdc-<noun>-<verb>
if it exists, otherwise fall back tonfdc-<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.
Updated by Alex Afanasyev over 8 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.
Updated by Junxiao Shi over 8 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 onman nfdc-face
. - When a legacy command is later re-implemented, take
nfdc create
as an example:nfdc create
is deleted fromman nfdc-face
.man nfdc-create
becomes a separate page that indicatesnfdc 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
.
Updated by Eric Newberry about 8 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.
Updated by Junxiao Shi about 8 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.
Updated by Eric Newberry about 8 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.
Updated by Junxiao Shi about 8 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
.
Updated by Junxiao Shi about 8 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.
Updated by Junxiao Shi about 8 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
.
Updated by Junxiao Shi about 8 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
.
Updated by Junxiao Shi about 8 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.
Updated by Junxiao Shi about 8 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.
Updated by Alex Afanasyev about 8 years ago
While
nfd-status
is commonly used, its command line options are rarely used.
How about keepingnfd-status
(without options) as a permanent alias ofnfdc status report
, while deprecating any invocation with command line options?
This would allow eventual removal ofnfdc legacy-nfd-status
subcommand.
This sounds good to me.
Updated by Junxiao Shi about 8 years ago
- Status changed from Code review to Closed