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")

_______________________________________________
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel

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 (#).
>  
> 

_______________________________________________
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel

> -----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.
_______________________________________________
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel