Re: PATCH: add "dejagnu report card" command [revised]

[Jacob Bachmeyer]

Ben Elliston wrote:
> On Mon, Dec 31, 2018 at 11:56:10PM -0600, Jacob Bachmeyer wrote:
>   
> > -DISTCLEANFILES = options-init.exp stats-init.exp
> > +DISTCLEANFILES = options-init.exp stats-init.exp \
> > +       testsuite/launcher.all/command/bin/dejagnu \
> > +       testsuite/launcher.all/command/bin/dejagnu-bar \
> >     
> [etc.]
>
> It should not be necessary to list all of these files for
> distclean. Automake only copies what you specify, so these should be
> able to be omitted. By the way, you do build in a separate object
> directory, right? That keeps your source tree clean of object and
> derived files.
>   

I build in a separate object directory and then confirm that only 
directories remain after "make distclean" in the object tree.  Those 
files are not part of the source distribution at all -- they are written 
by the testsuite.  (The entries in "launcher.all/commands" are not even 
files -- those are symlinks into the source tree that were missed in a 
previous patch because "find -type f" is not "find ! -type d" ... oops.)

> > TEXINFO_TEX = doc/texinfo.tex
> > -dist_man_MANS = doc/dejagnu.1 doc/dejagnu-help.1 doc/runtest.1
> > +dist_man_MANS = doc/dejagnu.1 \
> > +       doc/dejagnu-help.1 \
> > +       doc/dejagnu-report-card.1 \
> > +       doc/runtest.1
> >     
>
> I am wondering if we should do what other GNU packages do and have a
> skeletal man page for dejagnu(1) but refer users to the Info
> documentation for the details of, eg, dejagnu-report-card?
>   

On one hand, the GNU Coding Standards encourage that practice; on the 
other hand, users strongly expect man pages (enough that I recall Debian 
making a systematic effort to add man pages for everything in their 
distribution) and man pages (are supposed to) have a different style 
from Texinfo documentation to the extent that the information included 
in them is different -- as an example, the Info node for 
dejagnu-report-card contains only usage and a description of the output, 
while the man page also includes some examples that I do not believe 
"fit" in the Texinfo manual, or at least not in the "Invoking dejangu 
report card" node.  (That may be a documentation bug, but it is a bug 
that I currently do not know how to fix.)  Similarly, the Info node for 
the launcher describes only the direct user-facing features, while the 
man page goes a bit more into the implementation details, although the 
details in dejagnu.1 and not in dejagnu.texi are again poor fits for an 
"Invoking ..." node and I do not know where to put them in the Texinfo 
manual.

This goes the other way, too -- man pages are really only good for quick 
reference and are a very poor way to document an API as a whole.  
Texinfo works much better for reading through while initially learning 
to use an API, and the Info index search commands make up for the 
advantage man pages have of quickly going to a particular topic.

Generally, speaking from my own experience, man pages work very well for 
command references for simple or non-interactive commands and Info works 
better for API documentation and more complex manuals, especially for 
large interactive programs or programming languages.  (The full Emacs 
manual as man pages would be ... a mess, to put it mildly, and I 
literally learned Awk from reading the GNU Awk manual straight through 
-- that manual is very good.)  Emacs actually does have a man page, 
however:  emacs(1) describes only the command line syntax and X 
resources used.

Lastly, note that the man pages are what "dejagnu help" displays, so 
keeping them useful (and not trivial stubs) is likely to be important to 
many users, particularly the relative novices for which I am trying to 
make DejaGnu more accessible.

> I will also make the change to 'configure' to abort if AC_PROG_AWK
> returns 'no'.
>   

Thanks.



-- Jacob