[edk2-CCodingStandardsSpecification PATCH 0/5] Typographic Corrections

[edk2-CCodingStandardsSpecification PATCH 0/5] Typographic Corrections

[evan.lloyd]

From: Evan Lloyd <evan.lloyd@arm.com>

https://bugzilla.tianocore.org/show_bug.cgi?id=839

This patch set contains a number of minor typographical corrections.
They have no specific theme, being only that set of things I happened to
notice during recent code review sessions where I was frequently
consulting the CCS.  Some are pedantic or may come under the heading of
"Typographic silliness", but they were enough to distract my attention
from the content, so fixing them may help others.

GitHub branch for review:
https://github.com/EvanLloyd/edk2-CCodingStandardsSpecification/tree/17Q4Typos_v1

GitHub word diff view of the patches in this series:
https://github.com/tianocore-docs/edk2-CCodingStandardsSpecification/compare/master...EvanLloyd:17Q4Typos_v1?w1


Evan Lloyd (5):
  Fix Chapter 1 Typos
  Fix Chapter 2 Typos
  Fix Chapter 3 Typos
  Fix Chapter 4 Typo
  Fix Chapter 5 Typos

 1_introduction.md                           |  12 +-
 2_guiding_principles.md                     |   8 +-
 3_quick_reference.md                        |   2 +-
 4_naming_conventions/README.md              | 418 ++++++++++----------
 5_source_files/52_spacing.md                |   9 +-
 5_source_files/54_code_file_structure.md    |   4 +-
 5_source_files/56_declarations_and_types.md |   4 +-
 5_source_files/README.md                    |  18 +-
 8 files changed, 238 insertions(+), 237 deletions(-)

-- 
Guid("CE165669-3EF3-493F-B85D-6190EE5B9759")

[edk2-CCodingStandardsSpecification PATCH 1/5] Fix Chapter 1 Typos

[evan.lloyd]

From: Evan Lloyd <evan.lloyd@arm.com>

    1.1 Abstract - replace "then" with "can" (to make meaningful)
    1.2 Rationale - change
          "commit to conforming to standards of this specification"
      to   commit to conforming with the standards of this specification
    1.3 Scope - add missing "to" in "an attempt make you aware of your
      actions"

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
---
 1_introduction.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/1_introduction.md b/1_introduction.md
index c22c04c9f76d2352e4f294c0e70f5ebf787f7054..5471a6bf5e94df6dd0c5fd0a4b5020c77d1f8ca0 100644
--- a/1_introduction.md
+++ b/1_introduction.md
@@ -62,7 +62,7 @@ This specification addresses the chronic problem of providing accurate
 documentation of the code base by embedding the documentation within the code.
 While this does not guarantee that the documentation will be kept up to date,
 it significantly increases the chances. A document generation system, Doxygen,
-then produce formatted documentation by extracting information from specially
+can produce formatted documentation by extracting information from specially
 formatted comment blocks and the syntactic elements of the code.
 
 This specification presents protocol standards that will ensure that the
@@ -97,10 +97,10 @@ wide support. On the downside in that each developer's C code could
 lack of uniformity makes understanding and maintaining the code very difficult.
 
 Uniformity is the key theme of these rules. You may disagree with some of our
-decisions. Nevertheless, we ask that you commit to conforming to standards of
-this specification. Also, there are pitfalls inherent in the C language that
-this style guide may help you to avoid. The goal of this document is making
-you, and those who follow you, more productive.
+decisions. Nevertheless, we ask that you commit to conforming with the
+standards of this specification. Also, there are pitfalls inherent in the C
+language that this style guide may help you to avoid. The goal of this document
+is making you, and those who follow you, more productive.
 
 Some of the strict rules for protocol and driver construction may seem overly
 onerous. Don't panic - there is a method to our madness - we intend to
@@ -161,7 +161,7 @@ Topics covered in this coding standard include:
 * Commenting rules
 * Doxygen
 
-These guidelines represent an attempt make you aware of your actions, because
+These guidelines represent an attempt to make you aware of your actions, because
 those actions affect the future readers and maintainers of the code you produce.
 
 Pre-existing code ported to the EDK II environment does not have to conform to
-- 
Guid("CE165669-3EF3-493F-B85D-6190EE5B9759")

[edk2-CCodingStandardsSpecification PATCH 2/5] Fix Chapter 2 Typos

[evan.lloyd]

From: Evan Lloyd <evan.lloyd@arm.com>

2.1 Accessibility - remove erroneous "as"
2.1 Confirmation - insert missing full stop
2.1 Forgiveness - excise superfluous "errors"
2.1 Standard techniques - remove redundant "be to"

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
---
 2_guiding_principles.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/2_guiding_principles.md b/2_guiding_principles.md
index a7759f27dcf71a948b903332c9bc14946e445cd8..5a51225b65dec2159a4fb94481920666c0d042ff 100644
--- a/2_guiding_principles.md
+++ b/2_guiding_principles.md
@@ -47,7 +47,7 @@ The following is an alphabetical list of software design principles:
 **Accessibility**
 
 This entails designing objects and environments to be usable, with no
-modification, by the greatest number of people as possible, including people
+modification, by the greatest number of people possible, including people
 with varying educational and social backgrounds, as well as those with motor or
 sensory challenges.
 
@@ -68,7 +68,7 @@ shortterm memory, as well as to accommodate its limits.
 This is a technique used for critical actions, inputs, or commands.
 Confirmations are primarily used to prevent unintended actions. Minimize errors
 in critical or irreversible operations with confirmations. If you overuse
-confirmations, expect that they will be ignored Avoid overusing confirmations
+confirmations, expect that they will be ignored. Avoid overusing confirmations
 to ensure that they remain unexpected and uncommon; otherwise, they may be
 ignored. Use a two-step operation for hardware confirmations and dialogs for
 software confirmations.
@@ -97,7 +97,7 @@ about the assumptions you make.
 **Forgiveness**
 
 Design to help users avoid errors and reduce the negative consequences of
-errors any errors made. Recommended methods for achieving design forgiveness
+any errors made. Recommended methods for achieving design forgiveness
 include affordances, reversibility of actions, and safety nets. Effectively
 designing for forgiveness results in a design needing minimal confirmations,
 warnings, and help.
@@ -171,7 +171,7 @@ classes of platforms from embedded systems to massively parallel computers.
 
 Greater reliance on unique or exotic pieces makes a system harder to
 understand, and more intimidating for someone trying to understand it the first
-time. Using standardized, common approaches should be to give the whole system
+time. Using standardized, common approaches should give the whole system
 a familiar feeling. This standardization is one of the primary goals of this
 document.
 
-- 
Guid("CE165669-3EF3-493F-B85D-6190EE5B9759")

[edk2-CCodingStandardsSpecification PATCH 3/5] Fix Chapter 3 Typos

[evan.lloyd]

From: Evan Lloyd <evan.lloyd@arm.com>

3_quick_reference.md has some obviously invalid extra characters at the
end of line 55 ( ",).  This patch removes them.

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
---
 3_quick_reference.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/3_quick_reference.md b/3_quick_reference.md
index 13045d297b3be848d91f9be05380454b4cc2fe91..9367e422fb0337007409d6597913cb43da92e0c5 100644
--- a/3_quick_reference.md
+++ b/3_quick_reference.md
@@ -55,7 +55,7 @@
   any file using the abbreviation or acronym. See "Abbreviation Usage" and
   "Glossary".
 
-* There is no limit to name lengths. A length of 10 to 30 characters is ",
+* There is no limit to name lengths. A length of 10 to 30 characters is
   recommended. See "File Names" & "Identifiers that are always reserved".
 
 * File names must not start with numbers. See "File Names".
-- 
Guid("CE165669-3EF3-493F-B85D-6190EE5B9759")

[edk2-CCodingStandardsSpecification PATCH 4/5] Fix Chapter 4 Typo

[evan.lloyd]

From: Evan Lloyd <evan.lloyd@arm.com>

4.1.3.2 - remove "See" from 'as specified in See "File Heading"'

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
---
 4_naming_conventions/README.md | 418 ++++++++++----------
 1 file changed, 209 insertions(+), 209 deletions(-)

diff --git a/4_naming_conventions/README.md b/4_naming_conventions/README.md
index bcf902875719f94c5c4c3e58af24e18772dae055..1a9cd008b5dbbf203148408f92ffb4881f499766 100644
--- a/4_naming_conventions/README.md
+++ b/4_naming_conventions/README.md
@@ -1,209 +1,209 @@
-<!--- @file
-  4 Naming Conventions
-
-  Copyright (c) 2006-2017, Intel Corporation. All rights reserved.<BR>
-
-  Redistribution and use in source (original document form) and 'compiled'
-  forms (converted to PDF, epub, HTML and other formats) with or without
-  modification, are permitted provided that the following conditions are met:
-
-  1) Redistributions of source code (original document form) must retain the
-     above copyright notice, this list of conditions and the following
-     disclaimer as the first lines of this file unmodified.
-
-  2) Redistributions in compiled form (transformed to other DTDs, converted to
-     PDF, epub, HTML and other formats) must reproduce the above copyright
-     notice, this list of conditions and the following disclaimer in the
-     documentation and/or other materials provided with the distribution.
-
-  THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
-  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
-  EVENT SHALL TIANOCORE PROJECT  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
-  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
-  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
-  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
-  ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
--->
-
-# 4 Naming Conventions
-
-## 4.1 General Naming Rules
-
-**Use good naming practice when declaring variable names.**
-
-Studies show that programs with names averaging 10 to 16 characters are the
-easiest to debug. The name length is just a guideline_; the most important
-thing is that the name conveys a clear meaning of what it represents_.
-
-**Do not overload commonly used terms.**
-
-For example, EFI has an event model, so don't call some abstraction that you
-define an Event. People will get confused. Make sure someone reading the code
-can tell what you are talking about.
-
-**Each word or concept must start with a capital letter and be followed by
-lower-case letters.**
-
-The intent is for names to be consistent and easily readable. Each word in a
-compound name should be visually distinct.
-
-### 4.1.1 Identifiers that are always reserved
-
-**Identifiers beginning with an underscore are always reserved**
-
-Define them only in the special ways allowed elsewhere in this document.
-
-**Identifiers that are defined in the Standard C and POSIX libraries are always
-reserved.**
-
-This includes macros, typedefs, variables, and functions, whether with external
-linkage or file scope. The only exception is with modules that are mutually
-exclusive with these libraries. These reserved identifiers are listed in
-"Reserved Identifiers" and reserved keywords are listed in "Reserved Keywords".
-
-### 4.1.2 Common Opposites in Variable Names
-
-Use the correct opposites when declaring names.
-
-###### Table 1 Common Opposites
-
-|                       |                 |                  |
-| --------------------- | --------------- | ---------------- |
-| add / remove          | begin / end     | create / destroy |
-| increment / decrement | first / last    | get / release    |
-| lock / unlock         | put / get       | up / down        |
-| old / new             | min / max       | next / previous  |
-| source / destination  | open / close    | show / hide      |
-|                       | source / target | start / stop     |
-
-### 4.1.3 Abbreviation Usage
-
-#### 4.1.3.1 The use of abbreviations shall be regulated.
-
-This document describes a common set of abbreviations that can be freely used.
-If you must make up abbreviations, remember the name is most important to the
-reader of the code, not the writer.
-
-#### 4.1.3.2 New abbreviations must be documented in the header of each using file.
-
-Any abbreviation used, which is not documented in this specification, or in the
-_UEFI Specification_ shall be placed into a Glossary section of the File header
-as specified in See "File Heading".
-
-Do not define a new abbreviation to replace an abbreviation that is already
-defined in this document. For example, do not define No to mean Number, because
-Num is the supported abbreviation.
-
-"EFI Supported Abbreviations" below lists the abbreviations that are
-standardized by this document and do not require a defining comment.
-
-###### Table 2 EFI Supported Abbreviations
-
-| Abbreviation | Description             |
-| ------------ | ----------------------- |
-| Ptr          | Pointer                 |
-| Str          | Unicode string          |
-| Ascii        | ASCII string            |
-| Len          | Length                  |
-| Arg          | Argument                |
-| Max          | Maximum                 |
-| Min          | Minimum                 |
-| Char         | Character               |
-| Num          | Number                  |
-| Temp         | Temporary               |
-| Src          | Source                  |
-| Dst          | Destination             |
-| BS           | EFI Boot Services Table |
-| RT           | EFI Runtime Table       |
-| ST           | EFI System Table        |
-| Tpl          | EFI Task Priority Level |
-
-#### 4.1.3.3 Powers of 2 and 10
-
-You are encouraged to use the IEC international abbreviations for powers of 2
-(KiB for 2^10, MiB for 2^20, GiB for 2^30, etc.) rather than the old KB, MB,
-and GB, which IEC now reserves for powers of 10 (10^3, 10^6, 10^9). Given that
-many readers of the code may not have made the conversion to add the 'i', do
-not use KB, MB, and GB for powers of 10 Instead, use e.g. "2*10^6 bytes"
-instead of 2MB to avoid confusion. Note that GiB is derived from the G in
-'Giga', the 'i' in binary, and the B in 'Byte'.
-
-### 4.1.4 Acronym Usage
-
-#### 4.1.4.1 The use of acronyms shall be limited.
-
-Please remember the golden rule: Code for the person who will have to read and
-maintain your code. Making up your own vocabulary to describe your module can
-lead to lots of confusion.
-
-#### 4.1.4.2 Created Acronyms must be fully defined.
-
-If you must create acronyms, they must be fully defined in the documentation
-
-##### 4.1.4.2.1 Translation tables are required for each module using a created acronym
-
-Each module that uses the acronym must contain a translation table comment in
-the file header. This definition is required so that others can understand your
-names and comments.
-
-#### 4.1.4.3 Industry-Standard Acronyms are allowed
-
-It's okay to use acronyms for industry standards.
-
-Acronyms such as Pci, Acpi, Smbios, Isa, (capitalized per the variable naming
-convention) are all legal to use without defining their meaning.
-
-If you reference an industry standard acronym, the file header must define to
-which version of the specification the code is written. Thus, a PCI resource
-manager would state that it was coded to follow the PCI 2.2 Specification and
-which optional features it included support for.
-
-#### 4.1.4.4 Capitalize Acronyms in comments and documentation to match their industry standard use.
-
-For example, use "PCI" in comments and documentation, and "Pci" for functions,
-files, etc.
-
-The table below lists the acronyms that are considered integral to the EDK II
-vernacular, and may be used without defining their meaning in a comment.
-
-###### Table 3 EFI Supported Acronyms
-
-| Acronyms | In an Identifier | Description                                        |
-| -------- | ---------------- | -------------------------------------------------- |
-| ACPI     | Acpi             | Advanced Configuration and Power Interface         |
-| AGP      | Agp              | Accelerated Graphics Port                          |
-| ANSI     | Ansi             | American National Standards Institute              |
-| ASCII    | Ascii            | American Standard Code for Information Interchange |
-| ATA      | Ata              | Advanced Technology Attachment                     |
-| ATAPI    | Atapi            | Advanced Technology Attachment Packet Interface    |
-| BFD      | Bfd              | Boot Flash Device                                  |
-| BIOS     | Bios             | Basic Input/Output System                          |
-| BIS      | Bis              | Boot Integrity Services                            |
-| CMOS     | Cmos             | Complementary metal oxide semiconductor            |
-| CPU      | Cpu              | Central processing unit                            |
-| CRC      | Crc              | Cyclic Redundancy Check                            |
-| DMA      | Dma              | Direct Memory Access                               |
-| DXE      | Dxe              | Driver Execution Environment                       |
-| EFI      | Efi              | Extensible Firmware Interface                      |
-| FD       | Fd               | Flash Device                                       |
-| FIFO     | Fifo             | First In First Out                                 |
-| FV       | Fv               | Firmware Volume                                    |
-| GUID     | Guid             | Globally Unique Identifier                         |
-| IEC      | Iec              | International Electrotechnical Commission          |
-| ISA      | Isa              | Industry Standard Architecture                     |
-| ISO      | Iso              | International Standards Organization               |
-| NVRAM    | Nvram            | Nonvolatile Random Access Memory                   |
-| PCI      | Pci              | Peripheral Component Interconnect                  |
-| PEI      | Pei              | Pre-EFI Initialization environment                 |
-| RAM      | Ram              | Random Access Memory                               |
-| ROM      | Rom              | Read-Only Memory                                   |
-| SRAM     | Sram             | Static Random Access Memory                        |
-| TPL      | Tpl              | Task Priority Level                                |
-| UEFI     | Uefi             | Unified Extensible Firmware Interface              |
-| UNDI     | Undi             | Universal Network Driver Interface                 |
-| USB      | Usb              | Universal Serial Bus                               |
-| VGA      | Vga              | Video graphics array                               |
+<!--- @file
+  4 Naming Conventions
+
+  Copyright (c) 2006-2017, Intel Corporation. All rights reserved.<BR>
+
+  Redistribution and use in source (original document form) and 'compiled'
+  forms (converted to PDF, epub, HTML and other formats) with or without
+  modification, are permitted provided that the following conditions are met:
+
+  1) Redistributions of source code (original document form) must retain the
+     above copyright notice, this list of conditions and the following
+     disclaimer as the first lines of this file unmodified.
+
+  2) Redistributions in compiled form (transformed to other DTDs, converted to
+     PDF, epub, HTML and other formats) must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+
+  THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
+  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+  EVENT SHALL TIANOCORE PROJECT  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
+  ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+-->
+
+# 4 Naming Conventions
+
+## 4.1 General Naming Rules
+
+**Use good naming practice when declaring variable names.**
+
+Studies show that programs with names averaging 10 to 16 characters are the
+easiest to debug. The name length is just a guideline_; the most important
+thing is that the name conveys a clear meaning of what it represents_.
+
+**Do not overload commonly used terms.**
+
+For example, EFI has an event model, so don't call some abstraction that you
+define an Event. People will get confused. Make sure someone reading the code
+can tell what you are talking about.
+
+**Each word or concept must start with a capital letter and be followed by
+lower-case letters.**
+
+The intent is for names to be consistent and easily readable. Each word in a
+compound name should be visually distinct.
+
+### 4.1.1 Identifiers that are always reserved
+
+**Identifiers beginning with an underscore are always reserved**
+
+Define them only in the special ways allowed elsewhere in this document.
+
+**Identifiers that are defined in the Standard C and POSIX libraries are always
+reserved.**
+
+This includes macros, typedefs, variables, and functions, whether with external
+linkage or file scope. The only exception is with modules that are mutually
+exclusive with these libraries. These reserved identifiers are listed in
+"Reserved Identifiers" and reserved keywords are listed in "Reserved Keywords".
+
+### 4.1.2 Common Opposites in Variable Names
+
+Use the correct opposites when declaring names.
+
+###### Table 1 Common Opposites
+
+|                       |                 |                  |
+| --------------------- | --------------- | ---------------- |
+| add / remove          | begin / end     | create / destroy |
+| increment / decrement | first / last    | get / release    |
+| lock / unlock         | put / get       | up / down        |
+| old / new             | min / max       | next / previous  |
+| source / destination  | open / close    | show / hide      |
+|                       | source / target | start / stop     |
+
+### 4.1.3 Abbreviation Usage
+
+#### 4.1.3.1 The use of abbreviations shall be regulated.
+
+This document describes a common set of abbreviations that can be freely used.
+If you must make up abbreviations, remember the name is most important to the
+reader of the code, not the writer.
+
+#### 4.1.3.2 New abbreviations must be documented in the header of each using file.
+
+Any abbreviation used, which is not documented in this specification, or in the
+_UEFI Specification_ shall be placed into a Glossary section of the File header
+as specified in "File Heading".
+
+Do not define a new abbreviation to replace an abbreviation that is already
+defined in this document. For example, do not define No to mean Number, because
+Num is the supported abbreviation.
+
+"EFI Supported Abbreviations" below lists the abbreviations that are
+standardized by this document and do not require a defining comment.
+
+###### Table 2 EFI Supported Abbreviations
+
+| Abbreviation | Description             |
+| ------------ | ----------------------- |
+| Ptr          | Pointer                 |
+| Str          | Unicode string          |
+| Ascii        | ASCII string            |
+| Len          | Length                  |
+| Arg          | Argument                |
+| Max          | Maximum                 |
+| Min          | Minimum                 |
+| Char         | Character               |
+| Num          | Number                  |
+| Temp         | Temporary               |
+| Src          | Source                  |
+| Dst          | Destination             |
+| BS           | EFI Boot Services Table |
+| RT           | EFI Runtime Table       |
+| ST           | EFI System Table        |
+| Tpl          | EFI Task Priority Level |
+
+#### 4.1.3.3 Powers of 2 and 10
+
+You are encouraged to use the IEC international abbreviations for powers of 2
+(KiB for 2^10, MiB for 2^20, GiB for 2^30, etc.) rather than the old KB, MB,
+and GB, which IEC now reserves for powers of 10 (10^3, 10^6, 10^9). Given that
+many readers of the code may not have made the conversion to add the 'i', do
+not use KB, MB, and GB for powers of 10 Instead, use e.g. "2*10^6 bytes"
+instead of 2MB to avoid confusion. Note that GiB is derived from the G in
+'Giga', the 'i' in binary, and the B in 'Byte'.
+
+### 4.1.4 Acronym Usage
+
+#### 4.1.4.1 The use of acronyms shall be limited.
+
+Please remember the golden rule: Code for the person who will have to read and
+maintain your code. Making up your own vocabulary to describe your module can
+lead to lots of confusion.
+
+#### 4.1.4.2 Created Acronyms must be fully defined.
+
+If you must create acronyms, they must be fully defined in the documentation
+
+##### 4.1.4.2.1 Translation tables are required for each module using a created acronym
+
+Each module that uses the acronym must contain a translation table comment in
+the file header. This definition is required so that others can understand your
+names and comments.
+
+#### 4.1.4.3 Industry-Standard Acronyms are allowed
+
+It's okay to use acronyms for industry standards.
+
+Acronyms such as Pci, Acpi, Smbios, Isa, (capitalized per the variable naming
+convention) are all legal to use without defining their meaning.
+
+If you reference an industry standard acronym, the file header must define to
+which version of the specification the code is written. Thus, a PCI resource
+manager would state that it was coded to follow the PCI 2.2 Specification and
+which optional features it included support for.
+
+#### 4.1.4.4 Capitalize Acronyms in comments and documentation to match their industry standard use.
+
+For example, use "PCI" in comments and documentation, and "Pci" for functions,
+files, etc.
+
+The table below lists the acronyms that are considered integral to the EDK II
+vernacular, and may be used without defining their meaning in a comment.
+
+###### Table 3 EFI Supported Acronyms
+
+| Acronyms | In an Identifier | Description                                        |
+| -------- | ---------------- | -------------------------------------------------- |
+| ACPI     | Acpi             | Advanced Configuration and Power Interface         |
+| AGP      | Agp              | Accelerated Graphics Port                          |
+| ANSI     | Ansi             | American National Standards Institute              |
+| ASCII    | Ascii            | American Standard Code for Information Interchange |
+| ATA      | Ata              | Advanced Technology Attachment                     |
+| ATAPI    | Atapi            | Advanced Technology Attachment Packet Interface    |
+| BFD      | Bfd              | Boot Flash Device                                  |
+| BIOS     | Bios             | Basic Input/Output System                          |
+| BIS      | Bis              | Boot Integrity Services                            |
+| CMOS     | Cmos             | Complementary metal oxide semiconductor            |
+| CPU      | Cpu              | Central processing unit                            |
+| CRC      | Crc              | Cyclic Redundancy Check                            |
+| DMA      | Dma              | Direct Memory Access                               |
+| DXE      | Dxe              | Driver Execution Environment                       |
+| EFI      | Efi              | Extensible Firmware Interface                      |
+| FD       | Fd               | Flash Device                                       |
+| FIFO     | Fifo             | First In First Out                                 |
+| FV       | Fv               | Firmware Volume                                    |
+| GUID     | Guid             | Globally Unique Identifier                         |
+| IEC      | Iec              | International Electrotechnical Commission          |
+| ISA      | Isa              | Industry Standard Architecture                     |
+| ISO      | Iso              | International Standards Organization               |
+| NVRAM    | Nvram            | Nonvolatile Random Access Memory                   |
+| PCI      | Pci              | Peripheral Component Interconnect                  |
+| PEI      | Pei              | Pre-EFI Initialization environment                 |
+| RAM      | Ram              | Random Access Memory                               |
+| ROM      | Rom              | Read-Only Memory                                   |
+| SRAM     | Sram             | Static Random Access Memory                        |
+| TPL      | Tpl              | Task Priority Level                                |
+| UEFI     | Uefi             | Unified Extensible Firmware Interface              |
+| UNDI     | Undi             | Universal Network Driver Interface                 |
+| USB      | Usb              | Universal Serial Bus                               |
+| VGA      | Vga              | Video graphics array                               |
-- 
Guid("CE165669-3EF3-493F-B85D-6190EE5B9759")

[edk2-CCodingStandardsSpecification PATCH 5/5] Fix Chapter 5 Typos

[evan.lloyd]

From: Evan Lloyd <evan.lloyd@arm.com>

5.1.1 - Replace "less" with "fewer" (because columns is plural and
        countable)
5.1.5 - Correct tense.  (because the C specification still defines...)
        Insert full stop.
        Insert comma.
5.1.8 - Correct "provided" to "proven".
5.1.9 - remove hanging "This."
5.2.3.1 - replace "is comprised of" with "comprises" (comprise means
          "consists of", so "comprised of" is a solecism.
          Remove use of tab, as they are forbidden.
          Remove -- before date in copyright header (None of the edk2
          files have it).
5.4 - Add indent to comment text.
5.6.1.2 - Fix copy/paste text (from UEFI spec).

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
---
 5_source_files/52_spacing.md                |  9 +++++----
 5_source_files/54_code_file_structure.md    |  4 ++--
 5_source_files/56_declarations_and_types.md |  4 ++--
 5_source_files/README.md                    | 18 +++++++++---------
 4 files changed, 18 insertions(+), 17 deletions(-)

diff --git a/5_source_files/52_spacing.md b/5_source_files/52_spacing.md
index ddeabf7753a8713bf04e143d6e2e9bccf881f691..3c79f4e4ee91bcd4035d6cf7d8d32f1bb9c7756f 100644
--- a/5_source_files/52_spacing.md
+++ b/5_source_files/52_spacing.md
@@ -249,7 +249,7 @@ And the comment will end with:
 **/
 ```
 
-The File Heading comment block is comprised of the following sections: File
+The File Heading comment block comprises the following sections: File
 Description, Copyright, License, and the optional Specification Reference and
 Glossary sections.
 
@@ -266,8 +266,9 @@ Glossary sections.
 **/
 ```
 
-The following example begins each body line with a tab (two spaces). This is
-the preferred indentation, but two tabs (four spaces) is also acceptable.
+The following example begins each body line with an indent (two spaces).
+This is the preferred indentation, but a double indent (four spaces) is also
+acceptable.
 
 #### Example
 
@@ -278,7 +279,7 @@ the preferred indentation, but two tabs (four spaces) is also acceptable.
   Detailed description of the file’s contents and other useful
   information for a person viewing the file for the first time.
 
-  Copyright (C) --20XX, Acme Corporation. All rights reserved.<BR>
+  Copyright (C) 20XX, Acme Corporation. All rights reserved.<BR>
   This program and the accompanying materials
   are licensed and made available under the terms and conditions of
   the BSD License which accompanies this distribution. The full
diff --git a/5_source_files/54_code_file_structure.md b/5_source_files/54_code_file_structure.md
index 8cc9f4f61412b07f765d80d7b680c6dd38b838c1..ac999aae99ae9cfd8b6f97dc483e51bfbd7c7a0b 100644
--- a/5_source_files/54_code_file_structure.md
+++ b/5_source_files/54_code_file_structure.md
@@ -68,8 +68,8 @@ these are C files with an extension of "`.c`".
 
 /* Function Definitions */
 
-/* If this is a protocol definition, the
-protocol structure is defined and initialized here.
+/* If this is a protocol definition, the protocol structure is defined and
+  initialized here.
 */
 ```
 
diff --git a/5_source_files/56_declarations_and_types.md b/5_source_files/56_declarations_and_types.md
index ec1803d980e1fa808b9dc515cdffbc4b47437435..5c57834fe1195b5487f0f59e8a0385e44d91aff4 100644
--- a/5_source_files/56_declarations_and_types.md
+++ b/5_source_files/56_declarations_and_types.md
@@ -43,9 +43,9 @@ or from common EFI data types.
 The corresponding EFI types must be used instead.
 
 "EFI Data Types" below contains the common data types that are referenced in
-the interface definitions defined by this specification. Per the _UEFI
-Specification_, version 2.3.1:
+the interface definitions defined by the UEFI specification.
 
+Per the _UEFI Specification_, version 2.3.1:
 "Unless otherwise specified, all data types are naturally aligned. Structures
 are aligned on boundaries equal to the largest internal datum of the structure,
 and internal data is implicitly padded to achieve natural alignment."
diff --git a/5_source_files/README.md b/5_source_files/README.md
index a93492db4f0f17e14d9c2c3c95e57cf0f6cc911e..a443148138f2abaf6b9131f4758858a4a5f45fd3 100644
--- a/5_source_files/README.md
+++ b/5_source_files/README.md
@@ -33,9 +33,9 @@
 
 ## 5.1 General Rules
 
-### 5.1.1 Lines shall be 120 columns, or less
+### 5.1.1 Lines shall be 120 columns, or fewer
 
-Preferably, limit line lengths to 80 columns or less. When this doesn't leave
+Preferably, limit line lengths to 80 columns or fewer. When this doesn't leave
 sufficient space for a good postfix style comment, extend the line to a total
 of 120 columns. Having some level of uniformity in the expected width of the
 source is useful for viewing and printing the code.
@@ -79,9 +79,9 @@ Other than '\0', the only permissible escape sequences are:
 
 ### 5.1.5 Octal constants (Base 8) shall not be used.
 
-The C language specification has defined numbers whose first digit is zero as
-octal, so 010 is decimal 8 The use of octal has declined considerably since C
-was first defined but this construct remains for backwards compatibility. Its
+The C language specification defines numbers whose first digit is zero as
+octal, so 010 is decimal 8. The use of octal has declined considerably since C
+was first defined, but this construct remains for backwards compatibility. Its
 use is prohibited. In particular, do not be tempted to use the zero prefix in
 tables of numbers to ensure visual alignment:
 
@@ -107,16 +107,16 @@ Trigraphs are a construct to allow character representations that do not
 support all ASCII characters to enter the equivalent of the ASCII character.
 Trigraphs are three characters long (hence the "tri"). The first two characters
 are "??" while the third character disambiguates the trigraph. Technically
-therefore, a[5] could be written a??(5??). Trigraphs have provided both
+therefore, a[5] could be written a??(5??). Trigraphs have proven both
 confusing and unnecessary and are prohibited.
 
 ### 5.1.9 In-line assembler shall not be used
 
 There are really no reasons for in-line assembler to be used in EDK II code.
 The only exceptions in this case are largely associated with the lowest level
-Architectural Protocols. Using in-line assembly language deviates against the
-Scope rules defined in Section 1.3 "Scope" because it is an extension to
-standard C. This.
+Architectural Protocols. Using in-line assembly language deviates from the
+Scope rules defined in Section 1.3 "Scope", because it is an extension to
+standard C.
 
 ### 5.1.10 Do not use #pragma, except for #pragma pack (#).
 
-- 
Guid("CE165669-3EF3-493F-B85D-6190EE5B9759")

Re: [edk2-CCodingStandardsSpecification PATCH 1/5] Fix Chapter 1 Typos

[Laszlo Ersek]

On 01/03/18 12:22, evan.lloyd@arm.com wrote:
> From: Evan Lloyd <evan.lloyd@arm.com>
> 
>     1.1 Abstract - replace "then" with "can" (to make meaningful)
>     1.2 Rationale - change
>           "commit to conforming to standards of this specification"
>       to   commit to conforming with the standards of this specification
>     1.3 Scope - add missing "to" in "an attempt make you aware of your
>       actions"
> 
> Contributed-under: TianoCore Contribution Agreement 1.1
> Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
> ---
>  1_introduction.md | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/1_introduction.md b/1_introduction.md
> index c22c04c9f76d2352e4f294c0e70f5ebf787f7054..5471a6bf5e94df6dd0c5fd0a4b5020c77d1f8ca0 100644
> --- a/1_introduction.md
> +++ b/1_introduction.md
> @@ -62,7 +62,7 @@ This specification addresses the chronic problem of providing accurate
>  documentation of the code base by embedding the documentation within the code.
>  While this does not guarantee that the documentation will be kept up to date,
>  it significantly increases the chances. A document generation system, Doxygen,
> -then produce formatted documentation by extracting information from specially
> +can produce formatted documentation by extracting information from specially
>  formatted comment blocks and the syntactic elements of the code.
>  
>  This specification presents protocol standards that will ensure that the
> @@ -97,10 +97,10 @@ wide support. On the downside in that each developer's C code could
>  lack of uniformity makes understanding and maintaining the code very difficult.
>  
>  Uniformity is the key theme of these rules. You may disagree with some of our
> -decisions. Nevertheless, we ask that you commit to conforming to standards of
> -this specification. Also, there are pitfalls inherent in the C language that
> -this style guide may help you to avoid. The goal of this document is making
> -you, and those who follow you, more productive.
> +decisions. Nevertheless, we ask that you commit to conforming with the
> +standards of this specification. Also, there are pitfalls inherent in the C
> +language that this style guide may help you to avoid. The goal of this document
> +is making you, and those who follow you, more productive.
>  
>  Some of the strict rules for protocol and driver construction may seem overly
>  onerous. Don't panic - there is a method to our madness - we intend to

OK, a risky observation from non-native speaker to native speaker:

To my knowledge, it's "conform to", not "conform with". Thus, an update
to this paragraph looks unnecessary to me, but I'm more than prepared to
be corrected :)

(Also, I'd replace "help you to avoid" with "help you avoid", i.e. drop
the "to". But, that's a separate thing, and the same caveat about being
a non-native speaker applies :) )

Looks fine to me otherwise.

Thanks!
Laszlo

> @@ -161,7 +161,7 @@ Topics covered in this coding standard include:
>  * Commenting rules
>  * Doxygen
>  
> -These guidelines represent an attempt make you aware of your actions, because
> +These guidelines represent an attempt to make you aware of your actions, because
>  those actions affect the future readers and maintainers of the code you produce.
>  
>  Pre-existing code ported to the EDK II environment does not have to conform to
> 

Re: [edk2-CCodingStandardsSpecification PATCH 2/5] Fix Chapter 2 Typos

[Laszlo Ersek]

On 01/03/18 12:22, evan.lloyd@arm.com wrote:
> From: Evan Lloyd <evan.lloyd@arm.com>
> 
> 2.1 Accessibility - remove erroneous "as"
> 2.1 Confirmation - insert missing full stop
> 2.1 Forgiveness - excise superfluous "errors"
> 2.1 Standard techniques - remove redundant "be to"
> 
> Contributed-under: TianoCore Contribution Agreement 1.1
> Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
> ---
>  2_guiding_principles.md | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/2_guiding_principles.md b/2_guiding_principles.md
> index a7759f27dcf71a948b903332c9bc14946e445cd8..5a51225b65dec2159a4fb94481920666c0d042ff 100644
> --- a/2_guiding_principles.md
> +++ b/2_guiding_principles.md
> @@ -47,7 +47,7 @@ The following is an alphabetical list of software design principles:
>  **Accessibility**
>  
>  This entails designing objects and environments to be usable, with no
> -modification, by the greatest number of people as possible, including people
> +modification, by the greatest number of people possible, including people
>  with varying educational and social backgrounds, as well as those with motor or
>  sensory challenges.
>  
> @@ -68,7 +68,7 @@ shortterm memory, as well as to accommodate its limits.
>  This is a technique used for critical actions, inputs, or commands.
>  Confirmations are primarily used to prevent unintended actions. Minimize errors
>  in critical or irreversible operations with confirmations. If you overuse
> -confirmations, expect that they will be ignored Avoid overusing confirmations
> +confirmations, expect that they will be ignored. Avoid overusing confirmations
>  to ensure that they remain unexpected and uncommon; otherwise, they may be
>  ignored. Use a two-step operation for hardware confirmations and dialogs for
>  software confirmations.
> @@ -97,7 +97,7 @@ about the assumptions you make.
>  **Forgiveness**
>  
>  Design to help users avoid errors and reduce the negative consequences of
> -errors any errors made. Recommended methods for achieving design forgiveness
> +any errors made. Recommended methods for achieving design forgiveness
>  include affordances, reversibility of actions, and safety nets. Effectively
>  designing for forgiveness results in a design needing minimal confirmations,
>  warnings, and help.
> @@ -171,7 +171,7 @@ classes of platforms from embedded systems to massively parallel computers.
>  
>  Greater reliance on unique or exotic pieces makes a system harder to
>  understand, and more intimidating for someone trying to understand it the first
> -time. Using standardized, common approaches should be to give the whole system
> +time. Using standardized, common approaches should give the whole system
>  a familiar feeling. This standardization is one of the primary goals of this
>  document.
>  
> 


Reviewed-by: Laszlo Ersek <lersek@redhat.com>

Re: [edk2-CCodingStandardsSpecification PATCH 3/5] Fix Chapter 3 Typos

[Laszlo Ersek]

On 01/03/18 12:22, evan.lloyd@arm.com wrote:
> From: Evan Lloyd <evan.lloyd@arm.com>
> 
> 3_quick_reference.md has some obviously invalid extra characters at the
> end of line 55 ( ",).  This patch removes them.
> 
> Contributed-under: TianoCore Contribution Agreement 1.1
> Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
> ---
>  3_quick_reference.md | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/3_quick_reference.md b/3_quick_reference.md
> index 13045d297b3be848d91f9be05380454b4cc2fe91..9367e422fb0337007409d6597913cb43da92e0c5 100644
> --- a/3_quick_reference.md
> +++ b/3_quick_reference.md
> @@ -55,7 +55,7 @@
>    any file using the abbreviation or acronym. See "Abbreviation Usage" and
>    "Glossary".
>  
> -* There is no limit to name lengths. A length of 10 to 30 characters is ",
> +* There is no limit to name lengths. A length of 10 to 30 characters is
>    recommended. See "File Names" & "Identifiers that are always reserved".
>  
>  * File names must not start with numbers. See "File Names".
> 

Reviewed-by: Laszlo Ersek <lersek@redhat.com>

Re: [edk2-CCodingStandardsSpecification PATCH 4/5] Fix Chapter 4 Typo

[Laszlo Ersek]

On 01/03/18 12:22, evan.lloyd@arm.com wrote:
> From: Evan Lloyd <evan.lloyd@arm.com>
> 
> 4.1.3.2 - remove "See" from 'as specified in See "File Heading"'
> 
> Contributed-under: TianoCore Contribution Agreement 1.1
> Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
> ---
>  4_naming_conventions/README.md | 418 ++++++++++----------
>  1 file changed, 209 insertions(+), 209 deletions(-)

Looks like this file underwent a line terminator conversion as well.

If the file is currently not using CRLF, then I agree it should be
converted; however, the conversion should be please separated from the
typo fix.

... Hmm, the file already seems to use CRLF. So I think the conversion
was to LF, and must have been unintended.

Can you please resubmit without the line terminator changes?

Thanks!
Laszlo

Re: [edk2-CCodingStandardsSpecification PATCH 5/5] Fix Chapter 5 Typos

[Laszlo Ersek]

On 01/03/18 12:22, evan.lloyd@arm.com wrote:
> From: Evan Lloyd <evan.lloyd@arm.com>
> 
> 5.1.1 - Replace "less" with "fewer" (because columns is plural and
>         countable)
> 5.1.5 - Correct tense.  (because the C specification still defines...)
>         Insert full stop.
>         Insert comma.
> 5.1.8 - Correct "provided" to "proven".
> 5.1.9 - remove hanging "This."
> 5.2.3.1 - replace "is comprised of" with "comprises" (comprise means
>           "consists of", so "comprised of" is a solecism.
>           Remove use of tab, as they are forbidden.
>           Remove -- before date in copyright header (None of the edk2
>           files have it).
> 5.4 - Add indent to comment text.
> 5.6.1.2 - Fix copy/paste text (from UEFI spec).
> 
> Contributed-under: TianoCore Contribution Agreement 1.1
> Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
> ---
>  5_source_files/52_spacing.md                |  9 +++++----
>  5_source_files/54_code_file_structure.md    |  4 ++--
>  5_source_files/56_declarations_and_types.md |  4 ++--
>  5_source_files/README.md                    | 18 +++++++++---------
>  4 files changed, 18 insertions(+), 17 deletions(-)
> 
> diff --git a/5_source_files/52_spacing.md b/5_source_files/52_spacing.md
> index ddeabf7753a8713bf04e143d6e2e9bccf881f691..3c79f4e4ee91bcd4035d6cf7d8d32f1bb9c7756f 100644
> --- a/5_source_files/52_spacing.md
> +++ b/5_source_files/52_spacing.md
> @@ -249,7 +249,7 @@ And the comment will end with:
>  **/
>  ```
>  
> -The File Heading comment block is comprised of the following sections: File
> +The File Heading comment block comprises the following sections: File
>  Description, Copyright, License, and the optional Specification Reference and
>  Glossary sections.
>  
> @@ -266,8 +266,9 @@ Glossary sections.
>  **/
>  ```
>  
> -The following example begins each body line with a tab (two spaces). This is
> -the preferred indentation, but two tabs (four spaces) is also acceptable.
> +The following example begins each body line with an indent (two spaces).
> +This is the preferred indentation, but a double indent (four spaces) is also
> +acceptable.
>  
>  #### Example
>  
> @@ -278,7 +279,7 @@ the preferred indentation, but two tabs (four spaces) is also acceptable.
>    Detailed description of the file’s contents and other useful
>    information for a person viewing the file for the first time.
>  
> -  Copyright (C) --20XX, Acme Corporation. All rights reserved.<BR>
> +  Copyright (C) 20XX, Acme Corporation. All rights reserved.<BR>
>    This program and the accompanying materials
>    are licensed and made available under the terms and conditions of
>    the BSD License which accompanies this distribution. The full
> diff --git a/5_source_files/54_code_file_structure.md b/5_source_files/54_code_file_structure.md
> index 8cc9f4f61412b07f765d80d7b680c6dd38b838c1..ac999aae99ae9cfd8b6f97dc483e51bfbd7c7a0b 100644
> --- a/5_source_files/54_code_file_structure.md
> +++ b/5_source_files/54_code_file_structure.md
> @@ -68,8 +68,8 @@ these are C files with an extension of "`.c`".
>  
>  /* Function Definitions */
>  
> -/* If this is a protocol definition, the
> -protocol structure is defined and initialized here.
> +/* If this is a protocol definition, the protocol structure is defined and
> +  initialized here.
>  */
>  ```

So, I'm a bit hesitant about this. In edk2 we use /* comments */ (to my
knowledge, that is) only when they have to be embedded in replacement
texts of function-like macros, or in expressions that continue after the
comment on the same line. IOW, multi-line /* comments */ are mostly
unused, and I'm unsure if we should prepend a "*" to "initialized here".

On the other hand, the comments in this section look like they should be
fully replaced by actual code. In that sense the comment style we use
here does not matter.


>  
> diff --git a/5_source_files/56_declarations_and_types.md b/5_source_files/56_declarations_and_types.md
> index ec1803d980e1fa808b9dc515cdffbc4b47437435..5c57834fe1195b5487f0f59e8a0385e44d91aff4 100644
> --- a/5_source_files/56_declarations_and_types.md
> +++ b/5_source_files/56_declarations_and_types.md
> @@ -43,9 +43,9 @@ or from common EFI data types.
>  The corresponding EFI types must be used instead.
>  
>  "EFI Data Types" below contains the common data types that are referenced in
> -the interface definitions defined by this specification. Per the _UEFI
> -Specification_, version 2.3.1:
> +the interface definitions defined by the UEFI specification.
>  
> +Per the _UEFI Specification_, version 2.3.1:
>  "Unless otherwise specified, all data types are naturally aligned. Structures
>  are aligned on boundaries equal to the largest internal datum of the structure,
>  and internal data is implicitly padded to achieve natural alignment."
> diff --git a/5_source_files/README.md b/5_source_files/README.md
> index a93492db4f0f17e14d9c2c3c95e57cf0f6cc911e..a443148138f2abaf6b9131f4758858a4a5f45fd3 100644
> --- a/5_source_files/README.md
> +++ b/5_source_files/README.md
> @@ -33,9 +33,9 @@
>  
>  ## 5.1 General Rules
>  
> -### 5.1.1 Lines shall be 120 columns, or less
> +### 5.1.1 Lines shall be 120 columns, or fewer
>  
> -Preferably, limit line lengths to 80 columns or less. When this doesn't leave
> +Preferably, limit line lengths to 80 columns or fewer. When this doesn't leave
>  sufficient space for a good postfix style comment, extend the line to a total
>  of 120 columns. Having some level of uniformity in the expected width of the
>  source is useful for viewing and printing the code.
> @@ -79,9 +79,9 @@ Other than '\0', the only permissible escape sequences are:
>  
>  ### 5.1.5 Octal constants (Base 8) shall not be used.
>  
> -The C language specification has defined numbers whose first digit is zero as
> -octal, so 010 is decimal 8 The use of octal has declined considerably since C
> -was first defined but this construct remains for backwards compatibility. Its
> +The C language specification defines numbers whose first digit is zero as
> +octal, so 010 is decimal 8. The use of octal has declined considerably since C
> +was first defined, but this construct remains for backwards compatibility. Its
>  use is prohibited. In particular, do not be tempted to use the zero prefix in
>  tables of numbers to ensure visual alignment:
>  
> @@ -107,16 +107,16 @@ Trigraphs are a construct to allow character representations that do not
>  support all ASCII characters to enter the equivalent of the ASCII character.
>  Trigraphs are three characters long (hence the "tri"). The first two characters
>  are "??" while the third character disambiguates the trigraph. Technically
> -therefore, a[5] could be written a??(5??). Trigraphs have provided both
> +therefore, a[5] could be written a??(5??). Trigraphs have proven both
>  confusing and unnecessary and are prohibited.

"Provided" is certainly a typo and "proven" is right, but would "proved"
be even better in this context?

https://en.wiktionary.org/wiki/prove#Usage_notes

Looks fine to me otherwise.

Thanks!
Laszlo

>  
>  ### 5.1.9 In-line assembler shall not be used
>  
>  There are really no reasons for in-line assembler to be used in EDK II code.
>  The only exceptions in this case are largely associated with the lowest level
> -Architectural Protocols. Using in-line assembly language deviates against the
> -Scope rules defined in Section 1.3 "Scope" because it is an extension to
> -standard C. This.
> +Architectural Protocols. Using in-line assembly language deviates from the
> +Scope rules defined in Section 1.3 "Scope", because it is an extension to
> +standard C.
>  
>  ### 5.1.10 Do not use #pragma, except for #pragma pack (#).
>  
> 

Re: [edk2-CCodingStandardsSpecification PATCH 1/5] Fix Chapter 1 Typos

[Evan Lloyd]

Hi Laszlo

> -----Original Message-----
> From: Laszlo Ersek [mailto:lersek@redhat.com]
> Sent: 03 January 2018 16:51
> To: Evan Lloyd <Evan.Lloyd@arm.com>; edk2-devel@lists.01.org
> Cc: "ard.biesheuvel@linaro.org"@arm.com;
> "leif.lindholm@linaro.org"@arm.com;
> "Matteo.Carlini@arm.com"@arm.com; "lersek@redhat.com"@arm.com;
> "liming.gao@intel.com"@arm.com;
> "michael.d.kinney@intel.com"@arm.com;
> "jordan.l.justen@intel.com"@arm.com; "nd@arm.com"@arm.com
> Subject: Re: [edk2-CCodingStandardsSpecification PATCH 1/5] Fix Chapter 1
> Typos
>
> On 01/03/18 12:22, evan.lloyd@arm.com wrote:
> > From: Evan Lloyd <evan.lloyd@arm.com>
> >
> >     1.1 Abstract - replace "then" with "can" (to make meaningful)
> >     1.2 Rationale - change
> >           "commit to conforming to standards of this specification"
> >       to   commit to conforming with the standards of this specification
> >     1.3 Scope - add missing "to" in "an attempt make you aware of your
> >       actions"
> >
> > Contributed-under: TianoCore Contribution Agreement 1.1
> > Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
> > ---
> >  1_introduction.md | 12 ++++++------
> >  1 file changed, 6 insertions(+), 6 deletions(-)
> >
> > diff --git a/1_introduction.md b/1_introduction.md index
> >
> c22c04c9f76d2352e4f294c0e70f5ebf787f7054..5471a6bf5e94df6dd0c5fd0
> a4b50
> > 20c77d1f8ca0 100644
> > --- a/1_introduction.md
> > +++ b/1_introduction.md
> > @@ -62,7 +62,7 @@ This specification addresses the chronic problem of
> > providing accurate  documentation of the code base by embedding the
> documentation within the code.
> >  While this does not guarantee that the documentation will be kept up
> > to date,  it significantly increases the chances. A document
> > generation system, Doxygen, -then produce formatted documentation by
> > extracting information from specially
> > +can produce formatted documentation by extracting information from
> > +specially
> >  formatted comment blocks and the syntactic elements of the code.
> >
> >  This specification presents protocol standards that will ensure that
> > the @@ -97,10 +97,10 @@ wide support. On the downside in that each
> > developer's C code could  lack of uniformity makes understanding and
> maintaining the code very difficult.
> >
> >  Uniformity is the key theme of these rules. You may disagree with
> > some of our -decisions. Nevertheless, we ask that you commit to
> > conforming to standards of -this specification. Also, there are
> > pitfalls inherent in the C language that -this style guide may help
> > you to avoid. The goal of this document is making -you, and those who
> follow you, more productive.
> > +decisions. Nevertheless, we ask that you commit to conforming with
> > +the standards of this specification. Also, there are pitfalls
> > +inherent in the C language that this style guide may help you to
> > +avoid. The goal of this document is making you, and those who follow
> you, more productive.
> >
> >  Some of the strict rules for protocol and driver construction may
> > seem overly  onerous. Don't panic - there is a method to our madness -
> > we intend to
>
> OK, a risky observation from non-native speaker to native speaker:

 [[Evan Lloyd]] To avoid false appearances, I'm not English either, so feel free.

>
> To my knowledge, it's "conform to", not "conform with". Thus, an update to
> this paragraph looks unnecessary to me, but I'm more than prepared to be
> corrected :)
[[Evan Lloyd]]  You are correct, conform to is usual, but I think it is equally correct usage to conform 'with' a request, or regulation.
I changed it because "to conform to" has too many "to"s

>
> (Also, I'd replace "help you to avoid" with "help you avoid", i.e. drop the
> "to". But, that's a separate thing, and the same caveat about being a non-
> native speaker applies :) )

 [[Evan Lloyd]] I agree, your version is better.

>
> Looks fine to me otherwise.
>
> Thanks!
> Laszlo
>
> > @@ -161,7 +161,7 @@ Topics covered in this coding standard include:
> >  * Commenting rules
> >  * Doxygen
> >
> > -These guidelines represent an attempt make you aware of your actions,
> > because
> > +These guidelines represent an attempt to make you aware of your
> > +actions, because
> >  those actions affect the future readers and maintainers of the code you
> produce.
> >
> >  Pre-existing code ported to the EDK II environment does not have to
> > conform to
> >

IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

Re: [edk2-CCodingStandardsSpecification PATCH 5/5] Fix Chapter 5 Typos

[Evan Lloyd]

> -----Original Message-----
> From: Laszlo Ersek [mailto:lersek@redhat.com]
> Sent: 03 January 2018 17:08
> To: Evan Lloyd <Evan.Lloyd@arm.com>; edk2-devel@lists.01.org
> Cc: "ard.biesheuvel@linaro.org"@arm.com;
> "leif.lindholm@linaro.org"@arm.com;
> "Matteo.Carlini@arm.com"@arm.com; "lersek@redhat.com"@arm.com;
> "liming.gao@intel.com"@arm.com;
> "michael.d.kinney@intel.com"@arm.com;
> "jordan.l.justen@intel.com"@arm.com; "nd@arm.com"@arm.com
> Subject: Re: [edk2-CCodingStandardsSpecification PATCH 5/5] Fix Chapter 5
> Typos
>
> On 01/03/18 12:22, evan.lloyd@arm.com wrote:
> > From: Evan Lloyd <evan.lloyd@arm.com>
> >
> > 5.1.1 - Replace "less" with "fewer" (because columns is plural and
> >         countable)
> > 5.1.5 - Correct tense.  (because the C specification still defines...)
> >         Insert full stop.
> >         Insert comma.
> > 5.1.8 - Correct "provided" to "proven".
> > 5.1.9 - remove hanging "This."
> > 5.2.3.1 - replace "is comprised of" with "comprises" (comprise means
> >           "consists of", so "comprised of" is a solecism.
> >           Remove use of tab, as they are forbidden.
> >           Remove -- before date in copyright header (None of the edk2
> >           files have it).
> > 5.4 - Add indent to comment text.
> > 5.6.1.2 - Fix copy/paste text (from UEFI spec).
> >
> > Contributed-under: TianoCore Contribution Agreement 1.1
> > Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
> > ---
> >  5_source_files/52_spacing.md                |  9 +++++----
> >  5_source_files/54_code_file_structure.md    |  4 ++--
> >  5_source_files/56_declarations_and_types.md |  4 ++--
> >  5_source_files/README.md                    | 18 +++++++++---------
> >  4 files changed, 18 insertions(+), 17 deletions(-)
> >
> > diff --git a/5_source_files/52_spacing.md
> > b/5_source_files/52_spacing.md index
> >
> ddeabf7753a8713bf04e143d6e2e9bccf881f691..3c79f4e4ee91bcd4035d6c
> f7d8d3
> > 2f1bb9c7756f 100644
> > --- a/5_source_files/52_spacing.md
> > +++ b/5_source_files/52_spacing.md
> > @@ -249,7 +249,7 @@ And the comment will end with:
> >  **/
> >  ```
> >
> > -The File Heading comment block is comprised of the following
> > sections: File
> > +The File Heading comment block comprises the following sections: File
> >  Description, Copyright, License, and the optional Specification
> > Reference and  Glossary sections.
> >
> > @@ -266,8 +266,9 @@ Glossary sections.
> >  **/
> >  ```
> >
> > -The following example begins each body line with a tab (two spaces).
> > This is -the preferred indentation, but two tabs (four spaces) is also
> acceptable.
> > +The following example begins each body line with an indent (two spaces).
> > +This is the preferred indentation, but a double indent (four spaces)
> > +is also acceptable.
> >
> >  #### Example
> >
> > @@ -278,7 +279,7 @@ the preferred indentation, but two tabs (four
> spaces) is also acceptable.
> >    Detailed description of the file’s contents and other useful
> >    information for a person viewing the file for the first time.
> >
> > -  Copyright (C) --20XX, Acme Corporation. All rights reserved.<BR>
> > +  Copyright (C) 20XX, Acme Corporation. All rights reserved.<BR>
> >    This program and the accompanying materials
> >    are licensed and made available under the terms and conditions of
> >    the BSD License which accompanies this distribution. The full diff
> > --git a/5_source_files/54_code_file_structure.md
> > b/5_source_files/54_code_file_structure.md
> > index
> >
> 8cc9f4f61412b07f765d80d7b680c6dd38b838c1..ac999aae99ae9cfd8b6f97
> dc483e
> > 51bfbd7c7a0b 100644
> > --- a/5_source_files/54_code_file_structure.md
> > +++ b/5_source_files/54_code_file_structure.md
> > @@ -68,8 +68,8 @@ these are C files with an extension of "`.c`".
> >
> >  /* Function Definitions */
> >
> > -/* If this is a protocol definition, the -protocol structure is
> > defined and initialized here.
> > +/* If this is a protocol definition, the protocol structure is
> > +defined and
> > +  initialized here.
> >  */
> >  ```
>
> So, I'm a bit hesitant about this. In edk2 we use /* comments */ (to my
> knowledge, that is) only when they have to be embedded in replacement
> texts of function-like macros, or in expressions that continue after the
> comment on the same line. IOW, multi-line /* comments */ are mostly
> unused, and I'm unsure if we should prepend a "*" to "initialized here".
>

 [[Evan Lloyd]] You are quite correct.  However, this patch only addresses typos in the existing document.
There are a number of inconsistencies in the comment formats used throughout, but they would need a patch with "actual" changes, not just typo corrections.

> On the other hand, the comments in this section look like they should be
> fully replaced by actual code. In that sense the comment style we use here
> does not matter.
>
>
> >
> > diff --git a/5_source_files/56_declarations_and_types.md
> > b/5_source_files/56_declarations_and_types.md
> > index
> >
> ec1803d980e1fa808b9dc515cdffbc4b47437435..5c57834fe1195b5487f0f5
> 9e8a03
> > 85e44d91aff4 100644
> > --- a/5_source_files/56_declarations_and_types.md
> > +++ b/5_source_files/56_declarations_and_types.md
> > @@ -43,9 +43,9 @@ or from common EFI data types.
> >  The corresponding EFI types must be used instead.
> >
> >  "EFI Data Types" below contains the common data types that are
> > referenced in -the interface definitions defined by this
> > specification. Per the _UEFI -Specification_, version 2.3.1:
> > +the interface definitions defined by the UEFI specification.
> >
> > +Per the _UEFI Specification_, version 2.3.1:
> >  "Unless otherwise specified, all data types are naturally aligned.
> > Structures  are aligned on boundaries equal to the largest internal
> > datum of the structure,  and internal data is implicitly padded to achieve
> natural alignment."
> > diff --git a/5_source_files/README.md b/5_source_files/README.md
> index
> >
> a93492db4f0f17e14d9c2c3c95e57cf0f6cc911e..a443148138f2abaf6b9131f
> 47588
> > 58a4a5f45fd3 100644
> > --- a/5_source_files/README.md
> > +++ b/5_source_files/README.md
> > @@ -33,9 +33,9 @@
> >
> >  ## 5.1 General Rules
> >
> > -### 5.1.1 Lines shall be 120 columns, or less
> > +### 5.1.1 Lines shall be 120 columns, or fewer
> >
> > -Preferably, limit line lengths to 80 columns or less. When this
> > doesn't leave
> > +Preferably, limit line lengths to 80 columns or fewer. When this
> > +doesn't leave
> >  sufficient space for a good postfix style comment, extend the line to
> > a total  of 120 columns. Having some level of uniformity in the
> > expected width of the  source is useful for viewing and printing the code.
> > @@ -79,9 +79,9 @@ Other than '\0', the only permissible escape
> sequences are:
> >
> >  ### 5.1.5 Octal constants (Base 8) shall not be used.
> >
> > -The C language specification has defined numbers whose first digit is
> > zero as -octal, so 010 is decimal 8 The use of octal has declined
> > considerably since C -was first defined but this construct remains for
> > backwards compatibility. Its
> > +The C language specification defines numbers whose first digit is
> > +zero as octal, so 010 is decimal 8. The use of octal has declined
> > +considerably since C was first defined, but this construct remains
> > +for backwards compatibility. Its
> >  use is prohibited. In particular, do not be tempted to use the zero
> > prefix in  tables of numbers to ensure visual alignment:
> >
> > @@ -107,16 +107,16 @@ Trigraphs are a construct to allow character
> > representations that do not  support all ASCII characters to enter the
> equivalent of the ASCII character.
> >  Trigraphs are three characters long (hence the "tri"). The first two
> > characters  are "??" while the third character disambiguates the
> > trigraph. Technically -therefore, a[5] could be written a??(5??).
> > Trigraphs have provided both
> > +therefore, a[5] could be written a??(5??). Trigraphs have proven both
> >  confusing and unnecessary and are prohibited.
>
> "Provided" is certainly a typo and "proven" is right, but would "proved"
> be even better in this context?

 [[Evan Lloyd]] The "Chicago Manual of Style" agrees with you.  (So do I.  My Scottish grandad wouldn't, but...)

>
> https://en.wiktionary.org/wiki/prove#Usage_notes

 [[Evan Lloyd]] This particular page looks sensible, but in general I'm very wary of using wiki's as an authority.  People may have a bee in their bonnet that they promote by biasing such pages.

>
> Looks fine to me otherwise.
>
> Thanks!
> Laszlo
>
> >
> >  ### 5.1.9 In-line assembler shall not be used
> >
> >  There are really no reasons for in-line assembler to be used in EDK II code.
> >  The only exceptions in this case are largely associated with the
> > lowest level -Architectural Protocols. Using in-line assembly language
> > deviates against the -Scope rules defined in Section 1.3 "Scope"
> > because it is an extension to -standard C. This.
> > +Architectural Protocols. Using in-line assembly language deviates
> > +from the Scope rules defined in Section 1.3 "Scope", because it is an
> > +extension to standard C.
> >
> >  ### 5.1.10 Do not use #pragma, except for #pragma pack (#).
> >
> >

IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

Re: [edk2-CCodingStandardsSpecification PATCH 4/5] Fix Chapter 4 Typo

[Evan Lloyd]

> -----Original Message-----
> From: Laszlo Ersek [mailto:lersek@redhat.com]
> Sent: 03 January 2018 16:56
> To: Evan Lloyd <Evan.Lloyd@arm.com>; edk2-devel@lists.01.org
> Cc: "ard.biesheuvel@linaro.org"@arm.com;
> "leif.lindholm@linaro.org"@arm.com;
> "Matteo.Carlini@arm.com"@arm.com; "lersek@redhat.com"@arm.com;
> "liming.gao@intel.com"@arm.com;
> "michael.d.kinney@intel.com"@arm.com;
> "jordan.l.justen@intel.com"@arm.com; "nd@arm.com"@arm.com
> Subject: Re: [edk2-CCodingStandardsSpecification PATCH 4/5] Fix Chapter 4
> Typo
>
> On 01/03/18 12:22, evan.lloyd@arm.com wrote:
> > From: Evan Lloyd <evan.lloyd@arm.com>
> >
> > 4.1.3.2 - remove "See" from 'as specified in See "File Heading"'
> >
> > Contributed-under: TianoCore Contribution Agreement 1.1
> > Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
> > ---
> >  4_naming_conventions/README.md | 418 ++++++++++----------
> >  1 file changed, 209 insertions(+), 209 deletions(-)
>
> Looks like this file underwent a line terminator conversion as well.
>
> If the file is currently not using CRLF, then I agree it should be converted;
> however, the conversion should be please separated from the typo fix.
>
> ... Hmm, the file already seems to use CRLF. So I think the conversion was to
> LF, and must have been unintended.

 [[Evan Lloyd]] It certainly was unintended, and seems to be an artefact of a core.autocrlf setting change.  Sorry.

>
> Can you please resubmit without the line terminator changes?
[[Evan Lloyd]] Will do.
>
> Thanks!
> Laszlo
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.