Re: PATCH: add dejagnu-report-card(1) tool (run as "dejagnu report card")

[Jacob Bachmeyer]

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