* Typos in the manual
@ 2011-02-08 20:25 Ralf Wildenhues
2011-02-13 0:49 ` Neil Jerram
0 siblings, 1 reply; 29+ messages in thread
From: Ralf Wildenhues @ 2011-02-08 20:25 UTC (permalink / raw)
To: bug-guile
[-- Attachment #1: Type: text/plain, Size: 3311 bytes --]
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.
Note the first one may be mangled by email transport, which is why I
gziped it; it removes a non-ASCII character from the text. It should be
possible to skip it if needed and use 'git am -3' on the rest.
There are a few things that I spotted that I didn't fix, either because
I didn't know which was the right way, or in cases that I've come to
know as contentious among developers. It would be nice if you could go
over them and address them in one way or another. Given consensus, I
might be prodded into patching some, but don't count on me.
- Word pairs you might want to review and/or maybe just use one set of:
queuing vs. queueing,
destructur.* vs. destruct.* vs. deconstr.*
(unless they have different meanings of course),
uninterned vs. non-internal,
latin1 vs. latin-1,
parsable vs. parseable.
- 'postpend': I'd replace this with 'append' throughout the tree
(not just the manual).
- 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").
- The Guile manual seems quite eager in making up new words. This is to
some extent a tendency that just comes with hacking, and has both
distinguished and entertaining aspects. At the same time however, it
can make things less accessible for new users, especially those with a
foreign native language, who then have troubles looking such words up
in some dictionary. It starts with very simple things like 'dir' and
'arg' which I assume nobody has a serious problem with, yet which I
would always write as 'directory' and 'argument' in prose
(cf. 'info standards "GNU Manuals"'; but this goes beyond that text).
OTOH, things like 'unpermanent', 'cdring', and 'consing' are not easy
to understand IMVHO.
- 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 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.
- I love France and the Franc, but there will soon be kids that don't
remember it, for which 'french currency string' will be a foreign
concept. It might be a good idea to update the example eventually.
Thanks for maintaining Guile,
Ralf
[-- Attachment #2: 0001-docs-remove-non-ASCII-space-from-docs.patch.gz --]
[-- Type: application/x-gunzip, Size: 688 bytes --]
[-- Attachment #3: 0002-docs-fix-typos-in-manual-and-a-couple-in-code-commen.patch --]
[-- Type: text/plain, Size: 41911 bytes --]
From a68a49404cdbc4be46d764374f79dfb8b6d93aaf Mon Sep 17 00:00:00 2001
From: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
Date: Tue, 8 Feb 2011 21:20:57 +0100
Subject: [PATCH 2/5] docs: fix typos in manual, and a couple in code comments.
* doc/ref/api-binding.texi, doc/ref/api-compound.texi,
doc/ref/api-control.texi, doc/ref/api-debug.texi,
doc/ref/api-io.texi, doc/ref/api-macros.texi,
doc/ref/api-procedures.texi, doc/ref/api-scheduling.texi,
doc/ref/api-undocumented.texi, doc/ref/api-utility.texi,
doc/ref/compiler.texi, doc/ref/goops.texi,
doc/ref/libguile-concepts.texi, doc/ref/misc-modules.texi,
doc/ref/posix.texi, doc/ref/r6rs.texi, doc/ref/slib.texi,
doc/ref/srfi-modules.texi, doc/ref/sxml-match.texi,
doc/ref/tools.texi, doc/ref/vm.texi, doc/ref/web.texi,
doc/sources/env.texi, doc/sources/jimb-org.texi,
doc/sources/scheme-concepts.texi, doc/sources/unix.texi,
module/ice-9/optargs.scm: Fix typos.
* doc/r4rs/r5rs.texi: Likewise. Do not capitalize code symbols
even at the start of a sentence.
* doc/ref/api-data.texi: Likewise. Also, remove executable bit.
---
doc/r5rs/r5rs.texi | 6 +++---
doc/ref/api-binding.texi | 2 +-
doc/ref/api-compound.texi | 8 ++++----
doc/ref/api-control.texi | 4 ++--
doc/ref/api-data.texi | 26 +++++++++++++-------------
doc/ref/api-debug.texi | 2 +-
doc/ref/api-io.texi | 4 ++--
doc/ref/api-macros.texi | 8 ++++----
doc/ref/api-procedures.texi | 2 +-
doc/ref/api-scheduling.texi | 2 +-
doc/ref/api-undocumented.texi | 6 +++---
doc/ref/api-utility.texi | 2 +-
doc/ref/compiler.texi | 8 ++++----
doc/ref/goops.texi | 4 ++--
doc/ref/libguile-concepts.texi | 2 +-
doc/ref/misc-modules.texi | 6 +++---
doc/ref/posix.texi | 2 +-
doc/ref/r6rs.texi | 10 +++++-----
doc/ref/slib.texi | 2 +-
doc/ref/srfi-modules.texi | 16 ++++++++--------
doc/ref/sxml-match.texi | 2 +-
doc/ref/tools.texi | 2 +-
doc/ref/vm.texi | 10 +++++-----
doc/ref/web.texi | 4 ++--
doc/sources/env.texi | 6 +++---
doc/sources/jimb-org.texi | 2 +-
doc/sources/scheme-concepts.texi | 2 +-
doc/sources/unix.texi | 4 ++--
module/ice-9/optargs.scm | 2 +-
29 files changed, 78 insertions(+), 78 deletions(-)
mode change 100755 => 100644 doc/ref/api-data.texi
diff --git a/doc/r5rs/r5rs.texi b/doc/r5rs/r5rs.texi
index 605a976..1c3df60 100644
--- a/doc/r5rs/r5rs.texi
+++ b/doc/r5rs/r5rs.texi
@@ -4429,9 +4429,9 @@ all.
These procedures are part of every implementation that supports
@c %R4%%
general
-real numbers; they compute the usual transcendental functions. @samp{Log}
+real numbers; they compute the usual transcendental functions. @samp{log}
computes the natural logarithm of @var{z} (not the base ten logarithm).
-@samp{Asin}, @samp{acos}, and @samp{atan} compute arcsine (sin^-1),
+@samp{asin}, @samp{acos}, and @samp{atan} compute arcsine (sin^-1),
arccosine (cos^-1), and arctangent (tan^-1), respectively.
The two-argument variant of @samp{atan} computes @t{(angle
(make-rectangular @var{x} @var{y}))} (see below), even in implementations
@@ -5988,7 +5988,7 @@ unspecified value.
-Vectors are heterogenous structures whose elements are indexed
+Vectors are heterogeneous structures whose elements are indexed
by integers. A vector typically occupies less space than a list
of the same length, and the average time required to access a randomly
chosen element is typically less for the vector than for the list.
diff --git a/doc/ref/api-binding.texi b/doc/ref/api-binding.texi
index 60af456..a954f4d 100644
--- a/doc/ref/api-binding.texi
+++ b/doc/ref/api-binding.texi
@@ -142,7 +142,7 @@ The @var{init} expressions are not allowed to refer to any of the
@var{variables}.
@end deffn
-The other binding contructs are variations on the same theme: making new
+The other binding constructs are variations on the same theme: making new
values, binding them to variables, and executing a body in that new,
extended lexical context.
diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index f5e8c97..e108da8 100644
--- a/doc/ref/api-compound.texi
+++ b/doc/ref/api-compound.texi
@@ -909,7 +909,7 @@ Sets the element at position @var{idx} in the simple vector
Acquire a handle for the vector @var{vec} and return a pointer to the
elements of it. This pointer can only be used to read the elements of
@var{vec}. When @var{vec} is not a vector, an error is signaled. The
-handle mustr eventually be released with
+handle must eventually be released with
@code{scm_array_handle_release}.
The variables pointed to by @var{lenp} and @var{incp} are filled with
@@ -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
@@ -2377,7 +2377,7 @@ to be stored along side usual Scheme @code{SCM} values.
A vtable is a structure type, specifying its layout, and other
information. A vtable is actually itself a structure, but there's no
-need to worray about that initially (@pxref{Vtable Contents}.)
+need to worry about that initially (@pxref{Vtable Contents}.)
@deffn {Scheme Procedure} make-vtable fields [print]
Create a new vtable.
@@ -2786,7 +2786,7 @@ of tools for using either association lists or hash tables.
@tpindex Alist
@cindex association List
@cindex alist
-@cindex aatabase
+@cindex database
An association list is a conventional data structure that is often used
to implement simple key-value databases. It consists of a list of
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index 2375a64..7a5fb1e 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -148,7 +148,7 @@ and the last @var{clause} may have the form
@end lisp
All @var{datum}s must be distinct. First, @var{key} is evaluated. The
-the result of this evaluation is compared against all @var{datum}s using
+result of this evaluation is compared against all @var{datum} values using
@code{eqv?}. When this comparison succeeds, the expression(s) following
the @var{datum} are evaluated from left to right, returning the value of
the last expression as the result of the @code{case} expression.
@@ -1303,7 +1303,7 @@ frees the memory. But once the memory is freed, we can not get it
back on reentry. Thus reentry can not be allowed.
The consequence is that continuations become less useful when
-non-reenterable contexts are captured, but you don't need to worry
+non-reentrant contexts are captured, but you don't need to worry
about that too much.
The context is ended either implicitly when a non-local exit happens,
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
old mode 100755
new mode 100644
index 9b065a5..8c50941
--- 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}.
@@ -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
@@ -1155,7 +1155,7 @@ Returns the magnitude or angle of @var{z} as a @code{double}.
The C arithmetic functions below always takes two arguments, while the
Scheme functions can take an arbitrary number. When you need to
invoke them with just one argument, for example to compute the
-equivalent od @code{(- x)}, pass @code{SCM_UNDEFINED} as the second
+equivalent of @code{(- x)}, pass @code{SCM_UNDEFINED} as the second
one: @code{scm_difference (x, SCM_UNDEFINED)}.
@c begin (texi-doc-string "guile" "+")
@@ -1327,7 +1327,7 @@ including complex numbers.
@c begin (texi-doc-string "guile" "sqrt")
@deffn {Scheme Procedure} sqrt z
Return the square root of @var{z}. Of the two possible roots
-(positive and negative), the one with the a positive real part is
+(positive and negative), the one with the positive real part is
returned, or if that's zero then a positive imaginary part. Thus,
@example
@@ -2989,7 +2989,7 @@ Convert the string @var{str} into a list of characters.
@deffn {Scheme Procedure} string-split str chr
@deffnx {C Function} scm_string_split (str, chr)
-Split the string @var{str} into the a list of the substrings delimited
+Split the string @var{str} into the list of the substrings delimited
by appearances of the character @var{chr}. Note that an empty substring
between separator characters will result in an empty string in the
result list.
@@ -3422,12 +3422,12 @@ case-insensitively.
@deffn {Scheme Procedure} string-hash s [bound [start [end]]]
@deffnx {C Function} scm_substring_hash (s, bound, start, end)
-Compute a hash value for @var{S}. the optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound).
+Compute a hash value for @var{S}. The optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound).
@end deffn
@deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]]
@deffnx {C Function} scm_substring_hash_ci (s, bound, start, end)
-Compute a hash value for @var{S}. the optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound).
+Compute a hash value for @var{S}. The optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound).
@end deffn
Because the same visual appearance of an abstract Unicode character can
@@ -3449,7 +3449,7 @@ Unicode Standard; and composition, which performs the converse.
There are two decomposition operations. ``Canonical decomposition''
produces character sequences that share the same visual appearance as
-the original characters, while ``compatiblity decomposition'' produces
+the original characters, while ``compatibility decomposition'' produces
ones whose visual appearances may differ from the originals but which
represent the same abstract character.
@@ -4069,7 +4069,7 @@ If a character in @var{str} cannot be represented in the locale encoding
of the current output port, the port conversion strategy of the current
output port will determine the result, @xref{Ports}. If output port's
conversion strategy is @code{error}, an error will be raised. If it is
-@code{subsitute}, a replacement character, such as a question mark, will
+@code{substitute}, a replacement character, such as a question mark, will
be inserted in its place. If it is @code{escape}, a hex escape will be
inserted in its place.
@end deftypefn
@@ -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
@@ -5128,8 +5128,8 @@ Guile currently retains some elements of the traditional structure in
case they turn out to be useful when implementing translators for other
languages, in particular Emacs Lisp.
-Specifically, Guile symbols have two extra slots. for a symbol's
-property list, and for its ``function value.'' The following procedures
+Specifically, Guile symbols have two extra slots, one for a symbol's
+property list, and one for its ``function value.'' The following procedures
are provided to access these slots.
@deffn {Scheme Procedure} symbol-fref symbol
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index 7efbb75..765b4ad 100644
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -1030,7 +1030,7 @@ of an application of @var{proc}.
@deffn {Scheme Procedure} trap-instructions-in-dynamic-extent proc @
next-handler [#:current-frame] [#:vm] [#:closure?]
-A trap that calls @var{next-handler} for all retired intructions within
+A trap that calls @var{next-handler} for all retired instructions within
the dynamic extent of a call to @var{proc}.
@end deffn
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index e02daeb..52dfdd4 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -871,7 +871,7 @@ requested, @code{open-file} throws an exception.
When the file is opened, this procedure will scan for a coding
declaration (@pxref{Character Encoding of Source Files}). If present
will use that encoding for interpreting the file. Otherwise, the
-port's encoding will be used. To supress this behavior, open
+port's encoding will be used. To suppress this behavior, open
the file in binary mode and then set the port encoding explicitly
using @code{set-port-encoding!}.
@@ -976,7 +976,7 @@ Determine whether @var{obj} is a port that is related to a file.
@cindex String port
@cindex Port, string
-The following allow string ports to be opened by analogy to R4R*
+The following allow string ports to be opened by analogy to R4RS
file port facilities:
With string ports, the port-encoding is treated differently than other
diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index 5f15fb7..f0eeb6e 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -299,7 +299,7 @@ expression.
This property is sometimes known as @dfn{hygiene}, and it does aid in code
cleanliness. In your macro definitions, you can feel free to introduce temporary
-variables, without worrying about inadvertantly introducing bindings into the
+variables, without worrying about inadvertently introducing bindings into the
macro expansion.
Consider the definition of @code{my-or} from the previous section:
@@ -461,7 +461,7 @@ found @var{exp} referenced outside a @code{syntax} form.
Since @code{syntax} appears frequently in macro-heavy code, it has a special
reader macro: @code{#'}. @code{#'foo} is transformed by the reader into
-@code{(syntax foo)}, just as @code{'foo} is tranformed into @code{(quote foo)}.
+@code{(syntax foo)}, just as @code{'foo} is transformed into @code{(quote foo)}.
The pattern language used by @code{syntax-case} is conveniently the same
language used by @code{syntax-rules}. Given this, Guile actually defines
@@ -763,7 +763,7 @@ macro. @code{syntax-rules} provides some syntax to effect this transformation
more easily.
@deffn {Syntax} identifier-syntax exp
-Returns a macro transformer that will replace occurences of the macro with
+Returns a macro transformer that will replace occurrences of the macro with
@var{exp}.
@end deffn
@@ -814,7 +814,7 @@ bar-alias @result{} 30
@end example
@end deffn
-There is an extension to identifer-syntax which allows it to handle the
+There is an extension to identifier-syntax which allows it to handle the
@code{set!} case as well:
@deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2)
diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi
index c087f4c..02889c4 100644
--- a/doc/ref/api-procedures.texi
+++ b/doc/ref/api-procedures.texi
@@ -489,7 +489,7 @@ take @code{lambda*}-style extended parameter lists, where @code{#:optional},
semantics. Here is an example of a macro with an optional argument:
@lisp
-(defmacro* transmorgify (a #:optional b)
+(defmacro* transmogrify (a #:optional b)
(a 1))
@end lisp
@end deffn
diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi
index 248d8b7..f7ba508 100644
--- a/doc/ref/api-scheduling.texi
+++ b/doc/ref/api-scheduling.texi
@@ -743,7 +743,7 @@ Set @var{fluids} to @var{values} temporary, and call @var{thunk}.
@var{fluids} must be a list of fluids and @var{values} must be the
same number of their values to be applied. Each substitution is done
in the order given. @var{thunk} must be a procedure with no argument.
-it is called inside a @code{dynamic-wind} and the fluids are
+It is called inside a @code{dynamic-wind} and the fluids are
set/restored when control enter or leaves the established dynamic
extent.
@end deffn
diff --git a/doc/ref/api-undocumented.texi b/doc/ref/api-undocumented.texi
index 774061d..1e36ad8 100644
--- a/doc/ref/api-undocumented.texi
+++ b/doc/ref/api-undocumented.texi
@@ -568,7 +568,7 @@ as @var{array}, if used as the @var{prototype} for
@deffn {Scheme Procedure} call-with-dynamic-root thunk handler
@deffnx {C Function} scm_call_with_dynamic_root (thunk, handler)
-Call @var{thunk} with a new dynamic state and withina continuation barrier. The @var{handler} catches allotherwise uncaught throws and executes within the samedynamic context as @var{thunk}.
+Call @var{thunk} with a new dynamic state and within a continuation barrier. The @var{handler} catches all otherwise uncaught throws and executes within the same dynamic context as @var{thunk}.
@end deffn
@deffn {Scheme Procedure} dynamic-root
@@ -587,13 +587,13 @@ Return @code{#t} if @var{obj} is a uniform vector.
@deffn {Scheme Procedure} uniform-vector-ref v idx
@deffnx {C Function} scm_uniform_vector_ref (v, idx)
Return the element at index @var{idx} of the
-homogenous numeric vector @var{v}.
+homogeneous numeric vector @var{v}.
@end deffn
@deffn {Scheme Procedure} uniform-vector-set! v idx val
@deffnx {C Function} scm_uniform_vector_set_x (v, idx, val)
Set the element at index @var{idx} of the
-homogenous numeric vector @var{v} to @var{val}.
+homogeneous numeric vector @var{v} to @var{val}.
@end deffn
@deffn {Scheme Procedure} uniform-vector->list uvec
diff --git a/doc/ref/api-utility.texi b/doc/ref/api-utility.texi
index 8fdfb22..fb747ee 100644
--- a/doc/ref/api-utility.texi
+++ b/doc/ref/api-utility.texi
@@ -432,7 +432,7 @@ copies any pairs in the cars of the input lists.
@deffn {Scheme Procedure} copy-tree obj
@deffnx {C Function} scm_copy_tree (obj)
-Recursively copy the data tree that is bound to @var{obj}, and return a
+Recursively copy the data tree that is bound to @var{obj}, and return
the new data structure. @code{copy-tree} recurses down the
contents of both pairs and vectors (since both cons cells and vector
cells may point to arbitrary objects), and stops recursing when it hits
diff --git a/doc/ref/compiler.texi b/doc/ref/compiler.texi
index b3a1dc6..3c35cc8 100644
--- a/doc/ref/compiler.texi
+++ b/doc/ref/compiler.texi
@@ -295,7 +295,7 @@ Properties}, for more information.
Although Tree-IL objects are represented internally using records,
there is also an equivalent S-expression external representation for
-each kind of Tree-IL. For example, an the S-expression representation
+each kind of Tree-IL. For example, the S-expression representation
of @code{#<const src: #f exp: 3>} expression would be:
@example
@@ -418,7 +418,7 @@ argument, or @code{#f}.
(@var{keyword} @var{name} @var{var}) ...)}, where @var{keyword} is the
keyword corresponding to the argument named @var{name}, and whose
corresponding gensym is @var{var}. @var{inits} are tree-il expressions
-corresponding to all of the optional and keyword argumens, evaluated
+corresponding to all of the optional and keyword arguments, evaluated
to bind variables whose value is not supplied by the procedure caller.
Each @var{init} expression is evaluated in the lexical context of
previously bound variables, from left to right.
@@ -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.
@@ -877,7 +877,7 @@ next step.
The compiler also needs help at the top end, enhancing the Scheme that
it knows to also understand R6RS, and adding new high-level compilers.
We have JavaScript and Emacs Lisp mostly complete, but they could use
-some love; Lua would be nice as well, butq whatever language it is
+some love; Lua would be nice as well, but whatever language it is
that strikes your fancy would be welcome too.
Compilers are for hacking, not for admiring or for complaining about.
diff --git a/doc/ref/goops.texi b/doc/ref/goops.texi
index 0dd7b0e..381dfe9 100644
--- a/doc/ref/goops.texi
+++ b/doc/ref/goops.texi
@@ -535,7 +535,7 @@ other. A better solution is to use virtual slots, like this:
@end lisp
-In this class definition, the magniture @code{m} and angle @code{a}
+In this class definition, the magnitude @code{m} and angle @code{a}
slots are virtual, and are calculated, when referenced, from the normal
(i.e. @code{#:allocation #:instance}) slots @code{r} and @code{i}, by
calling the function defined in the relevant @code{#:slot-ref} option.
@@ -619,7 +619,7 @@ different sets of specializing argument classes; for example:
@lisp
(define-method (+ (x <string>) (y <string)) ...)
(define-method (+ (x <matrix>) (y <matrix>)) ...)
-(define-method (+ (f <fish>) (b <bicyle>)) ...)
+(define-method (+ (f <fish>) (b <bicycle>)) ...)
(define-method (+ (a <foo>) (b <bar>) (c <baz>)) ...)
@end lisp
diff --git a/doc/ref/libguile-concepts.texi b/doc/ref/libguile-concepts.texi
index 1e4cb1e..6ebeb63 100644
--- a/doc/ref/libguile-concepts.texi
+++ b/doc/ref/libguile-concepts.texi
@@ -515,7 +515,7 @@ modified in another thread while the loop iterates over it. Thus, while
copying its elements into the vector, the list might get longer or
shorter. For this reason, the loop must check both that it doesn't
overrun the vector (@code{SCM_SIMPLE_VECTOR_SET} does no range-checking)
-and that it doesn't overrung the list (@code{SCM_CAR} and @code{SCM_CDR}
+and that it doesn't overrun the list (@code{SCM_CAR} and @code{SCM_CDR}
likewise do no type checking).
It is safe to use @code{SCM_CAR} and @code{SCM_CDR} on the local
diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi
index 7071dad..fc35ff8 100644
--- a/doc/ref/misc-modules.texi
+++ b/doc/ref/misc-modules.texi
@@ -91,11 +91,11 @@ dots.}, or in the worst case, displayed as @nicode{#}.
@deffn {Scheme Procedure} truncated-print obj [port] [keyword-options]
Print @var{obj}, truncating the output, if necessary, to make it fit
into @var{width} characters. By default, @var{x} will be printed using
-@code{write}, though that behavior can be overriden via the
+@code{write}, though that behavior can be overridden via the
@var{display?} keyword argument.
The default behaviour is to print depth-first, meaning that the entire
-remaining width will be available to each sub-expressoin of @var{x} --
+remaining width will be available to each sub-expression of @var{x} --
e.g., if @var{x} is a vector, each member of @var{x}. One can attempt to
``ration'' the available width, trying to allocate it equally to each
sub-expression, via the @var{breadth-first?} keyword argument.
@@ -1260,7 +1260,7 @@ The return value from @code{nftw} is @code{#t} if it ran to
completion, or otherwise the non-@code{#t} value from @var{proc} which
caused the stop.
-@c For reference, one reason not to esacpe is that the current
+@c For reference, one reason not to escape is that the current
@c directory is not saved and restored with dynamic-wind. Maybe
@c changing that would be enough to allow escaping.
@c
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
index 4c43248..704fe63 100644
--- a/doc/ref/posix.texi
+++ b/doc/ref/posix.texi
@@ -2456,7 +2456,7 @@ When given, @var{hint_family} should specify the requested
address family, e.g., @code{AF_INET6}. Similarly,
@var{hint_socktype} should specify the requested socket type
(e.g., @code{SOCK_DGRAM}), and @var{hint_protocol} should
-specify the requested protocol (its value is interpretered
+specify the requested protocol (its value is interpreted
as in calls to @code{socket}).
On error, an exception with key @code{getaddrinfo-error} is
diff --git a/doc/ref/r6rs.texi b/doc/ref/r6rs.texi
index ffd238d..4df05e0 100644
--- a/doc/ref/r6rs.texi
+++ b/doc/ref/r6rs.texi
@@ -1125,7 +1125,7 @@ called on exceptions thrown by the corresponding @code{raise} procedure.
@deffn {Scheme Procedure} with-exception-handler handler thunk
Installs @var{handler}, which must be a procedure taking one argument,
-as the current exception handler during the invokation of @var{thunk}, a
+as the current exception handler during the invocation of @var{thunk}, a
procedure taking zero arguments. The handler in place at the time
@code{with-exception-handler} is called is made current again once
either @var{thunk} returns or @var{handler} is invoked after an
@@ -1290,7 +1290,7 @@ condition in a compound condition.
@deffn {Condition Type} &who
@deffnx {Scheme Procedure} make-who-condition who
@deffnx {Scheme Procedure} who-condition? obj
-@deffnx {Scheme Procedure} condiction-who condition
+@deffnx {Scheme Procedure} condition-who condition
A base type used for storing the identity, a string or symbol, of the
entity responsible for another condition in a compound condition.
@end deffn
@@ -1544,7 +1544,7 @@ value, and the maximum fixnum value.
@deffnx {Scheme Procedure} fx<=? fx1 fx2 fx3 ...
These procedures return @code{#t} if their fixnum arguments are
(respectively): equal, monotonically increasing, monotonically
-decreasing, monotonically nondecreasing, or monotonically nonincrasing;
+decreasing, monotonically nondecreasing, or monotonically nonincreasing;
@code{#f} otherwise.
@end deffn
@@ -1716,7 +1716,7 @@ Returns the flonum that is numerically closest to the real number
@deffnx {Scheme Procedure} fl>=? fl1 fl2 fl3 ...
These procedures return @code{#t} if their flonum arguments are
(respectively): equal, monotonically increasing, monotonically
-decreasing, monotonically nondecreasing, or monotonically nonincrasing;
+decreasing, monotonically nondecreasing, or monotonically nonincreasing;
@code{#f} otherwise.
@end deffn
@@ -1915,7 +1915,7 @@ in the direction of more significant bits.
@end deffn
@deffn {Scheme Procedure} bitwise-reverse-bit-field ei1 ei2 ei3
-Returns the result of reversing the order of the bits of @var{e1}
+Returns the result of reversing the order of the bits of @var{ei1}
between position @var{ei2} (inclusive) and position @var{ei3}
(exclusive).
@end deffn
diff --git a/doc/ref/slib.texi b/doc/ref/slib.texi
index 5fe382d..388dae1 100644
--- a/doc/ref/slib.texi
+++ b/doc/ref/slib.texi
@@ -55,7 +55,7 @@ Library}):
@item
Unpack SLIB and install it using @code{make install} from its directory.
By default, this will install SLIB in @file{/usr/local/lib/slib/}.
-Running @code{make installinfo} installs its documentation, by default
+Running @code{make install-info} installs its documentation, by default
under @file{/usr/local/info/}.
@item
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index b214483..a6b98ee 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -391,13 +391,13 @@ Return a list containing all but the first @var{i} elements of
@end deffn
@deffn {Scheme Procedure} take-right lst i
-Return the a list containing the @var{i} last elements of @var{lst}.
+Return a list containing the @var{i} last elements of @var{lst}.
The return shares a common tail with @var{lst}.
@end deffn
@deffn {Scheme Procedure} drop-right lst i
@deffnx {Scheme Procedure} drop-right! lst i
-Return the a list containing all but the @var{i} last elements of
+Return a list containing all but the @var{i} last elements of
@var{lst}.
@code{drop-right} always returns a new list, even when @var{i} is
@@ -633,7 +633,7 @@ Determines when to stop unfolding.
Maps each seed value to the corresponding list element.
@item g
-Maps each seed value to next seed valu.
+Maps each seed value to next seed value.
@item seed
The state value for the unfold.
@@ -665,7 +665,7 @@ Determines when to stop unfolding.
Maps each seed value to the corresponding list element.
@item g
-Maps each seed value to next seed valu.
+Maps each seed value to next seed value.
@item seed
The state value for the unfold.
@@ -1678,7 +1678,7 @@ at the following odd index.
@deftypefnx {C Function} {const scm_t_int32 *} scm_s32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {const scm_t_uint64 *} scm_u64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {const scm_t_int64 *} scm_s64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
-@deftypefnx {C Function} {const float *} scm_f23vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
+@deftypefnx {C Function} {const float *} scm_f32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@@ -1695,7 +1695,7 @@ indicated kind.
@deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
-@deftypefnx {C Function} {float *} scm_f23vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
+@deftypefnx {C Function} {float *} scm_f32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@@ -1884,7 +1884,7 @@ The @var{fieldname}s provide the names for the record fields, as per
the core @code{record-type-fields} etc, and are referred to in the
subsequent accessor/modifier forms.
-@var{predictate} is bound to a function to be called as
+@var{predicate} is bound to a function to be called as
@code{(@var{predicate} obj)}. It returns @code{#t} or @code{#f}
according to whether @var{obj} is a record of this type.
@@ -4117,7 +4117,7 @@ stream-filter algorithm, expressed in a hypothetical lazy language as
(stream-filter p? t)))))
@end lisp
-This algorithm can be espressed as follows in Scheme:
+This algorithm can be expressed as follows in Scheme:
@lisp
(define (stream-filter p? s)
diff --git a/doc/ref/sxml-match.texi b/doc/ref/sxml-match.texi
index f92331b..7b82e11 100644
--- a/doc/ref/sxml-match.texi
+++ b/doc/ref/sxml-match.texi
@@ -298,7 +298,7 @@ basic arithmetic operations, which are represented by the XML elements
@end lisp
Using the catamorphism feature of @code{sxml-match}, a more concise version of
-@code{simple-eval} can be written. The pattern @code{,[x]} recusively invokes
+@code{simple-eval} can be written. The pattern @code{,[x]} recursively invokes
the pattern matcher on the value bound in this position.
@lisp
diff --git a/doc/ref/tools.texi b/doc/ref/tools.texi
index 2158344..2f4f59a 100644
--- a/doc/ref/tools.texi
+++ b/doc/ref/tools.texi
@@ -252,7 +252,7 @@ functions.
@node Writing your own snarfing macros
@subsubsection Writing your own snarfing macros
-When you want to use the general snarfing machanism, but none of the
+When you want to use the general snarfing mechanism, but none of the
provided macros fits your need, you can use the macro
@code{SCM_SNARF_INIT}.
diff --git a/doc/ref/vm.texi b/doc/ref/vm.texi
index 2c279bf..51fe8c4 100644
--- a/doc/ref/vm.texi
+++ b/doc/ref/vm.texi
@@ -746,7 +746,7 @@ Jump to @var{offset} if the number of arguments is not equal to, greater
than, or less than @var{n}. @var{n} is encoded over two bytes, and
@var{offset} has the normal three-byte encoding.
-These instructions are used to implement muliple arities, as in
+These instructions are used to implement multiple arities, as in
@code{case-lambda}. @xref{Case-lambda}, for more information.
@end deffn
@@ -803,7 +803,7 @@ keyword arguments to their local variable indices.
There are two bitflags that affect the parser, @code{allow-other-keys?}
(@code{0x1}) and @code{rest?} (@code{0x2}). Unless
@code{allow-other-keys?} is set, the parser will signal an error if an
-unknown key is found. If @code{rest?} is set, errors parsing the the
+unknown key is found. If @code{rest?} is set, errors parsing the
keyword arguments will be ignored, as a later @code{bind-rest}
instruction will collect all of the tail arguments, including the
keywords, into a list. Otherwise if the keyword arguments are invalid,
@@ -940,7 +940,7 @@ Jump to @var{offset} if the object on the stack is not @code{'()}.
@subsubsection Data Constructor Instructions
These instructions push simple immediate values onto the stack,
-or constructo compound data structures from values the stack.
+or constructor compound data structures from values the stack.
@deffn Instruction make-int8 value
Push @var{value}, an 8-bit integer, onto the stack.
@@ -1067,7 +1067,7 @@ encoded in the ``latin1'' locale.
@end deffn
@deffn Instruction load-wide-string length
Load a UTF-32 string from the instruction stream. @var{length} is the
-length in bytes, not in codepoints
+length in bytes, not in codepoints.
@end deffn
@deffn Instruction load-symbol length
Load a symbol from the instruction stream. The symbol is assumed to be
@@ -1228,7 +1228,7 @@ Since most of these operations are historically implemented as C
primitives, not inlining them would entail constantly calling out from
the VM to the interpreter, which has some costs---registers must be
saved, the interpreter has to dispatch, called procedures have to do
-much typechecking, etc. It's much more efficient to inline these
+much type checking, etc. It's much more efficient to inline these
operations in the virtual machine itself.
All of these instructions pop their arguments from the stack and push
diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index e285c2a..c7018e9 100644
--- a/doc/ref/web.texi
+++ b/doc/ref/web.texi
@@ -762,7 +762,7 @@ list is itself a list, in the same format as @code{content-type}.
(parse-header 'accept "text/html,text/plain;charset=utf-8")
@result{} ((text/html) (text/plain (charset . "utf-8")))
@end example
-Preference is expressed with qualitiy values:
+Preference is expressed with quality values:
@example
(parse-header 'accept "text/html;q=0.8,text/plain;q=0.6")
@result{} ((text/html (q . 800)) (text/plain (q . 600)))
@@ -1008,7 +1008,7 @@ A string identifying the server.
@deftypevr {HTTP Header} *|List vary
A set of request headers that were used in computing this response.
-Used to indicate that server-side content negotation was performed, for
+Used to indicate that server-side content negotiation was performed, for
example in response to the @code{accept-language} header. Can also be
the symbol @code{*}, indicating that all headers were considered.
@example
diff --git a/doc/sources/env.texi b/doc/sources/env.texi
index 3f51568..a3efce2 100644
--- a/doc/sources/env.texi
+++ b/doc/sources/env.texi
@@ -80,7 +80,7 @@ we document the Scheme procedure only, and call it a "Primitive". If a
Scheme function is marked as a primitive, you can derive the name of the
corresponding C function by changing @code{-} to @code{_}, @code{!} to
@code{_x}, @code{?} to @code{_p}, and prepending @code{scm_}. The C
-function's arguments will be all of the Scheme procedure's argumements,
+function's arguments will be all of the Scheme procedure's arguments,
both required and optional; if the Scheme procedure takes a ``rest''
argument, that will be a final argument to the C function. The C
function's arguments, as well as its return type, will be @code{SCM}.
@@ -735,7 +735,7 @@ changes the bindings of @var{local} or @var{imported}, those changes
will be visible in @var{eval}.
Since most Scheme evaluation takes place in @var{eval} environments,
-they transparenty cache the bindings received from @var{local} and
+they transparently cache the bindings received from @var{local} and
@var{imported}. Thus, the first time the program looks up a symbol in
@var{eval}, @var{eval} may make calls to @var{local} or @var{imported}
to find their bindings, but subsequent references to that symbol will be
@@ -1086,7 +1086,7 @@ Once this is done, we can make the following simplifications to Guile:
@item
A good portion of symbols.c can go away. Symbols no longer need value
-slots. The mismash of @code{scm_sym2ovcell},
+slots. The mishmash of @code{scm_sym2ovcell},
@code{scm_intern_obarray_soft}, etc. can go away. @code{intern} becomes
simpler.
diff --git a/doc/sources/jimb-org.texi b/doc/sources/jimb-org.texi
index 5ec4216..c4ad9ea 100644
--- a/doc/sources/jimb-org.texi
+++ b/doc/sources/jimb-org.texi
@@ -27,7 +27,7 @@ Part I: Guile Scheme
Keywords
Exceptions
Modules
- --- the preceeding three come first, because we need them
+ --- the preceding three come first, because we need them
in order to explain the behavior of some things later
Exception Handling
--- mention that repls usually establish default exception handlers
diff --git a/doc/sources/scheme-concepts.texi b/doc/sources/scheme-concepts.texi
index e8e78f1..0e9ae6c 100644
--- a/doc/sources/scheme-concepts.texi
+++ b/doc/sources/scheme-concepts.texi
@@ -204,7 +204,7 @@ arrays, uniform arrays, bit vectors:
@deffn procedure array-prototype ra
@end deffn
-Unform arrays can be written and read, but @code{read} won't recognize
+Uniform arrays can be written and read, but @code{read} won't recognize
them unless the optional @code{read-sharp} parameter is supplied,
e.g,
@smalllisp
diff --git a/doc/sources/unix.texi b/doc/sources/unix.texi
index 0ef894a..6754f8a 100644
--- a/doc/sources/unix.texi
+++ b/doc/sources/unix.texi
@@ -28,7 +28,7 @@ be required to make them available.
The low-level interfaces are designed to give Scheme programs
access to as much functionality as possible from the underlying
Unix system. They can be used to implement higher level
-intefaces such as the Scheme shell @ref{scsh}.
+interfaces such as the Scheme shell @ref{scsh}.
Generally there is a single procedure for each corresponding Unix
facility. However some of the procedures are implemented for
@@ -53,7 +53,7 @@ facility.
Underscores in Unix names are converted to hyphens.
@item
Procedures which destructively modify Scheme data gain postpended
-exclaimation marks, e.g., @code{recv!}.
+exclamation marks, e.g., @code{recv!}.
@item
Predicates are postpended with question marks, e.g., @code{access?}.
@item
diff --git a/module/ice-9/optargs.scm b/module/ice-9/optargs.scm
index 4e3267d..50a8299 100644
--- a/module/ice-9/optargs.scm
+++ b/module/ice-9/optargs.scm
@@ -269,7 +269,7 @@
;; take lambda*-style extended paramter lists, where #:optional,
;; #:key, #:allow-other-keys and #:rest are allowed with the usual
;; semantics. Here is an example of a macro with an optional argument:
-;; (defmacro* transmorgify (a #:optional b)
+;; (defmacro* transmogrify (a #:optional b)
(define-syntax defmacro*
(lambda (x)
--
1.7.4.rc1.6.gb704ef.dirty
[-- Attachment #4: 0003-fix-typos-in-the-manual-bits-generated-from-source-c.patch --]
[-- Type: text/plain, Size: 14025 bytes --]
From c837632602604496f82bb3e369a21dcde50269aa Mon Sep 17 00:00:00 2001
From: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
Date: Mon, 7 Feb 2011 00:29:51 +0100
Subject: [PATCH 3/5] fix typos in the manual bits generated from source comments.
* libguile/bitvectors.c, libguile/chars.c,
libguile/deprecated.c, libguile/numbers.c, libguile/random.c,
libguile/read.c, libguile/root.c, libguile/srfi-1.c,
libguile/srfi-13.c, libguile/srfi-14.c, libguile/uniform.c:
Fix typos, add missing newlines.
---
libguile/bitvectors.c | 2 +-
libguile/chars.c | 2 +-
libguile/deprecated.c | 2 +-
libguile/numbers.c | 2 +-
libguile/random.c | 2 +-
libguile/read.c | 2 +-
libguile/root.c | 6 +++---
libguile/srfi-1.c | 4 ++--
libguile/srfi-13.c | 24 ++++++++++++------------
libguile/srfi-14.c | 4 ++--
libguile/uniform.c | 4 ++--
11 files changed, 27 insertions(+), 27 deletions(-)
diff --git a/libguile/bitvectors.c b/libguile/bitvectors.c
index 65fc021..17b0260 100644
--- a/libguile/bitvectors.c
+++ b/libguile/bitvectors.c
@@ -496,7 +496,7 @@ find_first_one (scm_t_uint32 x)
SCM_DEFINE (scm_bit_position, "bit-position", 3, 0, 0,
(SCM item, SCM v, SCM k),
- "Return the index of the first occurrance of @var{item} in bit\n"
+ "Return the index of the first occurrence of @var{item} in bit\n"
"vector @var{v}, starting from @var{k}. If there is no\n"
"@var{item} entry between @var{k} and the end of\n"
"@var{bitvector}, then return @code{#f}. For example,\n"
diff --git a/libguile/chars.c b/libguile/chars.c
index fcc43f3..2e16105 100644
--- a/libguile/chars.c
+++ b/libguile/chars.c
@@ -265,7 +265,7 @@ SCM scm_char_ci_less_p (SCM x, SCM y)
static SCM scm_i_char_ci_leq_p (SCM x, SCM y, SCM rest);
SCM_DEFINE (scm_i_char_ci_leq_p, "char-ci<=?", 0, 2, 1,
(SCM x, SCM y, SCM rest),
- "Return @code{#t} iff the case-folded Unicodd code point of @var{x} is\n"
+ "Return @code{#t} iff the case-folded Unicode code point of @var{x} is\n"
"less than or equal to the case-folded code point of @var{y}, else\n"
"@code{#f}")
#define FUNC_NAME s_scm_i_char_ci_leq_p
diff --git a/libguile/deprecated.c b/libguile/deprecated.c
index e11d353..59ff341 100644
--- a/libguile/deprecated.c
+++ b/libguile/deprecated.c
@@ -1341,7 +1341,7 @@ SCM_DEFINE (scm_uniform_vector_read_x, "uniform-vector-read!", 1, 3, 0,
"leaving the remainder of the vector unchanged.\n\n"
"When @var{port-or-fdes} is a port, all specified elements\n"
"of @var{uvec} are attempted to be read, potentially blocking\n"
- "while waiting formore input or end-of-file.\n"
+ "while waiting for more input or end-of-file.\n"
"When @var{port-or-fd} is an integer, a single call to\n"
"read(2) is made.\n\n"
"An error is signalled when the last element has only\n"
diff --git a/libguile/numbers.c b/libguile/numbers.c
index 85ca0fd..bd9870f 100644
--- a/libguile/numbers.c
+++ b/libguile/numbers.c
@@ -7954,7 +7954,7 @@ SCM_PRIMITIVE_GENERIC (scm_exp, "exp", 1, 0, 0,
SCM_PRIMITIVE_GENERIC (scm_sqrt, "sqrt", 1, 0, 0,
(SCM z),
"Return the square root of @var{z}. Of the two possible roots\n"
- "(positive and negative), the one with the a positive real part\n"
+ "(positive and negative), the one with positive real part\n"
"is returned, or if that's zero then a positive imaginary part.\n"
"Thus,\n"
"\n"
diff --git a/libguile/random.c b/libguile/random.c
index f487eb8..8bc0d87 100644
--- a/libguile/random.c
+++ b/libguile/random.c
@@ -447,7 +447,7 @@ SCM_DEFINE (scm_seed_to_random_state, "seed->random-state", 1, 0, 0,
SCM_DEFINE (scm_datum_to_random_state, "datum->random-state", 1, 0, 0,
(SCM datum),
"Return a new random state using @var{datum}, which should have\n"
- "been obtailed from @code{random-state->datum}.")
+ "been obtained from @code{random-state->datum}.")
#define FUNC_NAME s_scm_datum_to_random_state
{
return make_rstate (scm_c_rstate_from_datum (datum));
diff --git a/libguile/read.c b/libguile/read.c
index 87eecfe..28a738e 100644
--- a/libguile/read.c
+++ b/libguile/read.c
@@ -1750,7 +1750,7 @@ scm_i_scan_for_encoding (SCM port)
SCM_DEFINE (scm_file_encoding, "file-encoding", 1, 0, 0,
(SCM port),
"Scans the port for an Emacs-like character coding declaration\n"
- "near the top of the contents of a port with random-acessible contents.\n"
+ "near the top of the contents of a port with random-accessible contents.\n"
"The coding declaration is of the form\n"
"@code{coding: XXXXX} and must appear in a scheme comment.\n"
"\n"
diff --git a/libguile/root.c b/libguile/root.c
index d35d8e8..8c8fd1a 100644
--- a/libguile/root.c
+++ b/libguile/root.c
@@ -155,9 +155,9 @@ cwdr (SCM proc, SCM a1, SCM args, SCM handler, SCM_STACKITEM *stack_start)
SCM_DEFINE (scm_call_with_dynamic_root, "call-with-dynamic-root", 2, 0, 0,
(SCM thunk, SCM handler),
- "Call @var{thunk} with a new dynamic state and within"
- "a continuation barrier. The @var{handler} catches all"
- "otherwise uncaught throws and executes within the same"
+ "Call @var{thunk} with a new dynamic state and within\n"
+ "a continuation barrier. The @var{handler} catches all\n"
+ "otherwise uncaught throws and executes within the same\n"
"dynamic context as @var{thunk}.")
#define FUNC_NAME s_scm_call_with_dynamic_root
{
diff --git a/libguile/srfi-1.c b/libguile/srfi-1.c
index 7931138..5c07504 100644
--- a/libguile/srfi-1.c
+++ b/libguile/srfi-1.c
@@ -1026,7 +1026,7 @@ SCM_DEFINE (scm_srfi1_assoc, "assoc", 2, 1, 0,
SCM_DEFINE (scm_srfi1_partition, "partition", 2, 0, 0,
(SCM pred, SCM list),
"Partition the elements of @var{list} with predicate @var{pred}.\n"
- "Return two values: the list of elements satifying @var{pred} and\n"
+ "Return two values: the list of elements satisfying @var{pred} and\n"
"the list of elements @emph{not} satisfying @var{pred}. The order\n"
"of the output lists follows the order of @var{list}. @var{list}\n"
"is not mutated. One of the output lists may share memory with @var{list}.\n")
@@ -1185,7 +1185,7 @@ SCM_DEFINE (scm_srfi1_remove_x, "remove!", 2, 0, 0,
SCM_DEFINE (scm_srfi1_take_right, "take-right", 2, 0, 0,
(SCM lst, SCM n),
- "Return the a list containing the @var{n} last elements of\n"
+ "Return a list containing the @var{n} last elements of\n"
"@var{lst}.")
#define FUNC_NAME s_scm_srfi1_take_right
{
diff --git a/libguile/srfi-13.c b/libguile/srfi-13.c
index 9efe275..ab933c2 100644
--- a/libguile/srfi-13.c
+++ b/libguile/srfi-13.c
@@ -1640,14 +1640,14 @@ SCM_DEFINE (scm_string_suffix_ci_p, "string-suffix-ci?", 2, 4, 0,
SCM_DEFINE (scm_string_index, "string-index", 2, 2, 0,
(SCM s, SCM char_pred, SCM start, SCM end),
"Search through the string @var{s} from left to right, returning\n"
- "the index of the first occurence of a character which\n"
+ "the index of the first occurrence of a character which\n"
"\n"
"@itemize @bullet\n"
"@item\n"
"equals @var{char_pred}, if it is character,\n"
"\n"
"@item\n"
- "satisifies the predicate @var{char_pred}, if it is a procedure,\n"
+ "satisfies the predicate @var{char_pred}, if it is a procedure,\n"
"\n"
"@item\n"
"is in the set @var{char_pred}, if it is a character set.\n"
@@ -1705,14 +1705,14 @@ SCM_DEFINE (scm_string_index, "string-index", 2, 2, 0,
SCM_DEFINE (scm_string_index_right, "string-index-right", 2, 2, 0,
(SCM s, SCM char_pred, SCM start, SCM end),
"Search through the string @var{s} from right to left, returning\n"
- "the index of the last occurence of a character which\n"
+ "the index of the last occurrence of a character which\n"
"\n"
"@itemize @bullet\n"
"@item\n"
"equals @var{char_pred}, if it is character,\n"
"\n"
"@item\n"
- "satisifies the predicate @var{char_pred}, if it is a procedure,\n"
+ "satisfies the predicate @var{char_pred}, if it is a procedure,\n"
"\n"
"@item\n"
"is in the set if @var{char_pred} is a character set.\n"
@@ -1770,14 +1770,14 @@ SCM_DEFINE (scm_string_index_right, "string-index-right", 2, 2, 0,
SCM_DEFINE (scm_string_rindex, "string-rindex", 2, 2, 0,
(SCM s, SCM char_pred, SCM start, SCM end),
"Search through the string @var{s} from right to left, returning\n"
- "the index of the last occurence of a character which\n"
+ "the index of the last occurrence of a character which\n"
"\n"
"@itemize @bullet\n"
"@item\n"
"equals @var{char_pred}, if it is character,\n"
"\n"
"@item\n"
- "satisifies the predicate @var{char_pred}, if it is a procedure,\n"
+ "satisfies the predicate @var{char_pred}, if it is a procedure,\n"
"\n"
"@item\n"
"is in the set if @var{char_pred} is a character set.\n"
@@ -1792,14 +1792,14 @@ SCM_DEFINE (scm_string_rindex, "string-rindex", 2, 2, 0,
SCM_DEFINE (scm_string_skip, "string-skip", 2, 2, 0,
(SCM s, SCM char_pred, SCM start, SCM end),
"Search through the string @var{s} from left to right, returning\n"
- "the index of the first occurence of a character which\n"
+ "the index of the first occurrence of a character which\n"
"\n"
"@itemize @bullet\n"
"@item\n"
"does not equal @var{char_pred}, if it is character,\n"
"\n"
"@item\n"
- "does not satisify the predicate @var{char_pred}, if it is a\n"
+ "does not satisfy the predicate @var{char_pred}, if it is a\n"
"procedure,\n"
"\n"
"@item\n"
@@ -1858,7 +1858,7 @@ SCM_DEFINE (scm_string_skip, "string-skip", 2, 2, 0,
SCM_DEFINE (scm_string_skip_right, "string-skip-right", 2, 2, 0,
(SCM s, SCM char_pred, SCM start, SCM end),
"Search through the string @var{s} from right to left, returning\n"
- "the index of the last occurence of a character which\n"
+ "the index of the last occurrence of a character which\n"
"\n"
"@itemize @bullet\n"
"@item\n"
@@ -1932,7 +1932,7 @@ SCM_DEFINE (scm_string_count, "string-count", 2, 2, 0,
"equals @var{char_pred}, if it is character,\n"
"\n"
"@item\n"
- "satisifies the predicate @var{char_pred}, if it is a procedure.\n"
+ "satisfies the predicate @var{char_pred}, if it is a procedure.\n"
"\n"
"@item\n"
"is in the set @var{char_pred}, if it is a character set.\n"
@@ -2459,7 +2459,7 @@ SCM_DEFINE (scm_string_concatenate_shared, "string-concatenate/shared", 1, 0, 0,
SCM_DEFINE (scm_string_concatenate_reverse_shared, "string-concatenate-reverse/shared", 1, 2, 0,
(SCM ls, SCM final_string, SCM end),
"Like @code{string-concatenate-reverse}, but the result may\n"
- "share memory with the the strings in the @var{ls} arguments.")
+ "share memory with the strings in the @var{ls} arguments.")
#define FUNC_NAME s_scm_string_concatenate_reverse_shared
{
/* Just call the non-sharing version. */
@@ -2969,7 +2969,7 @@ SCM_DEFINE (scm_string_tokenize, "string-tokenize", 1, 3, 0,
SCM_DEFINE (scm_string_split, "string-split", 2, 0, 0,
(SCM str, SCM chr),
- "Split the string @var{str} into the a list of the substrings delimited\n"
+ "Split the string @var{str} into a list of the substrings delimited\n"
"by appearances of the character @var{chr}. Note that an empty substring\n"
"between separator characters will result in an empty string in the\n"
"result list.\n"
diff --git a/libguile/srfi-14.c b/libguile/srfi-14.c
index af106ed..b22471d 100644
--- a/libguile/srfi-14.c
+++ b/libguile/srfi-14.c
@@ -1363,7 +1363,7 @@ SCM_DEFINE (scm_ucs_range_to_char_set, "ucs-range->char-set", 2, 2, 0,
"If @var{error} is a true value, an error is signalled if the\n"
"specified range contains characters which are not valid\n"
"Unicode code points. If @var{error} is @code{#f},\n"
- "these characters are silently left out of the resultung\n"
+ "these characters are silently left out of the resulting\n"
"character set.\n"
"\n"
"The characters in @var{base_cs} are added to the result, if\n"
@@ -1385,7 +1385,7 @@ SCM_DEFINE (scm_ucs_range_to_char_set_x, "ucs-range->char-set!", 4, 0, 0,
"If @var{error} is a true value, an error is signalled if the\n"
"specified range contains characters which are not contained in\n"
"the implemented character range. If @var{error} is @code{#f},\n"
- "these characters are silently left out of the resultung\n"
+ "these characters are silently left out of the resulting\n"
"character set.\n"
"\n"
"The characters are added to @var{base_cs} and @var{base_cs} is\n"
diff --git a/libguile/uniform.c b/libguile/uniform.c
index cab976e..d3ecb1b 100644
--- a/libguile/uniform.c
+++ b/libguile/uniform.c
@@ -160,7 +160,7 @@ scm_c_uniform_vector_ref (SCM v, size_t idx)
SCM_DEFINE (scm_uniform_vector_ref, "uniform-vector-ref", 2, 0, 0,
(SCM v, SCM idx),
"Return the element at index @var{idx} of the\n"
- "homogenous numeric vector @var{v}.")
+ "homogeneous numeric vector @var{v}.")
#define FUNC_NAME s_scm_uniform_vector_ref
{
return scm_c_uniform_vector_ref (v, scm_to_size_t (idx));
@@ -178,7 +178,7 @@ scm_c_uniform_vector_set_x (SCM v, size_t idx, SCM val)
SCM_DEFINE (scm_uniform_vector_set_x, "uniform-vector-set!", 3, 0, 0,
(SCM v, SCM idx, SCM val),
"Set the element at index @var{idx} of the\n"
- "homogenous numeric vector @var{v} to @var{val}.")
+ "homogeneous numeric vector @var{v} to @var{val}.")
#define FUNC_NAME s_scm_uniform_vector_set_x
{
scm_c_uniform_vector_set_x (v, scm_to_size_t (idx), val);
--
1.7.4.rc1.6.gb704ef.dirty
[-- Attachment #5: 0004-docs-fix-markup-in-api-options.texi.patch --]
[-- Type: text/plain, Size: 1967 bytes --]
From ae67f30cb1ff9354c240c09a62e4bcdebab82d8e Mon Sep 17 00:00:00 2001
From: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
Date: Tue, 8 Feb 2011 20:52:02 +0100
Subject: [PATCH 4/5] docs: fix markup in api-options.texi.
* doc/ref/api-options.texi (Build Config): Use @var for
metasyntactic variable. Add newline after @noindent.
Use @env for GUILE_LOAD_PATH.
---
doc/ref/api-options.texi | 11 ++++++-----
1 files changed, 6 insertions(+), 5 deletions(-)
diff --git a/doc/ref/api-options.texi b/doc/ref/api-options.texi
index 1102708..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/<GUILE_EFFECTIVE_VERSION>} or
-@file{/usr/share/guile/<GUILE_EFFECTIVE_VERSION>};
+@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
@@ -95,12 +96,12 @@ your site should be installed. On Unix-like systems, this is usually
@file{/usr/local/share/guile/site} or @file{/usr/share/guile/site}.
@end deffn
-@cindex GUILE_LOAD_PATH
+@cindex @env{GUILE_LOAD_PATH}
@defvar %load-path
List of directories which should be searched for Scheme modules and
libraries. @code{%load-path} is initialized when Guile starts up to
@code{(list (%site-dir) (%library-dir) (%package-data-dir))},
-prepended with the contents of the GUILE_LOAD_PATH environment variable,
+prepended with the contents of the @env{GUILE_LOAD_PATH} environment variable,
if it is set.
@end defvar
--
1.7.4.rc1.6.gb704ef.dirty
[-- Attachment #6: 0005-docs-add-missing-parentheses-in-asin-formula.patch --]
[-- Type: text/plain, Size: 803 bytes --]
From 6a07f96e3953c169c5407c6cf289f1599364a991 Mon Sep 17 00:00:00 2001
From: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
Date: Tue, 8 Feb 2011 21:13:07 +0100
Subject: [PATCH 5/5] docs: add missing parentheses in asin formula.
* doc/r5rs/r5rs.texi (Numerical operations): Add parentheses
around argument to sqrt.
---
doc/r5rs/r5rs.texi | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/doc/r5rs/r5rs.texi b/doc/r5rs/r5rs.texi
index 1c3df60..b7722c1 100644
--- a/doc/r5rs/r5rs.texi
+++ b/doc/r5rs/r5rs.texi
@@ -4446,7 +4446,7 @@ With log defined this way, the values of sin^-1 z, cos^-1 z,
and tan^-1 z are according to the following formulae:
-@center sin^-1 z = -i log (i z + sqrt1 - z^2)
+@center sin^-1 z = -i log (i z + sqrt(1 - z^2))
--
1.7.4.rc1.6.gb704ef.dirty
^ permalink raw reply related [flat|nested] 29+ messages in thread* Re: Typos in the manual
2011-02-08 20:25 Typos in the manual Ralf Wildenhues
@ 2011-02-13 0:49 ` Neil Jerram
2011-02-13 7:00 ` Ralf Wildenhues
2011-02-15 20:48 ` Mark Harig
0 siblings, 2 replies; 29+ messages in thread
From: Neil Jerram @ 2011-02-13 0:49 UTC (permalink / raw)
To: Ralf Wildenhues; +Cc: bug-guile
Ralf Wildenhues <Ralf.Wildenhues@gmx.de> 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/<GUILE_EFFECTIVE_VERSION>} or
> -@file{/usr/share/guile/<GUILE_EFFECTIVE_VERSION>};
> +@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 "resp. signed" into separate
signed and unsigned @deffns.
> diff --git a/doc/ref/compiler.texi b/doc/ref/compiler.texi
> index 8274a96..3c35cc8 100644
> --- 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.
> There are a few things that I spotted that I didn't fix, either because
> I didn't know which was the right way, or in cases that I've come to
> know as contentious among developers. It would be nice if you could go
> over them and address them in one way or another. Given consensus, I
> might be prodded into patching some, but don't count on me.
>
> - Word pairs you might want to review and/or maybe just use one set of:
> queuing vs. queueing,
queuing. Listed by merriam-webster.com before "queueing", wins 2:1 in a
googlefight, and is simpler.
> destructur.* vs. destruct.* vs. deconstr.*
> (unless they have different meanings of course),
In general, I believe these are all validly different. I believe the
use of "deconstructor" is idiomatic here (which is the only occurrence):
"
apply @code{force} to arguments of deconstructors (e.g., @code{car},
@code{cdr} and @code{null?}),
"
Similarly for the use of "destructuring" when talking about syntax.
An easily imaginable mistake would be "destruct" (wrong) rather than
"destroy" (right), but there aren't actually any instances of this.
> uninterned vs. non-internal,
"uninterned" is certainly idiomatic in the Lisp world. Where do you see
"non-internal"?
> latin1 vs. latin-1,
I'm happy to defer to you on that. What do you recommend?
> parsable vs. parseable.
parsable. "parseable" is a clear mistake, I'd say.
> - 'postpend': I'd replace this with 'append' throughout the tree
> (not just the manual).
I'm not seeing this.... (Have I missed some other discussion or patches
in this area?)
> - 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.
> - The Guile manual seems quite eager in making up new words. This is to
> some extent a tendency that just comes with hacking, and has both
> distinguished and entertaining aspects. At the same time however, it
> can make things less accessible for new users, especially those with a
> foreign native language, who then have troubles looking such words up
> in some dictionary. It starts with very simple things like 'dir' and
> 'arg' which I assume nobody has a serious problem with, yet which I
> would always write as 'directory' and 'argument' in prose
> (cf. 'info standards "GNU Manuals"'; but this goes beyond that
> text).
Agreed - patches appreciated.
> OTOH, things like 'unpermanent', 'cdring', and 'consing' are not easy
> to understand IMVHO.
I'd say "consing" is a close call. On the one hand it's certainly
idiomatic in Lisp/Scheme. On the other hand, a newbie would not know
it. Perhaps the term just needs to be clearly explained in the section
that describes lists, and maybe some references added from the other
uses?
The others are definitely unhelpful, and I'd be happy to accept a patch to
fix them.
>
> - 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.
> - I love France and the Franc, but there will soon be kids that don't
> remember it, for which 'french currency string' will be a foreign
> concept. It might be a good idea to update the example eventually.
Indeed, yes.
> Thanks for maintaining Guile,
> Ralf
Thanks for your detailed review and patches!
Neil
^ permalink raw reply [flat|nested] 29+ messages in thread* Re: Typos in the manual
2011-02-13 0:49 ` Neil Jerram
@ 2011-02-13 7:00 ` Ralf Wildenhues
2011-02-13 22:29 ` Neil Jerram
2011-02-15 15:48 ` Marijn
2011-02-15 20:48 ` Mark Harig
1 sibling, 2 replies; 29+ messages in thread
From: Ralf Wildenhues @ 2011-02-13 7:00 UTC (permalink / raw)
To: Neil Jerram; +Cc: bug-guile
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/<GUILE_EFFECTIVE_VERSION>} or
> > -@file{/usr/share/guile/<GUILE_EFFECTIVE_VERSION>};
> > +@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 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 "resp. signed" into separate
> signed and unsigned @deffns.
Sure.
> > --- 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.
> > uninterned vs. non-internal,
>
> "uninterned" is certainly idiomatic in the Lisp world. Where do you see
> "non-internal"?
Hmm, maybe that was what I thought "uninterned" would mean.
> > 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.
> > parsable vs. parseable.
>
> parsable. "parseable" is a clear mistake, I'd say.
I'm not so sure, I think both are possible.
> > - 'postpend': I'd replace this with 'append' throughout the tree
> > (not just the manual).
>
> I'm not seeing this.... (Have I missed some other discussion or patches
> in this area?)
doc/sources/unix.texi, two instances around line 60.
> > - 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?
Thanks,
Ralf
^ permalink raw reply [flat|nested] 29+ messages in thread* Re: Typos in the manual
2011-02-13 7:00 ` Ralf Wildenhues
@ 2011-02-13 22:29 ` Neil Jerram
2011-02-15 15:48 ` Marijn
1 sibling, 0 replies; 29+ messages in thread
From: Neil Jerram @ 2011-02-13 22:29 UTC (permalink / raw)
To: Ralf Wildenhues; +Cc: bug-guile
Ralf Wildenhues <Ralf.Wildenhues@gmx.de> 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
^ permalink raw reply [flat|nested] 29+ messages in thread* Re: Typos in the manual
2011-02-13 7:00 ` Ralf Wildenhues
2011-02-13 22:29 ` Neil Jerram
@ 2011-02-15 15:48 ` Marijn
2011-02-15 20:21 ` Mark Harig
2011-02-15 23:49 ` Neil Jerram
1 sibling, 2 replies; 29+ messages in thread
From: Marijn @ 2011-02-15 15:48 UTC (permalink / raw)
To: Ralf Wildenhues, Neil Jerram, bug-guile
-----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-----
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-15 15:48 ` Marijn
@ 2011-02-15 20:21 ` Mark Harig
2011-02-15 23:55 ` Neil Jerram
2011-02-15 23:49 ` Neil Jerram
1 sibling, 1 reply; 29+ messages in thread
From: Mark Harig @ 2011-02-15 20:21 UTC (permalink / raw)
To: bug-guile; +Cc: Ralf.Wildenhues, neil
>
> >>> --- 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.
--
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-15 20:21 ` Mark Harig
@ 2011-02-15 23:55 ` Neil Jerram
2011-02-16 0:52 ` Mark Harig
0 siblings, 1 reply; 29+ messages in thread
From: Neil Jerram @ 2011-02-15 23:55 UTC (permalink / raw)
To: Mark Harig; +Cc: bug-guile, Ralf.Wildenhues
Mark Harig <idirectscm@aim.com> 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
^ permalink raw reply [flat|nested] 29+ messages in thread* Re: Typos in the manual
2011-02-15 23:55 ` Neil Jerram
@ 2011-02-16 0:52 ` Mark Harig
2011-02-16 22:37 ` Neil Jerram
0 siblings, 1 reply; 29+ messages in thread
From: Mark Harig @ 2011-02-16 0:52 UTC (permalink / raw)
To: neil; +Cc: bug-guile, Ralf.Wildenhues
>
> > 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.
--
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-16 0:52 ` Mark Harig
@ 2011-02-16 22:37 ` Neil Jerram
0 siblings, 0 replies; 29+ messages in thread
From: Neil Jerram @ 2011-02-16 22:37 UTC (permalink / raw)
To: Mark Harig; +Cc: bug-guile, Ralf.Wildenhues, neil
On 16 February 2011 00:52, Mark Harig <idirectscm@aim.com> 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
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-15 15:48 ` Marijn
2011-02-15 20:21 ` Mark Harig
@ 2011-02-15 23:49 ` Neil Jerram
1 sibling, 0 replies; 29+ messages in thread
From: Neil Jerram @ 2011-02-15 23:49 UTC (permalink / raw)
To: Marijn; +Cc: bug-guile, Ralf Wildenhues
Marijn <hkBst@gentoo.org> 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
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-13 0:49 ` Neil Jerram
2011-02-13 7:00 ` Ralf Wildenhues
@ 2011-02-15 20:48 ` Mark Harig
2011-02-15 21:14 ` Ralf Wildenhues
1 sibling, 1 reply; 29+ messages in thread
From: Mark Harig @ 2011-02-15 20:48 UTC (permalink / raw)
To: bug-guile; +Cc: Ralf.Wildenhues, neil
>
> > - 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."
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-15 20:48 ` Mark Harig
@ 2011-02-15 21:14 ` Ralf Wildenhues
2011-02-15 22:32 ` Mark Harig
0 siblings, 1 reply; 29+ messages in thread
From: Ralf Wildenhues @ 2011-02-15 21:14 UTC (permalink / raw)
To: Mark Harig; +Cc: bug-guile, neil
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 ... :-)
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-15 21:14 ` Ralf Wildenhues
@ 2011-02-15 22:32 ` Mark Harig
2011-02-16 0:14 ` Neil Jerram
2011-02-16 21:17 ` Ludovic Courtès
0 siblings, 2 replies; 29+ messages in thread
From: Mark Harig @ 2011-02-15 22:32 UTC (permalink / raw)
To: Ralf.Wildenhues; +Cc: bug-guile, neil
>
> > 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.
--
^ permalink raw reply [flat|nested] 29+ messages in thread* Re: Typos in the manual
2011-02-15 22:32 ` Mark Harig
@ 2011-02-16 0:14 ` Neil Jerram
2011-02-16 2:43 ` Mark Harig
2011-02-16 3:03 ` Mark Harig
2011-02-16 21:17 ` Ludovic Courtès
1 sibling, 2 replies; 29+ messages in thread
From: Neil Jerram @ 2011-02-16 0:14 UTC (permalink / raw)
To: Mark Harig; +Cc: bug-guile, Ralf.Wildenhues
Mark Harig <idirectscm@aim.com> 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
^ permalink raw reply [flat|nested] 29+ messages in thread* Re: Typos in the manual
2011-02-16 0:14 ` Neil Jerram
@ 2011-02-16 2:43 ` Mark Harig
2011-02-16 3:30 ` Francis Southern
2011-02-16 3:03 ` Mark Harig
1 sibling, 1 reply; 29+ messages in thread
From: Mark Harig @ 2011-02-16 2:43 UTC (permalink / raw)
To: neil; +Cc: bug-guile, Ralf.Wildenhues
> >> 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.
--
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-16 2:43 ` Mark Harig
@ 2011-02-16 3:30 ` Francis Southern
2011-02-16 23:46 ` Neil Jerram
0 siblings, 1 reply; 29+ messages in thread
From: Francis Southern @ 2011-02-16 3:30 UTC (permalink / raw)
To: bug-guile
On 15 February 2011 20:43, Mark Harig <idirectscm@aim.com> 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.)
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-16 3:30 ` Francis Southern
@ 2011-02-16 23:46 ` Neil Jerram
0 siblings, 0 replies; 29+ messages in thread
From: Neil Jerram @ 2011-02-16 23:46 UTC (permalink / raw)
To: Francis Southern; +Cc: bug-guile
Francis Southern <francis.southern@gmail.com> writes:
> On 15 February 2011 20:43, Mark Harig <idirectscm@aim.com> 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
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-16 0:14 ` Neil Jerram
2011-02-16 2:43 ` Mark Harig
@ 2011-02-16 3:03 ` Mark Harig
2011-02-16 8:18 ` Thien-Thi Nguyen
2011-02-17 0:10 ` Neil Jerram
1 sibling, 2 replies; 29+ messages in thread
From: Mark Harig @ 2011-02-16 3:03 UTC (permalink / raw)
To: neil; +Cc: bug-guile, Ralf.Wildenhues
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?"
--
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-16 3:03 ` Mark Harig
@ 2011-02-16 8:18 ` Thien-Thi Nguyen
2011-02-17 0:10 ` Neil Jerram
1 sibling, 0 replies; 29+ messages in thread
From: Thien-Thi Nguyen @ 2011-02-16 8:18 UTC (permalink / raw)
To: Mark Harig; +Cc: bug-guile, Ralf.Wildenhues, neil
() Mark Harig <idirectscm@aim.com>
() 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.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-16 3:03 ` Mark Harig
2011-02-16 8:18 ` Thien-Thi Nguyen
@ 2011-02-17 0:10 ` Neil Jerram
2011-02-17 1:21 ` Mark Harig
1 sibling, 1 reply; 29+ messages in thread
From: Neil Jerram @ 2011-02-17 0:10 UTC (permalink / raw)
To: Mark Harig; +Cc: bug-guile, Ralf.Wildenhues
Mark Harig <idirectscm@aim.com> 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
^ permalink raw reply [flat|nested] 29+ messages in thread* Re: Typos in the manual
2011-02-17 0:10 ` Neil Jerram
@ 2011-02-17 1:21 ` Mark Harig
0 siblings, 0 replies; 29+ messages in thread
From: Mark Harig @ 2011-02-17 1:21 UTC (permalink / raw)
To: neil; +Cc: bug-guile, Ralf.Wildenhues
> >
> > >> > 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.
--
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-15 22:32 ` Mark Harig
2011-02-16 0:14 ` Neil Jerram
@ 2011-02-16 21:17 ` Ludovic Courtès
2011-02-17 0:14 ` Neil Jerram
2011-02-17 3:13 ` Mark Harig
1 sibling, 2 replies; 29+ messages in thread
From: Ludovic Courtès @ 2011-02-16 21:17 UTC (permalink / raw)
To: bug-guile
Hi!
While we’re at it...
Mark Harig <idirectscm@aim.com> 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’.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-16 21:17 ` Ludovic Courtès
@ 2011-02-17 0:14 ` Neil Jerram
2011-02-17 3:13 ` Mark Harig
1 sibling, 0 replies; 29+ messages in thread
From: Neil Jerram @ 2011-02-17 0:14 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: bug-guile
ludo@gnu.org (Ludovic Courtès) writes:
> Hi!
>
> While we’re at it...
>
> Mark Harig <idirectscm@aim.com> 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
^ permalink raw reply [flat|nested] 29+ messages in thread* Re: Typos in the manual
2011-02-16 21:17 ` Ludovic Courtès
2011-02-17 0:14 ` Neil Jerram
@ 2011-02-17 3:13 ` Mark Harig
2011-02-17 11:33 ` Andy Wingo
2011-02-21 20:23 ` Ludovic Courtès
1 sibling, 2 replies; 29+ messages in thread
From: Mark Harig @ 2011-02-17 3:13 UTC (permalink / raw)
To: ludo; +Cc: bug-guile
>
> > 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-<right>',
`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 in the buffer;
for example, you can place point by clicking mouse button 1
(normally the left button) at the desired location."
--
^ permalink raw reply [flat|nested] 29+ messages in thread* Re: Typos in the manual
2011-02-17 3:13 ` Mark Harig
@ 2011-02-17 11:33 ` Andy Wingo
2011-02-21 20:23 ` Ludovic Courtès
1 sibling, 0 replies; 29+ messages in thread
From: Andy Wingo @ 2011-02-17 11:33 UTC (permalink / raw)
To: Mark Harig; +Cc: bug-guile, ludo
On Thu 17 Feb 2011 04:13, Mark Harig <idirectscm@aim.com> 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/
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-17 3:13 ` Mark Harig
2011-02-17 11:33 ` Andy Wingo
@ 2011-02-21 20:23 ` Ludovic Courtès
1 sibling, 0 replies; 29+ messages in thread
From: Ludovic Courtès @ 2011-02-21 20:23 UTC (permalink / raw)
To: Mark Harig; +Cc: bug-guile
Hi Mark,
Mark Harig <idirectscm@aim.com> 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’.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
@ 2011-02-19 17:40 Bruno Haible
2011-02-19 17:56 ` Ralf Wildenhues
0 siblings, 1 reply; 29+ messages in thread
From: Bruno Haible @ 2011-02-19 17:40 UTC (permalink / raw)
To: bug-guile, Ralf Wildenhues
Regarding this commit:
<http://git.savannah.gnu.org/gitweb/?p=guile.git;a=commitdiff;h=c2c550ca9d2442d070f79ed8bacb8db173c72df3>
Ralf Wildenhues wrote in <http://lists.gnu.org/archive/html/bug-guile/2011-02/msg00052.html>:
> > > 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
<http://www.iana.org/assignments/character-sets>), 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 <http://en.wikipedia.org/wiki/Friedrich_Weißler>
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-19 17:40 Bruno Haible
@ 2011-02-19 17:56 ` Ralf Wildenhues
2011-02-24 23:31 ` Ludovic Courtès
0 siblings, 1 reply; 29+ messages in thread
From: Ralf Wildenhues @ 2011-02-19 17:56 UTC (permalink / raw)
To: Bruno Haible; +Cc: bug-guile
Hi Bruno,
* Bruno Haible wrote on Sat, Feb 19, 2011 at 06:40:23PM CET:
> Regarding this commit:
> <http://git.savannah.gnu.org/gitweb/?p=guile.git;a=commitdiff;h=c2c550ca9d2442d070f79ed8bacb8db173c72df3>
> Ralf Wildenhues wrote in <http://lists.gnu.org/archive/html/bug-guile/2011-02/msg00052.html>:
>
> > > > 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
> <http://www.iana.org/assignments/character-sets>), 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
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Typos in the manual
2011-02-19 17:56 ` Ralf Wildenhues
@ 2011-02-24 23:31 ` Ludovic Courtès
0 siblings, 0 replies; 29+ messages in thread
From: Ludovic Courtès @ 2011-02-24 23:31 UTC (permalink / raw)
To: bug-guile
Hi,
Ralf Wildenhues <Ralf.Wildenhues@gmx.de> writes:
> * Bruno Haible wrote on Sat, Feb 19, 2011 at 06:40:23PM CET:
>> Regarding this commit:
>> <http://git.savannah.gnu.org/gitweb/?p=guile.git;a=commitdiff;h=c2c550ca9d2442d070f79ed8bacb8db173c72df3>
>> Ralf Wildenhues wrote in <http://lists.gnu.org/archive/html/bug-guile/2011-02/msg00052.html>:
>>
>> > > > 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
>> <http://www.iana.org/assignments/character-sets>), 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’.
^ permalink raw reply [flat|nested] 29+ messages in thread
end of thread, other threads:[~2011-02-24 23:31 UTC | newest]
Thread overview: 29+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2011-02-08 20:25 Typos in the manual Ralf Wildenhues
2011-02-13 0:49 ` Neil Jerram
2011-02-13 7:00 ` Ralf Wildenhues
2011-02-13 22:29 ` Neil Jerram
2011-02-15 15:48 ` Marijn
2011-02-15 20:21 ` Mark Harig
2011-02-15 23:55 ` Neil Jerram
2011-02-16 0:52 ` Mark Harig
2011-02-16 22:37 ` Neil Jerram
2011-02-15 23:49 ` Neil Jerram
2011-02-15 20:48 ` Mark Harig
2011-02-15 21:14 ` Ralf Wildenhues
2011-02-15 22:32 ` Mark Harig
2011-02-16 0:14 ` Neil Jerram
2011-02-16 2:43 ` Mark Harig
2011-02-16 3:30 ` Francis Southern
2011-02-16 23:46 ` Neil Jerram
2011-02-16 3:03 ` Mark Harig
2011-02-16 8:18 ` Thien-Thi Nguyen
2011-02-17 0:10 ` Neil Jerram
2011-02-17 1:21 ` Mark Harig
2011-02-16 21:17 ` Ludovic Courtès
2011-02-17 0:14 ` Neil Jerram
2011-02-17 3:13 ` Mark Harig
2011-02-17 11:33 ` Andy Wingo
2011-02-21 20:23 ` Ludovic Courtès
-- strict thread matches above, loose matches on Subject: below --
2011-02-19 17:40 Bruno Haible
2011-02-19 17:56 ` Ralf Wildenhues
2011-02-24 23:31 ` Ludovic Courtès
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).