From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Newsgroups: gmane.lisp.guile.bugs Subject: bug#71300: [PATCH v3] doc: Document SRFI 64. Date: Sun, 22 Dec 2024 22:34:44 +0100 Message-ID: <87ldw7fll7.fsf_-_@gnu.org> References: <20240601021743.808-1-maxim.cournoyer@gmail.com> <20240915042603.8529-1-maxim.cournoyer@gmail.com> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="1274"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: 71300-done@debbugs.gnu.org, Tomas Volf <~@wolfsden.cz>, Filip =?UTF-8?Q?=C5=81ajszczak?= , Maxime Devos To: Maxim Cournoyer Original-X-From: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Sun Dec 22 22:36:27 2024 Return-path: Envelope-to: guile-bugs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1tPTch-0000Dn-Ka for guile-bugs@m.gmane-mx.org; Sun, 22 Dec 2024 22:36:27 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tPTcO-0008UU-JJ; Sun, 22 Dec 2024 16:36:08 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tPTcN-0008U7-0B for bug-guile@gnu.org; Sun, 22 Dec 2024 16:36:07 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tPTcI-0008Rj-8M for bug-guile@gnu.org; Sun, 22 Dec 2024 16:36:06 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:Date:References:In-Reply-To:From:To:Subject; bh=CZRR7iD+ve44OQL41w8gNtmY8H6ZzzD6Uk3QDCGZPCQ=; b=mPyhRc7Vq9B6EVVHWjRxSvfBAK/QcltpR5548IHK8TblVkImGOF/Fb3ZBGAeYizzjezURjlI1o+CQx323odN5TPqpgVYmdx25EZVFRmpyqEHAvbwJ1QDRpEZ4Huq3zrWQxfvmlgYpI9CKyb8Ub6ipD3E6ElJ7pdi6Jn337TpbPQ6kKbJlL4BjVmk87rV8WGag0aYx526NdX5n6gm2xpp9WUT5GwSI0/EREn42iS9ztfJyvLJWDvWPnL/7h7iKhx3htf1BK217PPVJ7gIhX32elvRDFd20ObaHMYJA5HXS6cshGPpdIHiCKSNXGWSxlmx0r33xjRRHp2kKKf4TT/XhA==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1tPTcI-0002po-3i for bug-guile@gnu.org; Sun, 22 Dec 2024 16:36:02 -0500 Resent-From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-To: bug-guile@gnu.org Resent-Date: Sun, 22 Dec 2024 21:36:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: cc-closed 71300 X-GNU-PR-Package: guile X-GNU-PR-Keywords: patch Mail-Followup-To: 71300@debbugs.gnu.org, ludo@gnu.org, maxim.cournoyer@gmail.com Original-Received: via spool by 71300-done@debbugs.gnu.org id=D71300.173490330510536 (code D ref 71300); Sun, 22 Dec 2024 21:36:01 +0000 Original-Received: (at 71300-done) by debbugs.gnu.org; 22 Dec 2024 21:35:05 +0000 Original-Received: from localhost ([127.0.0.1]:52207 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tPTbM-0002jL-JO for submit@debbugs.gnu.org; Sun, 22 Dec 2024 16:35:05 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:36326) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tPTbL-0002hx-6M for 71300-done@debbugs.gnu.org; Sun, 22 Dec 2024 16:35:03 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tPTbB-000877-KM; Sun, 22 Dec 2024 16:34:55 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=CZRR7iD+ve44OQL41w8gNtmY8H6ZzzD6Uk3QDCGZPCQ=; b=XlbbJgYgSfTOms2BTNhE 5g34vBrr/Bv0+ao0C754WF1Oyny7xfqv/lXNExHeAVde8HPPUiknIgJAhaAxcZM68/5rlk3lpbCn5 pb2/eIAXdrqRw+OWrMmtMmRwIjBYlZ50BH1zhKqYGBjbTJ0ZSV6E/RiF5rnCwsdqEqG116Dif3l7/ CLt+wkqUfMydPdKj9vXSIhFyVygnulh4h5bysK9ydi4/ySbksbQA8bo4GxRDjIvOE2mNivJQTN1kY FGGzwBBnLAEheoujveO3QuobknBVMmc6I3rghnPQTudtIeLeSWcRrwAaMOIR2F75IjxAHTRP23juP XhpazGUI3EwzJA==; In-Reply-To: <20240915042603.8529-1-maxim.cournoyer@gmail.com> (Maxim Cournoyer's message of "Sun, 15 Sep 2024 13:25:46 +0900") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-guile@gnu.org List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Original-Sender: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.lisp.guile.bugs:11129 Archived-At: --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hi Maxim, Maxim Cournoyer skribis: > This is an import of the 'Abstract', 'Rationale', and 'Specification' > sections from the upstream specification text, with some manual > adjustment. > > * doc/ref/srfi-modules.texi (SRFI 64): New subsection. Finally applied with the typographical changes below, for consistency with (most of) the rest of the manual. Thanks, Ludo=E2=80=99. --=-=-= Content-Type: text/x-patch Content-Disposition: inline diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index 4bad8abbf..db54428ad 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -56,7 +56,7 @@ get the relevant SRFI documents from the SRFI home page * SRFI-60:: Integers as bits. * SRFI-61:: A more general `cond' clause * SRFI-62:: S-expression comments. -* SRFI 64:: A Scheme API for test suites. +* SRFI-64:: Writing test suites. * SRFI-67:: Compare procedures * SRFI-69:: Basic hash tables. * SRFI-71:: Extended let-syntax for multiple values. @@ -5295,22 +5295,23 @@ S-expression comments by default. @c This SRFI 64 documentation was "snarfed" from upstream specification @c HTML document using the 'snarfi' script. -@node SRFI 64 -@subsection SRFI 64: A Scheme API for test suites -@cindex SRFI 64 +@node SRFI-64 +@subsection SRFI-64: A Scheme API for Test Suites +@cindex SRFI-64, test suites +@cindex test suites, SRFI-64 @menu -* SRFI 64 Abstract:: -* SRFI 64 Rationale:: -* SRFI 64 Writing basic test suites:: -* SRFI 64 Conditonal test-suites and other advanced features:: -* SRFI 64 Test-runner:: -* SRFI 64 Test results:: -* SRFI 64 Writing a new test-runner:: +* SRFI-64 Abstract:: +* SRFI-64 Rationale:: +* SRFI-64 Writing Basic Test Suites:: +* SRFI-64 Conditonal Test Suites and Other Advanced Features:: +* SRFI-64 Test Runner:: +* SRFI-64 Test Results:: +* SRFI-64 Writing a New Test Runner:: @end menu -@node SRFI 64 Abstract -@subsubsection SRFI 64 Abstract +@node SRFI-64 Abstract +@subsubsection SRFI-64 Abstract This defines an API for writing @dfn{test suites}, to make it easy to portably test Scheme APIs, libraries, applications, and implementations. @@ -5319,8 +5320,8 @@ context of a @dfn{test-runner}. This specification also supports writing new test-runners, to allow customization of reporting and processing the result of running test suites. -@node SRFI 64 Rationale -@subsubsection SRFI 64 Rationale +@node SRFI-64 Rationale +@subsubsection SRFI-64 Rationale The Scheme community needs a standard for writing test suites. Every SRFI or other library should come with a test suite. Such a test suite @@ -5359,8 +5360,8 @@ syntax is to allow specific tests to be skipped without evaluating sub-expressions, or for implementations to add features such as printing line numbers or catching exceptions. -@node SRFI 64 Writing basic test suites -@subsubsection SRFI 64 Writing basic test suites +@node SRFI-64 Writing Basic Test Suites +@subsubsection SRFI-64 Writing Basic Test Suites Let's start with a simple example. This is a complete self-contained test-suite. @@ -5607,8 +5608,8 @@ For example: @end lisp @end deffn -@node SRFI 64 Conditonal test-suites and other advanced features -@subsubsection SRFI 64 Conditonal test-suites and other advanced features +@node SRFI-64 Conditonal Test Suites and Other Advanced Features +@subsubsection SRFI-64 Conditonal Test Suites and Other Advanced Features The following describes features for controlling which tests to execute, or specifying that some tests are @emph{expected} to fail. @@ -5716,8 +5717,8 @@ not test execution. For example: @end lisp @end deffn -@node SRFI 64 Test-runner -@subsubsection SRFI 64 Test-runner +@node SRFI-64 Test Runner +@subsubsection SRFI-64 Test Runner A @dfn{test-runner} is an object that runs a test-suite, and manages the state. The test group path, and the sets skip and expected-fail @@ -5787,14 +5788,14 @@ Executes each @var{decl-or-expr} in order in a context where the current test-runner is @var{runner}. @end deffn -@node SRFI 64 Test results -@subsubsection SRFI 64 Test results +@node SRFI-64 Test Results +@subsubsection SRFI-64 Test Results Running a test sets various status properties in the current test-runner. This can be examined by a custom test-runner, or (more rarely) in a test-suite. -@subsubheading Result kind +@subsubheading Result Kind Running a test may yield one of the following status symbols: @@ -5912,13 +5913,13 @@ The error value, if an error was signalled and it is known. The actual error value is implementation-defined. @end table -@node SRFI 64 Writing a new test-runner -@subsubsection SRFI 64 Writing a new test-runner +@node SRFI-64 Writing a New Test Runner +@subsubsection SRFI-64 Writing a New Test Runner This section specifies how to write a test-runner. It can be ignored if you just want to write test-cases. -@subsubheading Call-back functions +@subsubheading Call-back Functions These call-back functions are ``methods'' (in the object-oriented sense) of a test-runner. A method @code{test-runner-on-@var{event}} is called --=-=-=--