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
