Re: Typos in the manual

[Neil Jerram <neil@ossau.uklinux.net>]

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