Re: [PATCH doc] use "cannot" consistently

[Sandra Loosemore]

On 03/15/2017 09:40 AM, Martin Sebor wrote:

On 03/15/2017 05:00 AM, Richard Kenner wrote:

First, I agree that the less formal language is becoming more
acceptable.  Some style guides explicitly allow contractions,
but others advise against them.  The technical specifications
that significant parts of GCC aim to conform to, and those I
happen  to work with the most closely (the C, C++, and POSIX
standards), avoid them.  The IEEE Editorial Style Manual
recommends against using them.  The author of Engineer's Guide
to Technical Writing, Kenneth Budinski, equates them with slang.


How old are those documents?  More recently, see


They're all the latest versions (C++ 2011, C++ 2017, and the IEEE
Editorial Style Manual is the 2016 update).

But to get a more representative sample I've surveyed some other
references I have sitting on my hard drive.  I found none that
uses contractions:

   ARM Compiler Toolchain 4.1 Reference (2011)
   Clang 5,0 Compiler User’s Manual(*) (2017)
   DWARF Debugging Information Format Version 5 (2017)
   HP aCC 6.20 C Programmer's Guide(**)(2008)
   IBM Power ISA Version 3.0 (2015)
   IBM XL C/C++ for Linux, V13.1 Compiler Reference (2014)
   Intel C++ Compiler 17.0 Developer Guide and Reference (2016)
   Intel 64 and IA-32 Architectures Software Developer’s Manual (2011)
   MIPS64 Architecture for Programmers (2010)
   Oracle Developer Studio 12.5 C/C++ Users Guide (2016)

   [*] Except for a few instances of don't.
   [**] "Can't" used in comments in coding examples.



http://www.plainlanguage.gov/howto/guidelines/bigdoc/writeContract.cfm

https://lawyerist.com/61487/is-it-time-for-contractions-in-legal-writing/

The latter references other documents, which advocate for more use of
contractions even in formal writing.


These are legal guides, obviously not relevant in the context
of technical writing.


I personally don't feel too strongly about it, but the change
seems like an opportunity to improve not just the style of
the manual but also increase its consistency.  I could see
one being indifferent to such changes but I have trouble
understanding how they could be viewed as the wrong direction.
What is your rationale against it and what would you consider
the right direction for the manual?


I think it's the wrong direction because I'd be in favor of gradually
*introducing* contractions into to the manual instead of a change that
eliminates them.  I wouldn't be against a change that went in the other
direction (used contractions consistently), but it would be good a large
change, so I'm not advocating for doing that, but just instead using
contractions in all new material and when modifying old material for
other reasons.


Interesting.  I don't share that view and clearly neither do
writers of any of the technical specifications I listed above
but I will go along with whatever the documentation maintainers
think is appropriate or preferable for GCC.


I got behind on mail so I'm coming into this a few days late  :-(

The GCC manual isn't as formal a document as a language standards 
document.  I think "can't" is OK, but OTOH I would write "cannot" 
myself, and since there's already a clear bias in favor of "cannot" in 
the text, I think the patch is OK, modulo fixing the one use in the example.


-Sandra

Re: [PATCH doc] use "cannot" consistently

[Richard Kenner]

> > The latter references other documents, which advocate for more use of
> > contractions even in formal writing.
> 
> These are legal guides, not obviously relevant in the context
> of technical writing.

Yes and no.  The argument for them is that legal writing is the most formal
of all and has been the slowest to adopt contractions.

Re: [PATCH doc] use "cannot" consistently

[Toon Moene]

On 03/14/2017 09:53 PM, Richard Kenner wrote:


The GCC manual uses "cannot" in most places (280 lines) but there
are a few instances of "can't" (33 lines).

The attached patch replaces the informal "can't" with the former
for consistency.


In my opinion, this is the wrong direction.  Contractions are becoming
more acceptable in even more formal writing and there's even a current
US Supreme Court justice who uses them in her opinions.

I certainly don't think it's worth a change to use "can't" throughout,
but I'm not in favor of eliminating it either.


I think for non-native speakers of English, using the full word is 
easier to read (you can't take my experience as an example, as I was 
exposed to written English 48 years ago).


I think replacing the few instances of can't with cannot is worth the 
clarity.


Kind regards,

--
Toon Moene - e-mail: t...@moene.org - phone: +31 346 214290
Saturnushof 14, 3738 XG  Maartensdijk, The Netherlands
At home: http://moene.org/~toon/; weather: http://moene.org/~hirlam/
Progress of GNU Fortran: http://gcc.gnu.org/wiki/GFortran#news

Re: [PATCH doc] use "cannot" consistently

[Martin Sebor]

On 03/15/2017 09:40 AM, Martin Sebor wrote:

On 03/15/2017 05:00 AM, Richard Kenner wrote:

First, I agree that the less formal language is becoming more
acceptable.  Some style guides explicitly allow contractions,
but others advise against them.  The technical specifications
that significant parts of GCC aim to conform to, and those I
happen  to work with the most closely (the C, C++, and POSIX
standards), avoid them.  The IEEE Editorial Style Manual
recommends against using them.  The author of Engineer's Guide
to Technical Writing, Kenneth Budinski, equates them with slang.


How old are those documents?  More recently, see


They're all the latest versions (C++ 2011, C++ 2017, and the IEEE
Editorial Style Manual is the 2016 update).

But to get a more representative sample I've surveyed some other
references I have sitting on my hard drive.  I found none that
uses contractions:

  ARM Compiler Toolchain 4.1 Reference (2011)
  Clang 5,0 Compiler User’s Manual(*) (2017)
  DWARF Debugging Information Format Version 5 (2017)
  HP aCC 6.20 C Programmer's Guide(**)(2008)
  IBM Power ISA Version 3.0 (2015)
  IBM XL C/C++ for Linux, V13.1 Compiler Reference (2014)
  Intel C++ Compiler 17.0 Developer Guide and Reference (2016)
  Intel 64 and IA-32 Architectures Software Developer’s Manual (2011)
  MIPS64 Architecture for Programmers (2010)
  Oracle Developer Studio 12.5 C/C++ Users Guide (2016)

  [*] Except for a few instances of don't.
  [**] "Can't" used in comments in coding examples.



http://www.plainlanguage.gov/howto/guidelines/bigdoc/writeContract.cfm

https://lawyerist.com/61487/is-it-time-for-contractions-in-legal-writing/

The latter references other documents, which advocate for more use of
contractions even in formal writing.


These are legal guides, obviously not relevant in the context
of technical writing.


Sorry, I meant "not obviously relevant."




I personally don't feel too strongly about it, but the change
seems like an opportunity to improve not just the style of
the manual but also increase its consistency.  I could see
one being indifferent to such changes but I have trouble
understanding how they could be viewed as the wrong direction.
What is your rationale against it and what would you consider
the right direction for the manual?


I think it's the wrong direction because I'd be in favor of gradually
*introducing* contractions into to the manual instead of a change that
eliminates them.  I wouldn't be against a change that went in the other
direction (used contractions consistently), but it would be good a large
change, so I'm not advocating for doing that, but just instead using
contractions in all new material and when modifying old material for
other reasons.


My disagreement aside, I should have thanked you for clarifying
your view.  (Thank you.)



Interesting.  I don't share that view and clearly neither do
writers of any of the technical specifications I listed above
but I will go along with whatever the documentation maintainers
think is appropriate or preferable for GCC.

Martin

Re: [PATCH doc] use "cannot" consistently

[Martin Sebor]

On 03/15/2017 05:00 AM, Richard Kenner wrote:

First, I agree that the less formal language is becoming more
acceptable.  Some style guides explicitly allow contractions,
but others advise against them.  The technical specifications
that significant parts of GCC aim to conform to, and those I
happen  to work with the most closely (the C, C++, and POSIX
standards), avoid them.  The IEEE Editorial Style Manual
recommends against using them.  The author of Engineer's Guide
to Technical Writing, Kenneth Budinski, equates them with slang.


How old are those documents?  More recently, see


They're all the latest versions (C++ 2011, C++ 2017, and the IEEE
Editorial Style Manual is the 2016 update).

But to get a more representative sample I've surveyed some other
references I have sitting on my hard drive.  I found none that
uses contractions:

  ARM Compiler Toolchain 4.1 Reference (2011)
  Clang 5,0 Compiler User’s Manual(*) (2017)
  DWARF Debugging Information Format Version 5 (2017)
  HP aCC 6.20 C Programmer's Guide(**)(2008)
  IBM Power ISA Version 3.0 (2015)
  IBM XL C/C++ for Linux, V13.1 Compiler Reference (2014)
  Intel C++ Compiler 17.0 Developer Guide and Reference (2016)
  Intel 64 and IA-32 Architectures Software Developer’s Manual (2011)
  MIPS64 Architecture for Programmers (2010)
  Oracle Developer Studio 12.5 C/C++ Users Guide (2016)

  [*] Except for a few instances of don't.
  [**] "Can't" used in comments in coding examples.


http://www.plainlanguage.gov/howto/guidelines/bigdoc/writeContract.cfm
https://lawyerist.com/61487/is-it-time-for-contractions-in-legal-writing/

The latter references other documents, which advocate for more use of
contractions even in formal writing.


These are legal guides, obviously not relevant in the context
of technical writing.


I personally don't feel too strongly about it, but the change
seems like an opportunity to improve not just the style of
the manual but also increase its consistency.  I could see
one being indifferent to such changes but I have trouble
understanding how they could be viewed as the wrong direction.
What is your rationale against it and what would you consider
the right direction for the manual?


I think it's the wrong direction because I'd be in favor of gradually
*introducing* contractions into to the manual instead of a change that
eliminates them.  I wouldn't be against a change that went in the other
direction (used contractions consistently), but it would be good a large
change, so I'm not advocating for doing that, but just instead using
contractions in all new material and when modifying old material for
other reasons.


Interesting.  I don't share that view and clearly neither do
writers of any of the technical specifications I listed above
but I will go along with whatever the documentation maintainers
think is appropriate or preferable for GCC.

Martin

Re: [PATCH doc] use "cannot" consistently

[Richard Kenner]

> First, I agree that the less formal language is becoming more
> acceptable.  Some style guides explicitly allow contractions,
> but others advise against them.  The technical specifications
> that significant parts of GCC aim to conform to, and those I
> happen  to work with the most closely (the C, C++, and POSIX
> standards), avoid them.  The IEEE Editorial Style Manual
> recommends against using them.  The author of Engineer's Guide
> to Technical Writing, Kenneth Budinski, equates them with slang.

How old are those documents?  More recently, see

http://www.plainlanguage.gov/howto/guidelines/bigdoc/writeContract.cfm
https://lawyerist.com/61487/is-it-time-for-contractions-in-legal-writing/

The latter references other documents, which advocate for more use of
contractions even in formal writing.

> I personally don't feel too strongly about it, but the change
> seems like an opportunity to improve not just the style of
> the manual but also increase its consistency.  I could see
> one being indifferent to such changes but I have trouble
> understanding how they could be viewed as the wrong direction.
> What is your rationale against it and what would you consider
> the right direction for the manual?

I think it's the wrong direction because I'd be in favor of gradually
*introducing* contractions into to the manual instead of a change that
eliminates them.  I wouldn't be against a change that went in the other
direction (used contractions consistently), but it would be good a large
change, so I'm not advocating for doing that, but just instead using
contractions in all new material and when modifying old material for
other reasons.

Re: [PATCH doc] use "cannot" consistently

[Martin Sebor]

On 03/14/2017 02:53 PM, Richard Kenner wrote:

The GCC manual uses "cannot" in most places (280 lines) but there
are a few instances of "can't" (33 lines).

The attached patch replaces the informal "can't" with the former
for consistency.


In my opinion, this is the wrong direction.  Contractions are becoming
more acceptable in even more formal writing and there's even a current
US Supreme Court justice who uses them in her opinions.

I certainly don't think it's worth a change to use "can't" throughout,
but I'm not in favor of eliminating it either.


I don't consider this change important enough to spend too much
time on but since you voiced an objection but offered little in
the way of a rationale I feel I'd be remiss not to respond and
explain my perspective.

First, I agree that the less formal language is becoming more
acceptable.  Some style guides explicitly allow contractions,
but others advise against them.  The technical specifications
that significant parts of GCC aim to conform to, and those I
happen  to work with the most closely (the C, C++, and POSIX
standards), avoid them.  The IEEE Editorial Style Manual
recommends against using them.  The author of Engineer's Guide
to Technical Writing, Kenneth Budinski, equates them with slang.

I personally don't feel too strongly about it, but the change
seems like an opportunity to improve not just the style of
the manual but also increase its consistency.  I could see
one being indifferent to such changes but I have trouble
understanding how they could be viewed as the wrong direction.
What is your rationale against it and what would you consider
the right direction for the manual?

Martin

PS While researching this subject I came across the following
two interesting references that I think are worth quoting:

In Engineer's Guide to Technical Writing, the author writes:

  Contractions should never be used in technical writing [my
  opinion].  They are essentially a form of slang, and slang
  expressions are not appropriate in technical writing.  Some
  technical writers disagree with it.  They believe that writing
  without contractions is stiff.  Use the appropriate practice
  for your organization.  Use contractions sparingly, if at all.

The NASA Technical Documentation Style Guide offers, in my view,
sound advice:

  Contractions (for example, it's for it is or it has; don't for
  do not; doesn't for does not; isn't for is not; and won't for
  will not) are not forbidden in technical or business writing.
  A few well-placed contractions can help your material sound as
  if a person wrote it--always a worthy goal.  But too many
  contractions can make your message sound too casual.

The challenge with following this advice in the GCC manual is
that engineers are rarely good at writing or judging the right
tone of text.  Often, contributions are also made by non-native
speakers some of whom may not be able to discern between the of
a contraction that helps achieve the goal and one that works
against it.  The one thing most of us do have is an eye and
affinity for consistency, so using one style consistently
throughout the manual seems like a good (and safe) approach.

Re: [PATCH doc] use "cannot" consistently

[Joseph Myers]

On Tue, 14 Mar 2017, Martin Sebor wrote:

> PS I wasted quite a bit of time updating tm.texi.  I kept getting
> the error below and didn't realize (forgot) that it was asking me
> to copy $objdir/gcc/tm.texi to $srcdir/gcc/doc/tm.texi.  Can
> someone explain why this file requires these special steps when
> the rest of the .texi files can be updated directly?

Both a GPL copy and a GFDL copy of the text shared between tm.texi and 
target.def need to be checked in (hence not just having tm.texi.in but not 
tm.texi checked in).  If existing text that was only in one place (so only 
under one of GPL and GFDL) is being moved so that there are copies under 
both licenses, then this involves docstring relicensing review (otherwise, 
just copying the generated tm.texi without any extra review for that 
copying is appropriate).

-- 
Joseph S. Myers
jos...@codesourcery.com

Re: [PATCH doc] use "cannot" consistently

[Martin Sebor]

On 03/14/2017 01:41 PM, Richard Sandiford wrote:

Martin Sebor  writes:

@@ -373,7 +373,7 @@ example, this code would produce an error:

 @smallexample
 #if 0
-You can't expect this to work.
+You cannot expect this to work.
 #endif
 @end smallexample



Sure the maintainers would have caught this, but: the "'" is needed here.
The point is that code doesn't tokenise properly.


Great catch, thanks!  I'll be sure to fix that if the patch is
approved.

Martin

Re: [PATCH doc] use "cannot" consistently

[Richard Kenner]

> The GCC manual uses "cannot" in most places (280 lines) but there
> are a few instances of "can't" (33 lines).
> 
> The attached patch replaces the informal "can't" with the former
> for consistency.

In my opinion, this is the wrong direction.  Contractions are becoming
more acceptable in even more formal writing and there's even a current
US Supreme Court justice who uses them in her opinions.

I certainly don't think it's worth a change to use "can't" throughout,
but I'm not in favor of eliminating it either.

Re: [PATCH doc] use "cannot" consistently

[Richard Sandiford]

Martin Sebor  writes:
> @@ -373,7 +373,7 @@ example, this code would produce an error:
>  
>  @smallexample
>  #if 0
> -You can't expect this to work.
> +You cannot expect this to work.
>  #endif
>  @end smallexample
>  

Sure the maintainers would have caught this, but: the "'" is needed here.
The point is that code doesn't tokenise properly.

Thanks,
Richard

[PATCH doc] use "cannot" consistently

[Martin Sebor]

In formal writing it's recommended to prefer the word "cannot"
to the somewhat informal "can't."

The GCC manual uses "cannot" in most places (280 lines) but there
are a few instances of "can't" (33 lines).

The attached patch replaces the informal "can't" with the former
for consistency.

Thanks
Martin

PS I wasted quite a bit of time updating tm.texi.  I kept getting
the error below and didn't realize (forgot) that it was asking me
to copy $objdir/gcc/tm.texi to $srcdir/gcc/doc/tm.texi.  Can
someone explain why this file requires these special steps when
the rest of the .texi files can be updated directly?

mv tmp2-tm.texi tmp-tm.texi
/bin/sh /src/gcc/svn/gcc/../move-if-change tmp-tm.texi tm.texi

Verify that you have permission to grant a GFDL license for all
new text in tm.texi, then copy it to /src/gcc/svn/gcc/doc/tm.texi.,
Makefile:2437: recipe for target 's-tm-texi' failed
Index: gcc/doc/extend.texi
===
--- gcc/doc/extend.texi	(revision 246134)
+++ gcc/doc/extend.texi	(working copy)
@@ -7509,7 +7509,7 @@ In this case, GCC does not actually output assembl
 function, unless you specify the option @option{-fkeep-inline-functions}.
 If there is a nonintegrated call, then the function is compiled to
 assembler code as usual.  The function must also be compiled as usual if
-the program refers to its address, because that can't be inlined.
+the program refers to its address, because that cannot be inlined.
 
 @opindex Winline
 Note that certain usages in a function definition can make it unsuitable
@@ -9176,7 +9176,7 @@ This results in an incomplete type, much like what
 @code{struct foo} without describing the elements.  A later declaration
 that does specify the possible values completes the type.
 
-You can't allocate variables or storage using the type while it is
+You cannot allocate variables or storage using the type while it is
 incomplete.  However, you can work with pointers to that type.
 
 This extension may not be very useful, but it makes the handling of
Index: gcc/doc/hostconfig.texi
===
--- gcc/doc/hostconfig.texi	(revision 246134)
+++ gcc/doc/hostconfig.texi	(working copy)
@@ -22,7 +22,7 @@ header.  @xref{System Config}.
 
 @menu
 * Host Common:: Things every host probably needs implemented.
-* Filesystem::  Your host can't have the letter `a' in filenames?
+* Filesystem::  Your host cannot have the letter `a' in filenames?
 * Host Misc::   Rare configuration options for hosts.
 @end menu
 
Index: gcc/doc/install.texi
===
--- gcc/doc/install.texi	(revision 246134)
+++ gcc/doc/install.texi	(working copy)
@@ -3633,7 +3633,7 @@ The libffi library haven't been ported to 64-bit H
 
 Refer to @uref{binaries.html,,binaries} for information about obtaining
 precompiled GCC binaries for HP-UX@.  Precompiled binaries must be obtained
-to build the Ada language as it can't be bootstrapped using C@.  Ada is
+to build the Ada language as it cannot be bootstrapped using C@.  Ada is
 only available for the 32-bit PA-RISC runtime.
 
 Starting with GCC 3.4 an ISO C compiler is required to bootstrap.  The
@@ -3713,12 +3713,12 @@ Although the HP and GNU linkers are both supported
 HP linker be used for link editing on this target.
 
 At this time, the GNU linker does not support the creation of long
-branch stubs.  As a result, it can't successfully link binaries
+branch stubs.  As a result, it cannot successfully link binaries
 containing branch offsets larger than 8 megabytes.  In addition,
 there are problems linking shared libraries, linking executables
 with @option{-static}, and with dwarf2 unwind and exception support.
 It also doesn't provide stubs for internal calls to global functions
-in shared libraries, so these calls can't be overloaded.
+in shared libraries, so these calls cannot be overloaded.
 
 The HP dynamic loader does not support GNU symbol versioning, so symbol
 versioning is not supported.  It may be necessary to disable symbol
Index: gcc/doc/invoke.texi
===
--- gcc/doc/invoke.texi	(revision 246134)
+++ gcc/doc/invoke.texi	(working copy)
@@ -6471,7 +6471,7 @@ different size.
 @opindex Winvalid-pch
 @opindex Wno-invalid-pch
 Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
-the search path but can't be used.
+the search path but cannot be used.
 
 @item -Wlong-long
 @opindex Wlong-long
@@ -10733,7 +10733,7 @@ more details.  The run-time behavior can be influe
 the available options are shown at startup of the instrumented program.  See
 @url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags}
 for a list of supported options.
-The option can't be combined with @option{-fsanitize=thread}
+The option cannot be combined with @option{-fsanitize=thread}