[PATCH doc] use "cannot" consistently
Martin Sebor
msebor@gmail.com
Wed Mar 15 15:40:00 GMT 2017
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
More information about the Gcc-patches
mailing list