Re: Typos in the manual

[Neil Jerram]

Ralf Wildenhues <address@hidden> 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
> address@hidden/usr/local/share/guile/<GUILE_EFFECTIVE_VERSION>} or
> address@hidden/usr/share/guile/<GUILE_EFFECTIVE_VERSION>};
> address@hidden/usr/local/share/guile/@var{GUILE_EFFECTIVE_VERSION}} or
> address@hidden/usr/share/guile/@var{GUILE_EFFECTIVE_VERSION}};
>  
> address@hidden for example @file{/usr/local/share/guile/1.6}.
> address@hidden
> +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
> address@hidden(\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.
> address@hidden(\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