recipe whitespace style questions

recipe whitespace style questions

[Peter A. Bigot]

This maybe opens a can of worms, but:

A recent comment on a patch raised the issue of how to do whitespace 
indentation on multiple-line continuations: specifically, how many 
spaces should be used.  This is not addressed in the current style-guide 
and is something I've been confused about too.

I don't know that I particularly care which way it's done, but I would 
like guidance to help me be consistent for recipes I create.

Would a patch to update the style guide with clarifications be 
acceptable?  The intent of the proposed text below is to recommend:

SRC_URI = "file://skeleton \
            file://skeleton_test.c \
            file://COPYRIGHT \
            "

which should be displayed in a fixed-width font with the "file" words 
all aligned.

Next: I can find no documented recommendation in whether the closing 
quote is indented or not.  In addition to above (which in my display has 
the closing quote aligned with the letter 'f' of "file"; call this style 
"content aligned"), I've also seen:

SRC_URI = "file://skeleton \
            file://skeleton_test.c \
            file://COPYRIGHT \
           "

which I'll call "quote aligned", and:

SRC_URI = "file://skeleton \
            file://skeleton_test.c \
            file://COPYRIGHT \
"

which I'll call "none", and;

SRC_URI = "file://skeleton \
            file://skeleton_test.c \
            file://COPYRIGHT"

which I'll call "joined".

Again, for consistency's sake it would be nice to have a 
recommendation.  I personally prefer "none", which matches the closing 
bracket style for functions.

Next: I've also seen:

SRC_URI = " \
     file://skeleton \
     file://skeleton_test.c \
     file://COPYRIGHT \
"

which generalizes the Python 4-space indentation rule and is a nice 
option when the variable name is so long the content would go beyond 80 
characters if it appeared on the first line.

Finally, the use of tabs for shell functions is not preserved by 
meta-openembedded/contrib/oe-stylize.  Do any of the core developers 
recommend using that script, and if so does it need to be updated?  Do 
Yocto project coding standards apply to meta-openembedded?  And what 
about whitespace for multiple-line continuations within a shell 
function: one tab level?

If we can reach some level of consensus (or fiat) I'll prepare a patch 
for the style guide.  I think the following captures the proposed 
clarifications:

* Multiple-line continuations should be indented to the level of the 
content following the introductory quote symbol on the first line.

* Alternatively, the first line of a multi-line value may be continued 
after a single space following the introductory quote symbol and all 
subsequent content lines indented four spaces (or one tab if within a 
shell function)

*Any closing quote of a multiple-line continuation should be placed at 
the indentation level of the first continued line.

If you feel this is all too nit-picky just ignore it.

Peter

Re: recipe whitespace style questions

[Martin Jansa]

[-- Attachment #1: Type: text/plain, Size: 1062 bytes --]

On Wed, Aug 14, 2013 at 08:51:40AM -0500, Peter A. Bigot wrote:
> 
> SRC_URI = "file://skeleton \
>             file://skeleton_test.c \
>             file://COPYRIGHT \
> "
> 
> which I'll call "none", and;
> 
> SRC_URI = "file://skeleton \
>             file://skeleton_test.c \
>             file://COPYRIGHT"
> 
> which I'll call "joined".
> 
> Again, for consistency's sake it would be nice to have a 
> recommendation.  I personally prefer "none", which matches the closing 
> bracket style for functions.
> 
> Next: I've also seen:
> 
> SRC_URI = " \
>      file://skeleton \
>      file://skeleton_test.c \
>      file://COPYRIGHT \
> "

I prefer this one (especially for longer variables or entries) or "none",
because with "none" it's easier to see where multiline variable ends.

Worst is IMHO "joined" because when appending one more line you have to
edit 2 lines to move '"' so the diff for review is longer and harder to
read than just one added line.

-- 
Martin 'JaMa' Jansa     jabber: Martin.Jansa@gmail.com

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 205 bytes --]

Re: recipe whitespace style questions

[Chris Larson]

[-- Attachment #1: Type: text/plain, Size: 1190 bytes --]

On Wed, Aug 14, 2013 at 7:13 AM, Martin Jansa <martin.jansa@gmail.com>wrote:

> On Wed, Aug 14, 2013 at 08:51:40AM -0500, Peter A. Bigot wrote:
> >
> > SRC_URI = "file://skeleton \
> >             file://skeleton_test.c \
> >             file://COPYRIGHT \
> > "
> >
> > which I'll call "none", and;
> >
> > SRC_URI = "file://skeleton \
> >             file://skeleton_test.c \
> >             file://COPYRIGHT"
> >
> > which I'll call "joined".
> >
> > Again, for consistency's sake it would be nice to have a
> > recommendation.  I personally prefer "none", which matches the closing
> > bracket style for functions.
> >
> > Next: I've also seen:
> >
> > SRC_URI = " \
> >      file://skeleton \
> >      file://skeleton_test.c \
> >      file://COPYRIGHT \
> > "
>
> I prefer this one (especially for longer variables or entries) or "none",
> because with "none" it's easier to see where multiline variable ends.
>
> Worst is IMHO "joined" because when appending one more line you have to
> edit 2 lines to move '"' so the diff for review is longer and harder to
> read than just one added line.


I'd agree on both counts.
-- 
Christopher Larson

[-- Attachment #2: Type: text/html, Size: 1810 bytes --]

Re: recipe whitespace style questions

[Peter A. Bigot]

On 08/14/2013 09:31 AM, Joe MacDonald wrote:
> [Re: [OE-core] recipe whitespace style questions] On 13.08.14 (Wed 16:13) Martin Jansa wrote:
>
>> On Wed, Aug 14, 2013 at 08:51:40AM -0500, Peter A. Bigot wrote:
>>> SRC_URI = "file://skeleton \
>>>              file://skeleton_test.c \
>>>              file://COPYRIGHT \
>>> "
>>>
>>> which I'll call "none", and;
>>>
>>> SRC_URI = "file://skeleton \
>>>              file://skeleton_test.c \
>>>              file://COPYRIGHT"
>>>
>>> which I'll call "joined".
>>>
>>> Again, for consistency's sake it would be nice to have a
>>> recommendation.  I personally prefer "none", which matches the closing
>>> bracket style for functions.
>>>
>>> Next: I've also seen:
>>>
>>> SRC_URI = " \
>>>       file://skeleton \
>>>       file://skeleton_test.c \
>>>       file://COPYRIGHT \
>>> "
>> I prefer this one (especially for longer variables or entries) or "none",
>> because with "none" it's easier to see where multiline variable ends.
>>
>> Worst is IMHO "joined" because when appending one more line you have to
>> edit 2 lines to move '"' so the diff for review is longer and harder to
>> read than just one added line.
> +1

To close this out: that's three votes for the style named "none" or the 
one with separated lines.  No objections raised.

I'd thought the style guide was part of the Yocto documentation so I 
could prepare a patch to it, but it appears to only exist 
(independently) on the Yocto 
(https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide) and 
OpenEmbedded (http://www.openembedded.org/wiki/Styleguide) wiki sites.

In lieu of my applying for accounts on those sites and updating them 
I'll leave it that I think these additions would document the 
conclusions of this discussion, and are what I'll try to follow in my 
own Yocto-based recipe development:

* Multiple-line continuations should be indented to the level of the 
content following the introductory quote symbol on the first line.

* Alternatively, the first line of a multi-line value may be continued 
after the introductory quote symbol, with all subsequent content lines 
indented four spaces (or one tab if within a shell function)

* Any closing quote of a multiple-line continuation should be placed at 
the indentation level of the first continued line.

Peter