bug#41355: [PATCH] Fix typos in the manual

[Ludovic Courtès]

Hi,

jsyna...@redhat.com skribis:

> From: Jan Synacek 
>
> * doc/ref/api-control.texi:
> * doc/ref/r6rs.texi:
> * doc/ref/sxml.texi: Fix typos.

Applied, thanks!

Ludo’.

bug#41355: [PATCH] Fix typos in the manual

[jsynacek]

From: Jan Synacek 

* doc/ref/api-control.texi:
* doc/ref/r6rs.texi:
* doc/ref/sxml.texi: Fix typos.
---
 doc/ref/api-control.texi | 4 ++--
 doc/ref/r6rs.texi| 2 +-
 doc/ref/sxml.texi| 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index b62c0d6fe..5df5344c5 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -678,8 +678,8 @@ Evaluate @var{expr} in a prompt, optionally specifying a 
tag and a
 handler.  If no tag is given, the default prompt tag is used.
 
 If no handler is given, a default handler is installed.  The default
-handler accepts a procedure of one argument, which will called on the
-captured continuation, within a prompt.
+handler accepts a procedure of one argument, which will be called on
+the captured continuation, within a prompt.
 
 Sometimes it's easier just to show code, as in this case:
 
diff --git a/doc/ref/r6rs.texi b/doc/ref/r6rs.texi
index c47eef7d1..e430708d0 100644
--- a/doc/ref/r6rs.texi
+++ b/doc/ref/r6rs.texi
@@ -1173,7 +1173,7 @@ evaluates to @code{baz}.
 
 @deffn {Scheme Procedure} raise obj
 Equivalent to core Guile @code{(raise-exception @var{obj})}.
-@xref{Raising and Handling Exceptions}.  p(Unfortunately, @code{raise}
+@xref{Raising and Handling Exceptions}.  (Unfortunately, @code{raise}
 is already bound to a different function in core Guile.
 @xref{Signals}.)
 @end deffn
diff --git a/doc/ref/sxml.texi b/doc/ref/sxml.texi
index 19125091c..5f827916e 100644
--- a/doc/ref/sxml.texi
+++ b/doc/ref/sxml.texi
@@ -230,7 +230,7 @@ SAX parsers were created to give the programmer more 
control on the
 parsing process.  A programmer gives the SAX parser a number of
 ``callbacks'': functions that will be called on various features of the
 XML stream as they are encountered.  SAX parsers are more efficient, but
-much harder to user, as users typically have to manually maintain a
+much harder to use, as users typically have to manually maintain a
 stack of open elements.
 
 Kiselyov realized that the SAX programming model could be made much
-- 
2.26.2

bug#30276: typos in the manual (api-macros, vm)

[Mark H Weaver]

Matt Wette  writes:

> A couple typos in the maual
>
> --- api-macros.texi-fix   2018-01-28 13:22:52.305712852 -0800
> +++ api-macros.texi   2017-11-19 11:22:01.0 -0800
> @@ -1280,7 +1280,7 @@
>  In this way @code{(macroexpand @var{foo})} is equivalent to
>  @code{(macroexpand @var{foo} 'e '(eval))}.  The second argument is the
> -mode (@code{'e} for ``eval'') and the third is the
> +mode (@code{'e} for ``eval'') and the second is the
>  eval-syntax-expanders-when parameter (only @code{eval} in this default
>  setting).
>  --- vm.texi  2017-05-13 09:41:37.0 -0700
> +++ vm.texi-fix   2018-01-28 13:21:31.621618026 -0800
> @@ -719,7 +719,7 @@
>  For calls, both in tail position and in non-tail position, we require
>  that the procedure and the arguments already be shuffled into place
> -befor the call instruction.  ``Into place'' for a tail call means that
> +before the call instruction.  ``Into place'' for a tail call means that
>  the procedure should be in slot 0, relative to the @code{fp}, and the
>  arguments should follow.  For a non-tail call, if the procedure is in
>  @code{fp}-relative slot @var{n}, the arguments should follow from slot

Applied in commit 6d9c6833e78e560420a7805bf73a9dfbaa4b0cbb on the
stable-2.2 branch.

 Thanks!
   Mark

bug#30276: typos in the manual (api-macros, vm)

[Matt Wette]

A couple typos in the maual

--- api-macros.texi-fix 2018-01-28 13:22:52.305712852 -0800
+++ api-macros.texi 2017-11-19 11:22:01.0 -0800
@@ -1280,7 +1280,7 @@
 
 In this way @code{(macroexpand @var{foo})} is equivalent to

 @code{(macroexpand @var{foo} 'e '(eval))}.  The second argument is the
-mode (@code{'e} for ``eval'') and the third is the
+mode (@code{'e} for ``eval'') and the second is the
 eval-syntax-expanders-when parameter (only @code{eval} in this default
 setting).
 
--- vm.texi	2017-05-13 09:41:37.0 -0700

+++ vm.texi-fix 2018-01-28 13:21:31.621618026 -0800
@@ -719,7 +719,7 @@
 
 For calls, both in tail position and in non-tail position, we require

 that the procedure and the arguments already be shuffled into place
-befor the call instruction.  ``Into place'' for a tail call means that
+before the call instruction.  ``Into place'' for a tail call means that
 the procedure should be in slot 0, relative to the @code{fp}, and the
 arguments should follow.  For a non-tail call, if the procedure is in
 @code{fp}-relative slot @var{n}, the arguments should follow from slot

Re: Typos in the manual

[Ludovic Courtès]

Hi,

Ralf Wildenhues  writes:

> * Bruno Haible wrote on Sat, Feb 19, 2011 at 06:40:23PM CET:
>> Regarding this commit:
>> 
>> Ralf Wildenhues wrote in 
>> :
>> 
>> > > > latin1 vs. latin-1,
>> > > 
>> > > I'm happy to defer to you on that.  What do you recommend?
>> > 
>> > Never mind on this one.  Prose already uses latin-1 consistently in the
>> > *.texi files, and I assume actual code references to Guile and Emacs
>> > code need use the spelling that is correct there.
>> 
>> Actually, "latin1" is a standardized encoding name (standardized by IANA in
>> ), whereas "latin-1" is not.
>
> Yes, that's what I meant when I wrote "actual code references", but
> obviously I was way too terse and failed to express myself clearly at
> all.  Ludo, could you revert those bits?

Done, thanks!

Ludo’.

Re: Typos in the manual

[Ludovic Courtès]

Hi Mark,

Mark Harig  writes:

> Here are the relevant rules that I learned years ago.  They are
> followed by some examples from the Emacs manual (which also contains
> many examples that do not follow these rules).

Thanks for the informative post, I’ll try to keep that in mind!

Like Andy, I would welcome improvements in this area in the manual.  :-)

Thanks,
Ludo’.

Re: Typos in the manual

[Ralf Wildenhues]

Hi Bruno,

* Bruno Haible wrote on Sat, Feb 19, 2011 at 06:40:23PM CET:
> Regarding this commit:
> 
> Ralf Wildenhues wrote in 
> :
> 
> > > > latin1 vs. latin-1,
> > > 
> > > I'm happy to defer to you on that.  What do you recommend?
> > 
> > Never mind on this one.  Prose already uses latin-1 consistently in the
> > *.texi files, and I assume actual code references to Guile and Emacs
> > code need use the spelling that is correct there.
> 
> Actually, "latin1" is a standardized encoding name (standardized by IANA in
> ), whereas "latin-1" is not.

Yes, that's what I meant when I wrote "actual code references", but
obviously I was way too terse and failed to express myself clearly at
all.  Ludo, could you revert those bits?

> Therefore it's a good idea to use in the documentation the standardized name
> and not some different name that appears "prettier" but does not actually 
> work.

I agree.

Thanks for proof-reading!
Ralf

Re: Typos in the manual

[Bruno Haible]

Regarding this commit:


Ralf Wildenhues wrote in 
:

> > > latin1 vs. latin-1,
> > 
> > I'm happy to defer to you on that.  What do you recommend?
> 
> Never mind on this one.  Prose already uses latin-1 consistently in the
> *.texi files, and I assume actual code references to Guile and Emacs
> code need use the spelling that is correct there.

Actually, "latin1" is a standardized encoding name (standardized by IANA in
), whereas "latin-1" is not.

While some software recognizes "latin-1" as an alias for "latin1", other
software doesn't, like 'iconv' in glibc and GNU libiconv:

  $ echo abc | iconv -t latin1
  abc
  $ echo abc | iconv -t latin-1
  iconv: conversion to `latin-1' is not supported
  Try `iconv --help' or `iconv --usage' for more information.

Therefore it's a good idea to use in the documentation the standardized name
and not some different name that appears "prettier" but does not actually work.

Bruno
-- 
In memoriam Friedrich Weißler 

Re: Typos in the manual

[Andy Wingo]

On Thu 17 Feb 2011 04:13, Mark Harig  writes:

> Here are the relevant rules that I learned years ago.  They are
> followed by some examples from the Emacs manual (which also contains
> many examples that do not follow these rules).

A very interesting discussion!  At first read, your rules about em
dashes and semicolons and i.e. and e.g. all sounded very strident to me,
but then your examples support your points well -- the texts evince the
rules.  To my untrained eye and irreverent hand, anyway.

So... roll on, Guile manual, roll on?  Hopefully you and Neil will fall
into a state of mental synchronization, so that we do productive work on
the manual.  Though if you get too synchronized we list-readers will
lose the benefit of these digressions :)

Cheers,

Andy
-- 
http://wingolog.org/

Re: Typos in the manual

[Mark Harig]

> By "simple" we mean data types that are not primarily used as
> containers to hold other data -- i.e. pairs, lists, vectors and so
> on.

This should be “to hold other data---i.e., pairs”, i.e., this should
be an em dash with no surrounding spaces.



Agreed, except that both instances of the Latin abbreviations in your
sentence should be replaced by the words "that is", and both instances
should be preceded by an em dash:

  This should be “to hold other data---that is, pairs”---that is,
  this should be an em dash with no surrounding spaces.

Unfortunately, this opens another can of worms because the internet is
chock full of people using Latin abbreviations in English sentences
outside of parenthetical expressions.


Here are the relevant rules that I learned years ago.  They are
followed by some examples from the Emacs manual (which also contains
many examples that do not follow these rules).

1) Primarily, English sentences should contain English words.  Numbers
should be spelled out when they are in the low digits.  When foreign
words or phrases are included, they should be printed in italics
(unless they have already been accepted into English).  This applies
to general writing.  Mathematics and other academic fields have their
own specialized rules.

2) Because of the previous rule, Latin abbreviations should NOT be
used in English sentences, although there is an exception: when they
are used inside and begin parenthesized expressions, (e.g., inside
this expression).  This applies to "i.e.", "e.g.", and "etc.".  The
abbreviations "i.e." and "e.g." should always be followed by a comma.

3) Clauses that are set off with "that is," or "for example," should
begin with an em dash, and if the clause is in the interior of the
sentence it should be followed with an em dash.  If the following
clause is an independent clause then the em dash is not required.


Examples for rule 2)

- "Send mail through an external mail host (e.g., your Internet
  service provider's SMTP server)."

- "You can force these commands to move according to 'logical lines'
  (i.e., according to the text lines in the buffer) by setting the
  variable `line-move-visual' to `nil'; if a logical line occupies
  multiple screen lines, the cursor then skips over the additional
  screen lines."

- "Finally, you can set the mark by holding down the shift key while
  typing certain cursor motion commands (such as `S-',
  `S-C-f', `S-C-n', etc.)"


Examples for rule 3)

- "Note that in order to insert rows after the last row at the bottom
  of a table, you must place point below the table--that is, outside
  the table--prior to invoking this command."

- "When you edit a file that changes automatically and frequently--for
  example, a log of output from a process that continues to run--it
  may be useful for Emacs to revert the file without querying you."

- "Letters represent various nontrivial 'coding systems'--for example,
  `1' represents ISO Latin-1."

- "This feature is useful for certain character-only terminals built
  to support specific languages or character sets--for example,
  European terminals that support one of the ISO Latin character
  sets."

- `\{N\}' is a postfix operator that specifies repetition N
  times--that is, the preceding regular expression must match exactly
  N times in a row.

- "You will probably want to use a fixed-width default font--that is,
  a font in which all characters have the same width."

- "The command `C-c C-b' (`message-goto-body') moves point to just
  after the header separator line--that is, to the beginning of the
  body."


The next examples, which do NOT use em dashes, are INCORRECT.  The
semicolon should be replaced with an em dash.  The em dash is required
when the subordinate clause is not an independent clause.

- "A date may be "generic"; that is, partially unspecified."

- "By convention, a command name consists of one or more words,
 separated by hyphens; for example, `auto-fill-mode' or
 `manual-entry'."

- "This variable, like all the variables that control Font Lock mode,
  take effect whenever fontification is done; that is, potentially at
  any time."


The next examples, which do NOT use em dashes, are CORRECT.  The
clauses are independent clauses that can stand on their own (they have
their own subject and predicate).

- "The numbers of days shown is inclusive; that is, it includes the
  days specified by mark and point."

- "`C-x C-s' used on a buffer that is not visiting a file has the same
  effect as `C-x C-w'; that is, it reads a file name, marks the
  buffer as visiting that file, and saves it there."

- "However, if a word starts with single-quotes, these are treated as
  a prefix for purposes such as capitalization.  That is, `M-c' will
  convert `'hello'' into `'Hello'', as expected."

- "Some Emacs commands are invoked by just one input event; for
  example, `C-f' moves forward one character in the buffer."

- "Many Emacs commands move point to different places i

Re: Typos in the manual

[Mark Harig]

>
> >> > Something that's long been a mystery to me is why it is that
> >> > computer programmers, who spend their days learning and
> >> > following the rules and idioms of various programming
> >> > languages, do not want to learn and follow the rules and
> >> > idioms of natural languages.
> >>
> >> Because computer languages are constrained by the specifications 

and

> >> tools that interpret them, whereas natural languages evolve and
> >> diverge through human usage?
>
> When I read your para above before, it (strangely) didn't occur to 

me

> that it could be intended to include reference to me and the Guile
> manual.  Hence my general reply above, about the practical 

constraints

> on computer language evolution being tighter than those on human
> languages.
>


It wasn't intended to reference you or the Guile reference manual.  It
was a response to Ralf Wildenhues's recounting that he had submitted
patches that corrected usage to many projects and had them rejected.

> Just to be clear then, I didn't mean to imply that.  In fact I 

believe
> that I and the Guile manual do "follow the rules and idioms of 

natural

> languages."  Note in particular that this thread about "i.e.," is
> nothing to do with the looseness of human language constraints 

(i.e.,
> the kind of thing that allows many people today to say "you was" 

rather
> than "you were").  It's to do with a convention that has forked in 

two

> standard forms of English.
>


Understood.


> > 4) Programmers develop strong opinions about what is ugly or clean
> > in computer languages, despite the fact that this is not 

described in

> > the language specifications.  Yet, when something is pointed out
> > as clean or ugly in natural language, that developed sense is 

dismissed.

>
> When you say "dismissed", are you including this thread, and/or 

Guile

> manual discussions in general?
>


No, it was a general observation of the irony.

--

Re: Typos in the manual

[Neil Jerram]

l...@gnu.org (Ludovic Courtès) writes:

> Hi!
>
> While we’re at it...
>
> Mark Harig  writes:
>
>> By "simple" we mean data types that are not primarily used as
>> containers to hold other data -- i.e. pairs, lists, vectors and so on.
>
> This should be “to hold other data---i.e., pairs”, i.e., this should be
> an em dash with no surrounding spaces.
>
>   https://secure.wikimedia.org/wikipedia/en/wiki/Emdash#Em_dash

There's an "i.e." without a comma on that page, hooray!  :-)

 Neil

Re: Typos in the manual

[Neil Jerram]

Mark Harig  writes:

> Some of the discussion below was getting too far off-topic [...]

Hi Mark,

Your development of the argument below is interesting, and I think it
could be an interesting discussion to have.  In this email, though, I
just wanted to mention a couple of points, one of which I think I didn't
get quite right in my previous reply.

>> > Something that's long been a mystery to me is why it is that 
> computer
>> > programmers, who spend their days learning and following the rules 
> and
>> > idioms of various programming languages, do not want to learn and
>> > follow the rules and idioms of natural languages.
>>
>> Because computer languages are constrained by the specifications and
>> tools that interpret them, whereas natural languages evolve and 
> diverge
>> through human usage?

When I read your para above before, it (strangely) didn't occur to me
that it could be intended to include reference to me and the Guile
manual.  Hence my general reply above, about the practical constraints
on computer language evolution being tighter than those on human
languages.

Now that that does occur to me, I see that my reply could be read as
implying "yes, I am knowingly not learning and following the rules...".

Just to be clear then, I didn't mean to imply that.  In fact I believe
that I and the Guile manual do "follow the rules and idioms of natural
languages."  Note in particular that this thread about "i.e.," is
nothing to do with the looseness of human language constraints (i.e.,
the kind of thing that allows many people today to say "you was" rather
than "you were").  It's to do with a convention that has forked in two
standard forms of English.

> 4) Programmers develop strong opinions about what is ugly or clean
> in computer languages, despite the fact that this is not described in
> the
> language specifications.  Yet, when something is pointed out as clean
> or ugly in natural language, that developed sense is dismissed.

When you say "dismissed", are you including this thread, and/or Guile
manual discussions in general?

Regards,
Neil

Re: Typos in the manual

[Neil Jerram]

Francis Southern  writes:

> On 15 February 2011 20:43, Mark Harig  wrote:
>>
>> This is the crux of the argument.  Should the GNU Guile manual be
>> written using British English or American English, both in grammar and
>> spelling?  American English usage rules require a comma, while British
>> English requires that there not to be a comma.  There needs to be a
>> decision about which set of usage rules should be used in the primary
>> version of the manual, and then differences can be resolved in
>> translations.  But whichever is decided, it should not be "use a comma
>> if you feel it's needed; otherwise, leave it out."  Reference manuals
>> are not the place for personal style.  Let's leave that for tutorials.
>>
>
> While I agree that a consistent style is desirable for a manual,

You know, actually I disagree with that.

The Guile manual is around 800 pages long, and I think it does no harm
at all to have a little variability, or for different voices to come
through here and there.

It's important for the technical material to be correct and clearly
described, of course.  In my view the other two high level requirements
are that there should be an overall sense of narrative through the
manual, and that any individual section or related group of sections
should read well in their own context.

Clearly, in the world in general, there are significant forces that
encourage closely following a consistent style: basically all commercial
organisations, and in particular journalism.  But I think that's because
they are big organisations with lots of people, and it's easier overall
to lay down rules than to apply judgement in each case.  As things stand
at the moment, I don't think that needs to apply to the Guile manual.

> I
> just wanted to point out that the issue at hand is definitely not a
> British vs. American English debate.
> For example, although he has nothing to say on the matter (that I
> could find), you'll notice that H.W. Fowler quite consistently uses a
> comma after "i.e." and "e.g." in his book, "The King's English" [0].
> I sincerely doubt that anyone would dare to call his English
> Americanised.

Thanks.  And another big British pro-comma reference is the Economist's
style guide.

So I accept that, democratically speaking, I've lost the argument.
Nevertheless, this isn't something that I personally want to spend time
on.  I think there's loads more important stuff to review and improve in
the manual, and I'd rather focus on that.  On the other hand, if there
are more contributors on board in future, and one of them wants to work
on this, I won't object.

I hope that we are now approaching a point where the manual is
technically complete and correct, so please - anyone looking at the
manual - do regard it all as fair game, report any mistakes or problems
in understanding, check that the examples actually work, and so on.

Regards,
   Neil

Re: Typos in the manual

[Neil Jerram]

On 16 February 2011 00:52, Mark Harig  wrote:

> "take a detour" implies that there is an obstacle that is preventing
> the author from what would otherwise be the desirable route.

No, not really.  For example, the Michelin travel guides have been
using the phrase "worth a detour" for many years.

> Also, this is confusing to me because the section is titled "Extending
> the Compiler," which implies (to me) that it will describe how to
> extend the compiler, but instead it is a description of areas of the
> Guile compiler that need improvement and extending.  It might have
> been better titled "Helping Improve and Extend the Compiler."  It
> might also be more appropriate to move this section to an appendix
> because it does not provide instructions.

I think it works fine to have this little piece of encouragement here.
 Moving it elsewhere would dissociate it from its subject (i.e., what
the encouragement is about).

 Neil

Re: Typos in the manual

[Ludovic Courtès]

Hi!

While we’re at it...

Mark Harig  writes:

> By "simple" we mean data types that are not primarily used as
> containers to hold other data -- i.e. pairs, lists, vectors and so on.

This should be “to hold other data---i.e., pairs”, i.e., this should be
an em dash with no surrounding spaces.

  https://secure.wikimedia.org/wikipedia/en/wiki/Emdash#Em_dash

I think I fixed some of them in the past, but not all.  Any takers?  :-)

Thanks,
Ludo’.

Re: Typos in the manual

[Francis Southern]

On 15 February 2011 20:43, Mark Harig  wrote:
>
>> >> Also, while the Chicago Manual of Style recommends it, some other online
>> >> grammar sites mention that it is American English style, but British
>> >> English would not add a comma afterwards.
>>
>> My feeling is consistent with that.  I'm British, and I'd say there are
>> lots of cases where it is more natural (to me) not to have a comma after
>> "i.e." or "e.g.".
>>
>
> This is the crux of the argument.  Should the GNU Guile manual be
> written using British English or American English, both in grammar and
> spelling?  American English usage rules require a comma, while British
> English requires that there not to be a comma.  There needs to be a
> decision about which set of usage rules should be used in the primary
> version of the manual, and then differences can be resolved in
> translations.  But whichever is decided, it should not be "use a comma
> if you feel it's needed; otherwise, leave it out."  Reference manuals
> are not the place for personal style.  Let's leave that for tutorials.
>

While I agree that a consistent style is desirable for a manual, I
just wanted to point out that the issue at hand is definitely not a
British vs. American English debate.
For example, although he has nothing to say on the matter (that I
could find), you'll notice that H.W. Fowler quite consistently uses a
comma after "i.e." and "e.g." in his book, "The King's English" [0].
I sincerely doubt that anyone would dare to call his English
Americanised.

Personally, although it's neither here nor there, I'm pro-comma and
most definitely en_GB.
Francis


[0] - http://www.bartleby.com/116/213.html (An arbitrary page, but if
you search it for "i.e." you'll see the comma.)

Re: Typos in the manual

[Thien-Thi Nguyen]

() Mark Harig 
() Tue, 15 Feb 2011 22:03:39 -0500

   (Why do they miss the large similarities but see the small differences?)

This is a human condition that afflicts even programmers.

Re: Typos in the manual

[Mark Harig]

Some of the discussion below was getting too far off-topic from the
question of whether to follow "i.e." and "e.g." with commas in all
instances or not to follow "i.e." and "e.g." with commas in any 
instance,

so I have written a response in a separate message.



>>
>> > Both "i.e." and "e.g." should always be followed by a comma.
>>
>> Well.  Let me tell you.  I've written those kinds of patches 

before,

>> adding a comma unconditionally and all.  After a few maintainers of
>> some packages rejected them, I've become less enthused.
>>
>
> Something that's long been a mystery to me is why it is that 

computer
> programmers, who spend their days learning and following the rules 

and

> idioms of various programming languages, do not want to learn and
> follow the rules and idioms of natural languages.

Because computer languages are constrained by the specifications and
tools that interpret them, whereas natural languages evolve and 

diverge

through human usage?



Unfortunately, this answer does not resolve the mystery for me.

1) Both computer and natural languages evolve (How else would we
explain, e.g., C90 and C99, among many examples?)

2) Don't confuse the expressiveness and flexibility of natural languages
with a lack of standards.

Standard, written usage of natural language, as opposed to constantly
changing spoken slang, does not evolve very rapidly.  We can read
"The Great Gatsby" without any need to refer to a grammar reference,
despite it's being  written nearly a century ago, not to mention, say, 
Dickens.

Verbs are still verbs, nouns are nouns, sentences still have main and
subordinate clauses, etc.  But I cannot read much of Chaucer without
some translating reference.  Perhaps this is because there were no
dictionaries or grammar references then?

3) Computer language specifications do not say anything about idioms,
and yet programmers consider idioms to be significant.  How can that
be when they are not in the specification?

4) Programmers develop strong opinions about what is ugly or clean
in computer languages, despite the fact that this is not described in 
the

language specifications.  Yet, when something is pointed out as clean
or ugly in natural language, that developed sense is dismissed.

5) Your rhetorical question points out some differences between computer
languages and natural languages while ignoring the quite significant
similarities between them, which for me is the point of the mystery.
(Why do they miss the large similarities but see the small differences?)


> Reference manuals should strive to follow grammar and usage rules as
> much as possible in a jargon-filled context.  There is enough room
> already for confusion and lack of precision.

But surely you don't believe that there is a One True set of "grammar
and usage rules"?



No, I don't believe there is.  But I think this question is a
red-herring.  The reverse red-herring question would be "But surely
you don't believe that there are no grammar and usage rules?"

--

Re: Typos in the manual

[Mark Harig]

>> Also, while the Chicago Manual of Style recommends it, some other
> online
>> grammar sites mention that it is American English style, but 

British

>> English would not add a comma afterwards.

My feeling is consistent with that.  I'm British, and I'd say there 

are
lots of cases where it is more natural (to me) not to have a comma 

after

"i.e." or "e.g.".



This is the crux of the argument.  Should the GNU Guile manual be
written using British English or American English, both in grammar and
spelling?  American English usage rules require a comma, while British
English requires that there not to be a comma.  There needs to be a
decision about which set of usage rules should be used in the primary
version of the manual, and then differences can be resolved in
translations.  But whichever is decided, it should not be "use a comma
if you feel it's needed; otherwise, leave it out."  Reference manuals
are not the place for personal style.  Let's leave that for tutorials.

--

Re: Typos in the manual

[Mark Harig]

> Likewise, "make an intervention" implies that the author intends to
> intervene or stop or prevent something.  But the author is not 

hoping

> to stop compiler junkies from continuing their habit of writing code
> for compilers -- to the contrary.  Given the text that follows this
> phrase, "make an interjection" is probably what was intended.
> Alternatively, "make an entreaty" would describe the type of
> interjection that is to follow.

Thanks.  I agree that "make an intervention" isn't right.  I've gone 

for
"At this point we take a detour from the impersonal tone of the rest 

of

the manual."  Does that sound OK?



"take a detour" implies that there is an obstacle that is preventing
the author from what would otherwise be the desirable route.  I cannot
tell that there is any such obstacle.  But if you want to indicate a
temporary change in the discussion, then "make a digression" or some
form of that phrase could be used.

"Digression" has the same lack of precision that "interjection" has,
namely, that it does not say what kind or type of digression it is or
what the purpose of the digression is.  "Entreaty" or "plea" are more
specific, but might not be quite what is intended.  I do not have a
suggested sentence, other than to say that what the original author
appears to have in mind is to make explicit the change to informal
tone, and then provide some description of the reason for the
following text (originally, to "make an intervention").

Also, this is confusing to me because the section is titled "Extending
the Compiler," which implies (to me) that it will describe how to
extend the compiler, but instead it is a description of areas of the
Guile compiler that need improvement and extending.  It might have
been better titled "Helping Improve and Extend the Compiler."  It
might also be more appropriate to move this section to an appendix
because it does not provide instructions.

--

Re: Typos in the manual

[Neil Jerram]

Mark Harig  writes:

>>
>> > Both "i.e." and "e.g." should always be followed by a comma.
>>
>> Well.  Let me tell you.  I've written those kinds of patches before,
>> adding a comma unconditionally and all.  After a few maintainers of
>> some packages rejected them, I've become less enthused.
>>
>
> Something that's long been a mystery to me is why it is that computer
> programmers, who spend their days learning and following the rules and
> idioms of various programming languages, do not want to learn and
> follow the rules and idioms of natural languages.

Because computer languages are constrained by the specifications and
tools that interpret them, whereas natural languages evolve and diverge
through human usage?

> Reference manuals should strive to follow grammar and usage rules as
> much as possible in a jargon-filled context.  There is enough room
> already for confusion and lack of precision.

But surely you don't believe that there is a One True set of "grammar
and usage rules"?

>> Also, while the Chicago Manual of Style recommends it, some other 
> online
>> grammar sites mention that it is American English style, but British
>> English would not add a comma afterwards.

My feeling is consistent with that.  I'm British, and I'd say there are
lots of cases where it is more natural (to me) not to have a comma after
"i.e." or "e.g.".

> To propose that the comma sometimes be included and sometimes be
> omitted after "i.e." and "e.g." should be considered the same as
> proposing that the comma following the words "that is" and "for
> example" are optional.

I'd say that's a false premise (and hence makes the rest of your post
unfounded).  "i.e." and "e.g." are useful precisely because they are
more concise than "that is" and "for example", and hence they have
different effects on the flow of their containing sentence.  Normally
the effect is that they slow the sentence down _less_ than "that is" or
"for example" would - which IMO is often an advantage.  To require a
comma in every case would be to obscure that difference.

> Example 1:
>
> By "simple" we mean data types that are not primarily used as
> containers to hold other data -- i.e. pairs, lists, vectors and so on.

In case it helps to explain my position here: when I read this sentence
to myself, whether out loud or in my head, there is no pause after the
"i.e.".  To me this is natural, and is good because it allows the
sentence to complete without unnecessary delay.

Is there a pause when you read it to yourself?

Regards,
Neil

Re: Typos in the manual

[Neil Jerram]

Mark Harig  writes:

> Likewise, "make an intervention" implies that the author intends to
> intervene or stop or prevent something.  But the author is not hoping
> to stop compiler junkies from continuing their habit of writing code
> for compilers -- to the contrary.  Given the text that follows this
> phrase, "make an interjection" is probably what was intended.
> Alternatively, "make an entreaty" would describe the type of
> interjection that is to follow.

Thanks.  I agree that "make an intervention" isn't right.  I've gone for
"At this point we take a detour from the impersonal tone of the rest of
the manual."  Does that sound OK?

Neil

Re: Typos in the manual

[Neil Jerram]

Marijn  writes:

> Reading the quoted text I can't help but wonder what a "sublimated
> desire" is. According to wiktionary "sublimated" is the past tense of
> "sublimate" which has 3 meanings[1] none of which I recognize as the
> intended meaning. Perhaps "subliminal desire"[2] is meant, that is, a
> desire that is so faint that it is not discernible by the conscious
> mind, but that usage is said to be reserved for stimuli and one may
> consider it a stretch to include a desire under stimuli. If my analysis
> so far seems correct I tentatively propose "secret desire" or "furtive
> desire" as corrections.

Thanks, I agree.  I'll just delete "sublimated", as I think it reads
well with no adjective there.

 Neil

Re: Typos in the manual

[Mark Harig]

> Both "i.e." and "e.g." should always be followed by a comma.

Well.  Let me tell you.  I've written those kinds of patches before,
adding a comma unconditionally and all.  After a few maintainers of
some packages rejected them, I've become less enthused.



Something that's long been a mystery to me is why it is that computer
programmers, who spend their days learning and following the rules and
idioms of various programming languages, do not want to learn and
follow the rules and idioms of natural languages.

Reference manuals should strive to follow grammar and usage rules as
much as possible in a jargon-filled context.  There is enough room
already for confusion and lack of precision.

Also, while the Chicago Manual of Style recommends it, some other 

online

grammar sites mention that it is American English style, but British
English would not add a comma afterwards.  Yet others do not require 

it

even in American style.



Let's follow the guides that do require it.

To propose that the comma sometimes be included and sometimes be
omitted after "i.e." and "e.g." should be considered the same as
proposing that the comma following the words "that is" and "for
example" are optional.  The comma should not be optional because it
changes the meaning of the sentence, often making it ungrammatical.

Examples from the Guile reference manual:

Example 1:

By "simple" we mean data types that are not primarily used as
containers to hold other data -- i.e. pairs, lists, vectors and so on.

Substituting the words "that is" for "i.e." in two alternatives, which
is correct?

A)
By "simple" we mean data types that are not primarily used as
containers to hold other data -- that is pairs, lists, vectors and
so on.

B)
By "simple," we mean data types that are not primarily used as
containers to hold other data, that is, pairs, lists, vectors,
and so on.

Without the comma between "that is" and "pairs," the reader has a
noun-verb phrase that he needs to disambiguate to figure out the true
meaning.  ("that is pairs?"  "that is pairs" *what*?  What is "pairs"
doing?  Oh, you mean, "that is, pairs, lists, ...")

(Note the added comma before 'and so on' in keeping with the rule that
"etc." should always be preceded by a comma, and "etc." is an (Latin)
abbreviation for "and so on.")

Example 2:

An external representation (i.e. one which can written with `write'
and read with `read') of a random state object can be obtained via
`random-state->datum'.

Which is correct?

A)
An external representation (that is one which can written with
`write' and read with `read') of a random state object can be obtained
via `random-state->datum'.

B)
An external representation (that is, one which can written with
`write' and read with `read') of a random state object can be obtained
via `random-state->datum'.

Again, without the comma after "that is," the parenthetical phrase has
a different meaning than it does with the comma.  With the comma,
the phrase is a supplemental description of what is meant by the term
"external representation."  Without the comma, the phrase is selecting
from the supposedly many types of "external representations."


Cheers,
Ralf (whose first style book is shipping this way right now ... :-)


GNU Guile is lucky to have someone as knowledgeable as yourself
reviewing its manual.

--

Re: Typos in the manual

[Ralf Wildenhues]

Hello Mark,

* Mark Harig wrote on Tue, Feb 15, 2011 at 09:48:24PM CET:
> Both "i.e." and "e.g." should always be followed by a comma.

Well.  Let me tell you.  I've written those kinds of patches before,
adding a comma unconditionally and all.  After a few maintainers of
some packages rejected them, I've become less enthused.

Also, while the Chicago Manual of Style recommends it, some other online
grammar sites mention that it is American English style, but British
English would not add a comma afterwards.  Yet others do not require it
even in American style.

Cheers,
Ralf (whose first style book is shipping this way right now ... :-)

Re: Typos in the manual

[Mark Harig]

> - Some abbreviations are spelt creatively.  The Latin 'id est' is
>   usually abbreviated 'i.e.' without an intervening space, and for 

good
>   spacing you either need a comma right afterwards, or '@:'.  Same 

with

>   'e.g.'.  Find lots of instances with:
> git grep '\<[Ii][. ]*e\.[^,@]'
>
>   My personal preference is to use a comma when what follows is 

long or
>   grammatically a full sentence, and '@:' otherwise.  (info texinfo 

"Not

>   Ending a Sentence").

Agreed.


Both "i.e." and "e.g." should always be followed by a comma.  (The
previous sentence is not self-contradictory because in these
instances, the terms are quoted rather than used.)  I am not able to
think of an example where this rule should not be applied, even though
on the internet it is commonly not followed.  They should always be 
preceded

by a comma when they do not start a sentence, an interjection, or a
parenthetical phrase.  Likewise, "etc." should always be preceded by a
comma unless a sentence is constructed that starts with "etc."

Re: Typos in the manual

[Mark Harig]

>>> --- a/doc/ref/compiler.texi
>>> +++ b/doc/ref/compiler.texi
>>> @@ -855,7 +855,7 @@ for more information about the Brainfuck 

language

itself.
>>>  At this point, we break with the impersonal tone of the rest of 

the
>>>  manual, and make an intervention. Admit it: if you've read this 

far
>>>  into the compiler internals manual, you are a junkie. Perhaps a 

course
>>> -at your university left you unsated, or perhaps you've always 

harbored
>>> +at your university left you unsatisfied, or perhaps you've 

always harbored
>>>  a sublimated desire to hack the holy of computer science holies: 

a
>>>  compiler. Well you're in good company, and in a good position. 

Guile's

>>>  compiler needs your help.
>>
>> "unsated" is fine in English too, and I hesitate to tinker with 

Andy's

>> fine prose.  So I'd prefer to leave this as is.
>
> Yeah, that one can be attributed to my not being a native speaker.
>

Reading the quoted text I can't help but wonder what a "sublimated
desire" is. According to wiktionary "sublimated" is the past tense of
"sublimate" which has 3 meanings[1] none of which I recognize as the
intended meaning. Perhaps "subliminal desire"[2] is meant, that is, a
desire that is so faint that it is not discernible by the conscious
mind, but that usage is said to be reserved for stimuli and one may
consider it a stretch to include a desire under stimuli. If my 

analysis

so far seems correct I tentatively propose "secret desire" or "furtive
desire" as corrections.



Likewise, "make an intervention" implies that the author intends to
intervene or stop or prevent something.  But the author is not hoping
to stop compiler junkies from continuing their habit of writing code
for compilers -- to the contrary.  Given the text that follows this
phrase, "make an interjection" is probably what was intended.
Alternatively, "make an entreaty" would describe the type of
interjection that is to follow.

--

Re: Typos in the manual

[Marijn]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

Hi,

On 02/13/11 08:00, Ralf Wildenhues wrote:
> Hi Neil,
> 
> * Neil Jerram wrote on Sun, Feb 13, 2011 at 01:49:43AM CET:
>> Ralf Wildenhues writes:
>>> --- a/doc/ref/compiler.texi
>>> +++ b/doc/ref/compiler.texi
>>> @@ -855,7 +855,7 @@ for more information about the Brainfuck language 
>>> itself.
>>>  At this point, we break with the impersonal tone of the rest of the
>>>  manual, and make an intervention. Admit it: if you've read this far
>>>  into the compiler internals manual, you are a junkie. Perhaps a course
>>> -at your university left you unsated, or perhaps you've always harbored
>>> +at your university left you unsatisfied, or perhaps you've always harbored
>>>  a sublimated desire to hack the holy of computer science holies: a
>>>  compiler. Well you're in good company, and in a good position. Guile's
>>>  compiler needs your help.
>>
>> "unsated" is fine in English too, and I hesitate to tinker with Andy's
>> fine prose.  So I'd prefer to leave this as is.
> 
> Yeah, that one can be attributed to my not being a native speaker.
> 

Reading the quoted text I can't help but wonder what a "sublimated
desire" is. According to wiktionary "sublimated" is the past tense of
"sublimate" which has 3 meanings[1] none of which I recognize as the
intended meaning. Perhaps "subliminal desire"[2] is meant, that is, a
desire that is so faint that it is not discernible by the conscious
mind, but that usage is said to be reserved for stimuli and one may
consider it a stretch to include a desire under stimuli. If my analysis
so far seems correct I tentatively propose "secret desire" or "furtive
desire" as corrections.

Marijn

[1]: http://en.wiktionary.org/wiki/sublimate
[2]: http://en.wiktionary.org/wiki/subliminal
-BEGIN PGP SIGNATURE-
Version: GnuPG v2.0.17 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk1aoEIACgkQp/VmCx0OL2ytqgCgwAZ9tGhFeHzkW5uUC4bk09B4
CgwAn2EeWhtQGzM95cXB8JRaMweByBHF
=ca+s
-END PGP SIGNATURE-

Re: Typos in the manual

[Neil Jerram]

Ralf Wildenhues  writes:

> Hi Neil,

Hi Ralf,

I pushed some more changes based on your input.  Below has just a few
specific notes.

> * Neil Jerram wrote on Sun, Feb 13, 2011 at 01:49:43AM CET:
>> 
>> Will @var always generate appropriate markup for making it clear that
>> GUILE_EFFECTIVE_VERSION isn't meant literally?  I think that is what the
>> < and > intend to indicate.
>
> Well, @var is the intended way to denote metasyntactic variables.
> In info output, it capitalizes, in PDF output it uses a different font
> (or small caps IIRC).  See 'info texinfo var'.  It might sometimes be
> a bit hard to always read them correctly in info output.  I'm not sure
> how info could be improved though.

Yes, I'm convinced now and so have applied this.

>> Why is \sqrt2 better than \sqrt{2} ?
>
> No idea, that was pure consistency at work: you already use \sqrt2
> elsewhere.  Doesn't matter really.

I went for \sqrt{2} everywhere - I think that avoids anyone (who doesn't
immediately know the fine detail of TeX's lexer) wondering whether \sqrt2
might be a special TeX token.

>> > - In the Autoconf section, several macros are added to the function
>> >   index.  They come from doc/ref/autoconf{,-macros}.texi (one being
>> >   generated from meta/guile.m4.  The macros are:
>> > PKG_CHECK_MODULES
>> > GUILE_PROGS
>> > GUILE_FLAGS
>> > GUILE_SITE_DIR
>> > GUILE_CHECK_RETVAL
>> > GUILE_MODULE_CHECK
>> > GUILE_MODULE_AVAILABLE
>> > GUILE_MODULE_REQUIRED
>> > GUILE_MODULE_EXPORTS
>> > GUILE_MODULE_REQUIRED_EXPORT
>> >
>> >   The simplest way to fix this
>> 
>> Fix what?
>> 
>> > would be to adjust indices.texi to
>> >   document that Autoconf macros and variables are also listed in this
>> >   index.  Karl tells me that one should have less indices anyway for the
>> >   autotools manuals (ideally just one), so this would seem like a step
>> >   in the right direction.
>> 
>> Sorry, I'm not following here at all.
>
> Well.  If you look at the Procedure Index of the manual, you will find
> entries for the above Autoconf macros in there.  The Procedure Index has
> the following intro text:
>
>   This is an alphabetical list of all the procedures and macros in Guile.
>
>  When looking for a particular procedure, please look under its Scheme
>   name as well as under its C name.  The C name can be constructed from
>   the Scheme names by a simple transformation described in the section
>   *Note API Overview::.
>
> In other words, no mention of "Autoconf macros", and I wouldn't expect
> to find them there, among all the Scheme and C symbols.  Now, you can
> either fix the text to match the contents, or change the extractor to
> not emit @deffn's for the Autoconf macro in doc/ref/autoconf-macros.texi
> so that they don't end being listed in the Procedure Index.
>
> Is that clearer now?

Yes, thanks; done as you and Karl recommend.

  Neil

Re: Typos in the manual

[Ralf Wildenhues]

Hi Neil,

* Neil Jerram wrote on Sun, Feb 13, 2011 at 01:49:43AM CET:
> Ralf Wildenhues writes:
> > I found a few typos in the manual, actually, comparatively very few for
> > the size of the manual!  The attached patches should fix them.  Please
> > be scrupulous, I'm not firm in Guile language details nor habits.
> 
> I applied all these except for the following that I wasn't sure about.

Thank you!

Not quoting stuff I completely agree with:

> > --- a/doc/ref/api-options.texi
> > +++ b/doc/ref/api-options.texi
> > @@ -82,10 +82,11 @@ general are stored.  On Unix-like systems, this is 
> > usually
> >  Return the name of the directory where the Guile Scheme files that
> >  belong to the core Guile installation (as opposed to files from a 3rd
> >  party package) are installed.  On Unix-like systems this is usually
> > -@file{/usr/local/share/guile/} or
> > -@file{/usr/share/guile/};
> > +@file{/usr/local/share/guile/@var{GUILE_EFFECTIVE_VERSION}} or
> > +@file{/usr/share/guile/@var{GUILE_EFFECTIVE_VERSION}};
> >  
> > -@noindent for example @file{/usr/local/share/guile/1.6}.
> > +@noindent
> > +for example @file{/usr/local/share/guile/1.6}.
> >  @end deffn
> >  
> >  @deffn {Scheme Procedure} %site-dir
> 
> Will @var always generate appropriate markup for making it clear that
> GUILE_EFFECTIVE_VERSION isn't meant literally?  I think that is what the
> < and > intend to indicate.

Well, @var is the intended way to denote metasyntactic variables.
In info output, it capitalizes, in PDF output it uses a different font
(or small caps IIRC).  See 'info texinfo var'.  It might sometimes be
a bit hard to always read them correctly in info output.  I'm not sure
how info could be improved though.

If you choose to drop this hunk (which is fine of course), please still
add a newline after the @noindent.

> > --- a/doc/ref/api-compound.texi
> > +++ b/doc/ref/api-compound.texi
> > @@ -1820,7 +1820,7 @@ have smaller rank than @var{array}.
> >  @subsubsection Accessing Arrays from C
> >  
> >  Arrays, especially uniform numeric arrays, are useful to efficiently
> > -represent large amounts of rectangularily organized information, such as
> > +represent large amounts of information organized in a rectangular way, 
> > such as
> >  matrices, images, or generally blobs of binary data.  It is desirable to
> >  access these blobs in a C like manner so that they can be handed to
> >  external C code such as linear algebra libraries or image processing
> 
> I'm afraid "organized in a rectangular way" is just as opaque to me as
> "rectangularily organized", so this isn't a clear improvement.
> 
> I think readers will already know what array data is, so perhaps we can
> just delete that first sentence, and refactor the rest of the para to:
> 
> "
> For interworking with external C code, Guile provides an API to allow C
> code to access the elements of a Scheme array.  In particular, for
> uniform numeric arrays, the API exposes the underlying uniform data as a
> C array of numbers of the relevant type.
> "

Sounds better to me, thanks.

> > --- a/doc/ref/api-data.texi
> > +++ b/doc/ref/api-data.texi
> > @@ -225,8 +225,8 @@ rational is also real, and every real number is also a 
> > complex number
> >  In addition to the classification into integers, rationals, reals and
> >  complex numbers, Scheme also distinguishes between whether a number is
> >  represented exactly or not.  For example, the result of
> > -@m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)}, but Guile
> > -can represent neither @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
> > +@m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt2,2^(1/2)}, but Guile
> > +can represent neither @m{\pi/4,pi/4} nor @m{\sqrt2,2^(1/2)} exactly.
> >  Instead, it stores an inexact approximation, using the C type
> >  @code{double}.
> 
> Why is \sqrt2 better than \sqrt{2} ?

No idea, that was pure consistency at work: you already use \sqrt2
elsewhere.  Doesn't matter really.

> > @@ -4550,7 +4550,7 @@ representing the contents of @var{bv}, decoded 
> > according to
> >  @deffnx {Scheme Procedure} sint-list->bytevector lst endianness size
> >  @deffnx {C Function} scm_uint_list_to_bytevector (lst, endianness, size)
> >  @deffnx {C Function} scm_sint_list_to_bytevector (lst, endianness, size)
> > -Return a new bytevector containing the unsigned (resp. signed) integers
> > +Return a new bytevector containing the unsigned (resp.@: signed) integers
> >  listed in @var{lst} and encoded on @var{size} bytes accordin

Re: Typos in the manual

[Neil Jerram]

Ralf Wildenhues  writes:

> Hello Guile developers,
>
> I found a few typos in the manual, actually, comparatively very few for
> the size of the manual!  The attached patches should fix them.  Please
> be scrupulous, I'm not firm in Guile language details nor habits.

I applied all these except for the following that I wasn't sure about.

> diff --git a/doc/ref/api-options.texi b/doc/ref/api-options.texi
> index 7121784..57ba02e 100644
> --- a/doc/ref/api-options.texi
> +++ b/doc/ref/api-options.texi
> @@ -82,10 +82,11 @@ general are stored.  On Unix-like systems, this is usually
>  Return the name of the directory where the Guile Scheme files that
>  belong to the core Guile installation (as opposed to files from a 3rd
>  party package) are installed.  On Unix-like systems this is usually
> -@file{/usr/local/share/guile/} or
> -@file{/usr/share/guile/};
> +@file{/usr/local/share/guile/@var{GUILE_EFFECTIVE_VERSION}} or
> +@file{/usr/share/guile/@var{GUILE_EFFECTIVE_VERSION}};
>  
> -@noindent for example @file{/usr/local/share/guile/1.6}.
> +@noindent
> +for example @file{/usr/local/share/guile/1.6}.
>  @end deffn
>  
>  @deffn {Scheme Procedure} %site-dir

Will @var always generate appropriate markup for making it clear that
GUILE_EFFECTIVE_VERSION isn't meant literally?  I think that is what the
< and > intend to indicate.

> diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
> index 2284b0d..e108da8 100644
> --- a/doc/ref/api-compound.texi
> +++ b/doc/ref/api-compound.texi
> @@ -1820,7 +1820,7 @@ have smaller rank than @var{array}.
>  @subsubsection Accessing Arrays from C
>  
>  Arrays, especially uniform numeric arrays, are useful to efficiently
> -represent large amounts of rectangularily organized information, such as
> +represent large amounts of information organized in a rectangular way, such 
> as
>  matrices, images, or generally blobs of binary data.  It is desirable to
>  access these blobs in a C like manner so that they can be handed to
>  external C code such as linear algebra libraries or image processing

I'm afraid "organized in a rectangular way" is just as opaque to me as
"rectangularily organized", so this isn't a clear improvement.

I think readers will already know what array data is, so perhaps we can
just delete that first sentence, and refactor the rest of the para to:

"
For interworking with external C code, Guile provides an API to allow C
code to access the elements of a Scheme array.  In particular, for
uniform numeric arrays, the API exposes the underlying uniform data as a
C array of numbers of the relevant type.
"

Any other suggestions?

> diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
> index fd2e7ee..59b6405 100644
> --- a/doc/ref/api-data.texi
> +++ b/doc/ref/api-data.texi
> @@ -225,8 +225,8 @@ rational is also real, and every real number is also a 
> complex number
>  In addition to the classification into integers, rationals, reals and
>  complex numbers, Scheme also distinguishes between whether a number is
>  represented exactly or not.  For example, the result of
> -@m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)}, but Guile
> -can represent neither @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
> +@m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt2,2^(1/2)}, but Guile
> +can represent neither @m{\pi/4,pi/4} nor @m{\sqrt2,2^(1/2)} exactly.
>  Instead, it stores an inexact approximation, using the C type
>  @code{double}.

Why is \sqrt2 better than \sqrt{2} ?

> @@ -572,7 +572,7 @@ is an integer number or a rational number.
>  @deffnx {C Function} scm_rational_p (x)
>  Return @code{#t} if @var{x} is a rational number, @code{#f} otherwise.
>  Note that the set of integer values forms a subset of the set of
> -rational numbers, i. e. the predicate will also be fulfilled if
> +rational numbers, i.e.@: the predicate will also be fulfilled if
>  @var{x} is an integer number.
>  @end deffn

Having read through your comments below, I understand this one, and will
apply it.

> @@ -4550,7 +4550,7 @@ representing the contents of @var{bv}, decoded 
> according to
>  @deffnx {Scheme Procedure} sint-list->bytevector lst endianness size
>  @deffnx {C Function} scm_uint_list_to_bytevector (lst, endianness, size)
>  @deffnx {C Function} scm_sint_list_to_bytevector (lst, endianness, size)
> -Return a new bytevector containing the unsigned (resp. signed) integers
> +Return a new bytevector containing the unsigned (resp.@: signed) integers
>  listed in @var{lst} and encoded on @var{size} bytes according to
>  @var{endianness}.
>  @end deffn

I don't think "resp." is reliably understood.  I propose instead to
separate each of the current 3 uses of "