NFD

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.

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.

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.

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.

Then I also vote for option A.

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.

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.

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.

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.

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.

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.

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.