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
_______________________________________________
DejaGnu mailing list
DejaGnu@gnu.org
https://lists.gnu.org/mailman/listinfo/dejagnu
