[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Jacob Bachmeyer
Subject: Re: PATCH: add "dejagnu report card" command [revised]
Date: Tue, 01 Jan 2019 04:04:57 -0600
User-agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv: Gecko/20090807 MultiZilla/ SeaMonkey/1.1.17 Mnenhy/

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 \

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'.


-- Jacob

reply via email to

[Prev in Thread] Current Thread [Next in Thread]