--- /dev/null
+.\" Copyright (C) 2018 Free Software Foundation, Inc.
+.\" You may distribute this file under the terms of the GNU Free
+.\" Documentation License.
+.Dd December 31, 2018
+.Os GNU
+.Dt DEJAGNU-REPORT-CARD 1 URM
+.Sh NAME
+.Nm dejagnu\ report\ card
+.Nd summarize results from testing multiple tools
+.Sh SYNOPSIS
+.Nm dejagnu\ report\ card
+.Oo Ao Ar option Ac \*(Ba Ao Ar tool Ac \*(Ba Ao Ar file Ac Oc ...
+.Sh DESCRIPTION
+The
+.Nm
+command displays results from testing multiple tools in a tabular format.
+The produced table lists, for each tool (and if multiple passes were run,
+each pass) the number of tests passed, failed, unsupported, unresolved, and
+untested. Tests that are expected to fail are counted in separate columns
+from tests expected to pass, but "known" failures and "expected" failures
+are summarized together. If a test generated warnings or errors, a tag
+.Ql !W!
+or
+.Ql !E!
+is appended at the end of the relevant line.
+.Pp
+Aside from options, the argument list may include tool or file names. The
+.Nm
+command prefers to read DejaGnu summary files and will translate names accordingly:
+.Bl -tag -width ".Pa *.sum"
+.It Pa *.sum
+Used as-is.
+.It Pa *.log
+Rewritten to
+.Pa *.sum
+with the same stem.
+.It Pa *.
+The string
+.Pa sum
+is appended to select a summary file. This processing is done for
+convenience when using Readline file name completion in a shell, which will
+complete to the dot.
+.It Pa *
+Taken as a tool name;
+.Pa .sum
+is appended.
+.El
+.Sh OPTIONS
+.Bl -tag -width ".Fl v , -verbose"
+.It Fl v , -verbose
+Emit additional output describing the operation of
+.Nm
+itself.
+.El
+.Sh FILES
+The
+.Nm
+command produces its output by reading the summary files produced by
+DejaGnu and counting "PASS", "FAIL", etc.
+.Pp
+If no names are given as arguments, all files matching
+.Pa *.sum
+in the current directory are read.
+.Sh EXAMPLES
+.Ss A simple example from DejaGnu's own testsuite
+.Bd -literal
+$ dejagnu report card
+\ __________________________________________________
+\ / PASS FAIL ?PASS ?FAIL UNSUP UNRES UNTEST
+\ |--------------------------------------------------
+\ launcher | 52 0 0 0 0 0 0
+libdejagnu | 5 0 0 0 0 0 0
+\ runtest | 135 0 0 0 0 0 0
+\ |--------------------------------------------------
+\ | 192 0 0 0 0 0 0
+\ \\__________________________________________________
+.Ed
+.Pp
+Three tools were tested, with a total of 192 tests, all expected to pass.
+In this example, all tests did pass, so all other columns are zero. The
+.Ql ?PASS
+and
+.Ql ?FAIL
+columns count tests known or expected to fail that either unexpectedly
+passed or failed as expected. The remaining three columns count the
+exceptional results for unsupported tests, unresolved tests and stub tests
+that simply declare themselves untested.
+.Pp
+.ne 16v
+.Ss The same example after tests were added for dejagnu-report-card
+.Bd -literal
+$ dejagnu report-card
+\ __________________________________________________
+\ / PASS FAIL ?PASS ?FAIL UNSUP UNRES UNTEST
+\ |--------------------------------------------------
+\ launcher | 52 0 0 0 0 0 0
+\ libdejagnu | 5 0 0 0 0 0 0
+report-card / awk | 36 0 0 0 0 0 0
+report-card / sh | 36 0 0 0 0 0 0
+report-card / tcl | 36 0 0 0 0 0 0
+\ runtest | 135 0 0 0 0 0 0
+\ |--------------------------------------------------
+\ awk | 36 0 0 0 0 0 0
+\ sh | 36 0 0 0 0 0 0
+\ tcl | 36 0 0 0 0 0 0
+\ |--------------------------------------------------
+\ | 300 0 0 0 0 0 0
+\ \\__________________________________________________
+.Ed
+.Pp
+The
+.Ql report-card
+tool has been added, with three passes, one for each implementation. (The
+shell and Tcl implementations were later dropped to reduce future
+maintenance burden.) As before, all tests passed as expected. The
+interesting difference from the previous example is the use of DejaGnu's
+multipass testing feature and the additional per-pass summary lines added.
+For this example, only the
+.Ql report-card
+tool uses multipass testing, so each pass total is simply the count of
+tests for
+.Ql report-card
+instead of a distinct total.
+.Pp
+Also note that the command used to invoke
+.Nm
+is slightly different here. The
+.Xr dejagnu 1
+launcher will also accept multiple words joined with dashes into a single
+argument. This allows individual words in a command name to be separated
+with either dashes or spaces on the command line interchangeably.
+.Sh SEE ALSO
+.Xr dejagnu 1
+.Xr runtest 1
+.Pp
+The full documentation for DejaGnu is maintained as a Texinfo manual. If the
+.Nm info
+program is properly installed at your site, the command
+.Li info dejagnu
+should give you access to the complete manual.
+.Sh AUTHORS
+.An Jacob Bachmeyer
+.\".Sh BUGS
+.\" LocalWords: Dt dejagnu URM Nm Ao Oo Oc DejaGnu Xr runtest DejaGnu's Bd Ql
+.\" LocalWords: testsuite UNSUP UNRES UNTEST libdejagnu Readline Ss tcl awk
+.\" LocalWords: ne multipass
OSDN Git Service
