Subject: Re: bug#71300: [PATCH v3] doc: Document SRFI 64.
From: Ludovic Courtès <[email-masked]>
To: Maxim Cournoyer <[email-masked]>
Cc: [email-masked], Tomas Volf <[email-masked]>, Filip Łajszczak <[email-masked]>, Maxime Devos <[email-masked]>
Date: Sun, 22 Dec 2024 22:34:44 +0100
List-Id: <debbugs-submit.debbugs.gnu.org>

Hi Maxim,

Maxim Cournoyer <[email-masked]> 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’.

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