bug#10302: Some typos in web.texi documenation

bug#10302: Some typos in web.texi documenation

[jc zulian]

[-- Attachment #1.1: Type: text/plain, Size: 189 bytes --]

Hello,

While reading the documentation I came across some typos. Please find
attached a patch to correct those (I hope the patch format is alright).

Thanks for your work,
Jean-christophe

[-- Attachment #1.2: Type: text/html, Size: 248 bytes --]

[-- Attachment #2: typos-web-doc.patch --]
[-- Type: text/x-patch, Size: 789 bytes --]

diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index d98f1bb..795e2c9 100644
--- a/doc/ref/web.texi
+++ b/doc/ref/web.texi
@@ -349,7 +349,7 @@ parsing and serialization procedures.  If a header is unknown, its
 string name is simply its symbol name in title-case.
 
 @deffn {Scheme Procedure} known-header? sym
-Return @code{#t} iff @var{sym} is a known header, with associated
+Return @code{#t} if @var{sym} is a known header, with associated
 parsers and serialization procedures.
 @end deffn
 
@@ -398,7 +398,7 @@ HTTP stack like this:
 @end example
 
 @deffn {Scheme Procedure} valid-header? sym val
-Return a true value iff @var{val} is a valid Scheme value for the header
+Return a true value if @var{val} is a valid Scheme value for the header
 with name @var{sym}.
 @end deffn
 

bug#10302: Some typos in web.texi documenation

[Mark H Weaver]

jc zulian <jeanchristophe.zulian@gmail.com> writes:
> While reading the documentation I came across some typos. Please find
> attached a patch to correct those (I hope the patch format is
> alright).

Actually those are not typos.  In mathematics, "iff" is widely
understand to mean "if and only if".

I guess this brings up a good point though: We should not assume that
readers of the Guile manual are familiar with this terminology.

I'm leaving this bug open as a reminder that occurrences of "iff" should
probably be changed to something else.

Thanks for the report!

      Mark

bug#10302: Some typos in web.texi documenation

[jc zulian]

[-- Attachment #1: Type: text/plain, Size: 891 bytes --]

Hello Mark,

Thanks for your explanation. I knew about the mathematical "if and only
if". But as I am not a native english speaker I didn't know it could be
spelled 'iff'.

Thanks again,
Jean-christophe

On Thu, Dec 15, 2011 at 5:27 AM, Mark H Weaver <mhw@netris.org> wrote:

> jc zulian <jeanchristophe.zulian@gmail.com> writes:
> > While reading the documentation I came across some typos. Please find
> > attached a patch to correct those (I hope the patch format is
> > alright).
>
> Actually those are not typos.  In mathematics, "iff" is widely
> understand to mean "if and only if".
>
> I guess this brings up a good point though: We should not assume that
> readers of the Guile manual are familiar with this terminology.
>
> I'm leaving this bug open as a reminder that occurrences of "iff" should
> probably be changed to something else.
>
> Thanks for the report!
>
>      Mark
>

[-- Attachment #2: Type: text/html, Size: 1414 bytes --]

bug#10302: Some typos in web.texi documenation

[Andy Wingo]

Thanks for the follow-up, Mark.

On Thu 15 Dec 2011 05:27, Mark H Weaver <mhw@netris.org> writes:

> jc zulian <jeanchristophe.zulian@gmail.com> writes:
>> While reading the documentation I came across some typos. Please find
>> attached a patch to correct those (I hope the patch format is
>> alright).
>
> Actually those are not typos.  In mathematics, "iff" is widely
> understand to mean "if and only if".
>
> I guess this brings up a good point though: We should not assume that
> readers of the Guile manual are familiar with this terminology.

Indeed, the intro notes this:

  http://www.gnu.org/software/guile/manual/html_node/Typographical-Conventions.html

> I'm leaving this bug open as a reminder that occurrences of "iff" should
> probably be changed to something else.

I wonder, it might be the right thing just to change them all to "if".
WDYT?

Andy
-- 
http://wingolog.org/

bug#10302: Some typos in web.texi documenation

[jc zulian]

[-- Attachment #1: Type: text/plain, Size: 2944 bytes --]

Hello,

Allow me to share with you some ideas about this topic.

To me the 'iff' was a typo at first sight for many reasons:
   - it looks like the regular type of typo one would do, pressing twice
the same letter by leaving the finger too long on a key
   - the word doesn't exist in every dictionaries. I didn't find it in my
English dictionary (regular one on paper) but I did however find it in
wikipedia and on online dictionaries.
   - as a non-native-english speaker I never came across it before
(although I read a lot in english, both technical and non-technical texts)

Although it is "defined" in guile documentation in the typographical
convention I wouldn't have had the idea to look there because it doesn't
look like a typographical symbol. Usually those symbols are really looking
like "real symbol", understand graphical symbol (ie any kind of arrows, or
icons). Maybe it could be possible then to use one of the mathematical
symbols used to represent iff. Then for sure it cannot be taken for a typo.

Also I have the feeling that in the typographical convention of guile's
documentation the meaning of iff is somewhat redefined. In there the
meaning is "returns val if condition is true and #f otherwise" (if I
understood correctly). But after having a quick read at the wikipedia page
of iff I feel that the definitions are not exatly the same. But I might be
wrong here, I never study mathematic to a high level and never approach the
logic branch of it.

Maybe another option could be to add a reference link where iff is used
bringing readers to the typographical convention.

Or it could be possible, as you already suggested, to use a more commonly
used 'if' and build a longer sentence around it (eg if x then y otherwise
z).

These are my inputs on the topic, but I can't tell what would be best thing
to do. But for sure I have learn something and won't get confused anymore.

Regards,
Jean-christophe


On Thu, Dec 15, 2011 at 3:19 PM, Andy Wingo <wingo@pobox.com> wrote:

> Thanks for the follow-up, Mark.
>
> On Thu 15 Dec 2011 05:27, Mark H Weaver <mhw@netris.org> writes:
>
> > jc zulian <jeanchristophe.zulian@gmail.com> writes:
> >> While reading the documentation I came across some typos. Please find
> >> attached a patch to correct those (I hope the patch format is
> >> alright).
> >
> > Actually those are not typos.  In mathematics, "iff" is widely
> > understand to mean "if and only if".
> >
> > I guess this brings up a good point though: We should not assume that
> > readers of the Guile manual are familiar with this terminology.
>
> Indeed, the intro notes this:
>
>
> http://www.gnu.org/software/guile/manual/html_node/Typographical-Conventions.html
>
> > I'm leaving this bug open as a reminder that occurrences of "iff" should
> > probably be changed to something else.
>
> I wonder, it might be the right thing just to change them all to "if".
> WDYT?
>
> Andy
> --
> http://wingolog.org/
>

[-- Attachment #2: Type: text/html, Size: 4054 bytes --]

bug#10302: Some typos in web.texi documenation

[Marijn]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 15-12-11 22:08, jc zulian wrote:
> Or it could be possible, as you already suggested, to use a more
> commonly used 'if' and build a longer sentence around it (eg if x
> then y otherwise z).

Personally I like this suggestion a lot.

Marijn
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.18 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk7q908ACgkQp/VmCx0OL2zp7QCeILdA7pF7297E/QSwGL/DDVlc
rPUAni8jjf6zYRAbQkB4Tqu0xcl5kYHh
=TlN8
-----END PGP SIGNATURE-----

bug#10302: Some typos in web.texi documenation

[Andy Wingo]

On Fri 16 Dec 2011 08:46, Marijn <hkBst@gentoo.org> writes:

> On 15-12-11 22:08, jc zulian wrote:
>> Or it could be possible, as you already suggested, to use a more
>> commonly used 'if' and build a longer sentence around it (eg if x
>> then y otherwise z).
>
> Personally I like this suggestion a lot.

Done.
-- 
http://wingolog.org/