[PATCH doc] use "cannot" consistently

Sandra Loosemore sandra@codesourcery.com
Sun Mar 19 20:12:00 GMT 2017


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



More information about the Gcc-patches mailing list