Re: Typos in the manual

[Ralf Wildenhues]

Hi Neil,

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

Thank you!

Not quoting stuff I completely agree with:

> > --- a/doc/ref/api-options.texi
> > +++ b/doc/ref/api-options.texi
> > @@ -82,10 +82,11 @@ general are stored.  On Unix-like systems, this is 
> > usually
> >  Return the name of the directory where the Guile Scheme files that
> >  belong to the core Guile installation (as opposed to files from a 3rd
> >  party package) are installed.  On Unix-like systems this is usually
> > 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.

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
> > 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} ?

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