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

[Evan Lloyd <Evan.Lloyd@arm.com>]

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.