Ben Elliston wrote:
On Sun, Dec 30, 2018 at 02:17:12AM -0600, Jacob Bachmeyer wrote:
[...]
That said, the dejagnu subcommands need canonical names for
documentation. Should those be like "dejagnu-report-card" (using a
launcher symlink) or "dejagnu report-card" (standard name for
launcher, explicit full name for command)?
Why not just document them all in the dejagnu(1) man page? I see no
reason why not. It's easy to hit / and search for the subcommand of
interest.
The first reason that comes to mind is the Single Point of Truth
principle: listing dejagnu(1) subcommands is something that dejagnu(1)
itself should do (PR33821) using the set of commands that are actually
present in the commands directory. This avoids the documentation
getting out-of-sync with the actual code. I see expecting a table
"somewhere else" to be updated when commands are added as asking for
trouble.
This also leads to a question of the best format to use for listing
commands. The current plan is to simply list available commands in
tabular form, but retrieving descriptions from the command scripts would
not be difficult and could provide a "two-column" format with a command
name and brief description of each, like "git help" presents for the
most commonly used commands.
-- Jacob
_______________________________________________
DejaGnu mailing list
DejaGnu@gnu.org
https://lists.gnu.org/mailman/listinfo/dejagnu
