Inconsistent use of "cd ~/poky" and "cd poky" in the manuals

Inconsistent use of "cd ~/poky" and "cd poky" in the manuals

[Michael Opdenacker]

Greetings,

I'm joining the project to help with the documentation...

By going through the "Yocto Project Quick Build" instructions
(https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html#), and
I've noticed an inconsistency that impacts several documents...

People are first instructed to clone the poky git repository, but not
mentioning from which directory. Then, it's consistent to instruct
people to run "cd poky/".

However, later in the instructions, readers are instructed to run "cd
~/poky", which assumes that cloning poky was done from the home
directory. Many other places in the documentation make such an assumption:

documentation/README:      $ mkdir ~/poky-&DISTRO;
documentation/dev-manual/common-tasks.rst:      $ cd ~/poky
documentation/dev-manual/common-tasks.rst:      $ wic cp ~/poky_sdk/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+git999-r0/linux-yocto-4.12.12+git999/arch/x86/boot/bzImage \
documentation/dev-manual/common-tasks.rst:               ~/poky/build/tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz
documentation/dev-manual/common-tasks.rst:   ``~/poky/build/conf/local.conf``).
documentation/dev-manual/common-tasks.rst:directory of ``~/poky/build/tmp/deploy/rpm`` and a ``PACKAGE_CLASSES``
documentation/dev-manual/common-tasks.rst:   $ cd ~/poky/build/tmp/deploy/rpm
documentation/dev-manual/common-tasks.rst:   $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
documentation/dev-manual/common-tasks.rst:   ``~/poky/scripts``).
documentation/dev-manual/common-tasks.rst:      $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README"
documentation/dev-manual/common-tasks.rst:      $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org
documentation/dev-manual/qemu.rst:         $ cd ~/poky
documentation/dev-manual/qemu.rst:         . ~/poky_sdk/environment-setup-core2-64-poky-linux
documentation/dev-manual/start.rst:      $ cd ~/poky
documentation/kernel-dev/common.rst:      $ cd ~/poky
documentation/kernel-dev/common.rst:   ``~/poky/build`` in this example).
documentation/kernel-dev/common.rst:      $ cd ~/poky/build
documentation/kernel-dev/common.rst:      $ cd ~/poky/build
documentation/kernel-dev/common.rst:      $ cd ~/poky/build
documentation/kernel-dev/common.rst:      ~/poky/build/tmp/deploy/sdk
documentation/kernel-dev/common.rst:   ``~/poky_sdk`` directory:
documentation/kernel-dev/common.rst:      $ cd ~/poky/build/tmp/deploy/sdk
documentation/kernel-dev/common.rst:      Enter target directory for SDK (default: ~/poky_sdk):
documentation/kernel-dev/common.rst:      $ source ~/poky_sdk/environment-setup-i586-poky-linux
documentation/kernel-dev/common.rst:      $ cd ~/poky
documentation/kernel-dev/common.rst:   ``~/poky/build`` in this example).
documentation/kernel-dev/common.rst:      $ cd ~/poky/build
documentation/kernel-dev/common.rst:      $ cd ~/poky/build
documentation/kernel-dev/common.rst:      ``~/poky_sdk/workspace/sources/linux-yocto``). Change to where the
documentation/kernel-dev/common.rst:         $ cd ~/poky_sdk/workspace/sources/linux-yocto
documentation/kernel-dev/common.rst:      $ cd ~/poky_sdk/workspace/sources/linux-yocto
documentation/kernel-dev/common.rst:      $ cd ~/poky/build
documentation/kernel-dev/common.rst:      $ cd ~/poky/build/conf
documentation/kernel-dev/common.rst:      $ cd ~/poky/build
documentation/kernel-dev/common.rst:      $ cd ~/poky/build
documentation/kernel-dev/common.rst:              $ cd ~/poky/build
documentation/kernel-dev/common.rst:Directory's top-level folder is ``~/poky``:
documentation/sdk-manual/appendix-obtain.rst:      $ cd ~/poky/build/tmp/deploy/sdk
documentation/sdk-manual/appendix-obtain.rst:      $ source ~/poky_sdk/environment-setup-core2-64-poky-linux
documentation/sdk-manual/extensible.rst:   Enter target directory for SDK (default: ~/poky_sdk):
documentation/toaster-manual/reference.rst:   $ cd ~/poky/build
documentation/toaster-manual/setup-and-use.rst:      $ cd ~/poky/build
documentation/toaster-manual/setup-and-use.rst:      cd ~/poky/

That's more than the other choice:

documentation/brief-yoctoprojectqs/index.rst:   $ cd poky
documentation/brief-yoctoprojectqs/index.rst:      $ cd poky
documentation/brief-yoctoprojectqs/index.rst:      $ cd poky
documentation/brief-yoctoprojectqs/index.rst:      $ cd poky/build
documentation/brief-yoctoprojectqs/index.rst:   $ cd poky
documentation/dev-manual/common-tasks.rst:   $ cd poky
documentation/kernel-dev/common.rst:   $ cd poky
documentation/overview-manual/development-environment.rst:   $ cd poky
documentation/overview-manual/development-environment.rst:   $ cd poky
documentation/ref-manual/features.rst:   $ cd poky
documentation/ref-manual/system-requirements.rst:      $ cd poky
documentation/ref-manual/system-requirements.rst:      $ cd poky
documentation/toaster-manual/setup-and-use.rst:   $ cd poky

I could propose a patch that explicitly assumes that poky is cloned from
the home directory, making it clear that it's just to simplify the
documentation and doesn't correspond to any technical recommendation.
The advantage I see is that users that just want to copy and paste
commands won't have to use their brains to adapt the commands.

On the other hand, my second idea was to stop assuming that poky was
cloned from the home directory, and propose a patch that replaces
"~/poky/" by "poky/" everywhere, assuming that people using the Yocto
Project know how to use their brains anyway and understand where they're
storing their data ;-)

What would be your preference? Has this already been discussed?

Thanks in advance,

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] Inconsistent use of "cd ~/poky" and "cd poky" in the manuals

[Richard Purdie]

On Fri, 2021-03-19 at 16:32 +0100, Michael Opdenacker wrote:
> On the other hand, my second idea was to stop assuming that poky was
> cloned from the home directory, and propose a patch that replaces
> "~/poky/" by "poky/" everywhere, assuming that people using the Yocto
> Project know how to use their brains anyway and understand where they're
> storing their data ;-)
> 
> What would be your preference? Has this already been discussed?

I've never spotted that :)

I'd think changing to poky/ would be more consistent, we don't require
it to be in ~ but its just an opinion...

Cheers,

Richard

Re: [docs] Inconsistent use of "cd ~/poky" and "cd poky" in the manuals

[Nicolas Dechesne]

On Fri, Mar 19, 2021 at 4:34 PM Richard Purdie
<richard.purdie@linuxfoundation.org> wrote:
>
> On Fri, 2021-03-19 at 16:32 +0100, Michael Opdenacker wrote:
> > On the other hand, my second idea was to stop assuming that poky was
> > cloned from the home directory, and propose a patch that replaces
> > "~/poky/" by "poky/" everywhere, assuming that people using the Yocto
> > Project know how to use their brains anyway and understand where they're
> > storing their data ;-)
> >
> > What would be your preference? Has this already been discussed?
>
> I've never spotted that :)
>
> I'd think changing to poky/ would be more consistent, we don't require
> it to be in ~ but its just an opinion...

Regardless of the solution, consistency is definitely needed!

So let me propose a 3rd way :) We could assume that poky is install in
$POKY and use that all over the place. If anyone wants to copy/paste
snippet from the doc, they would just need to define the POKY env var.
If that's not desire, then I would prefer using cd poky, as per
Richard's suggestion.

>
> Cheers,
>
> Richard
>
>
> 
>

Re: [docs] Inconsistent use of "cd ~/poky" and "cd poky" in the manuals

[Michael Opdenacker]

Hi Richard,

Thanks for your advise!

On 3/19/21 4:34 PM, Richard Purdie wrote:
> On Fri, 2021-03-19 at 16:32 +0100, Michael Opdenacker wrote:
>> On the other hand, my second idea was to stop assuming that poky was
>> cloned from the home directory, and propose a patch that replaces
>> "~/poky/" by "poky/" everywhere, assuming that people using the Yocto
>> Project know how to use their brains anyway and understand where they're
>> storing their data ;-)
>>
>> What would be your preference? Has this already been discussed?
> I've never spotted that :)

That's the advantage of being new to the project.

I hope I won't lose it to quickly ;)

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] Inconsistent use of "cd ~/poky" and "cd poky" in the manuals

[Michael Opdenacker]

Hi Nico,

On 3/19/21 4:38 PM, Nicolas Dechesne wrote:
> On Fri, Mar 19, 2021 at 4:34 PM Richard Purdie
> <richard.purdie@linuxfoundation.org> wrote:
>> On Fri, 2021-03-19 at 16:32 +0100, Michael Opdenacker wrote:
>>> On the other hand, my second idea was to stop assuming that poky was
>>> cloned from the home directory, and propose a patch that replaces
>>> "~/poky/" by "poky/" everywhere, assuming that people using the Yocto
>>> Project know how to use their brains anyway and understand where they're
>>> storing their data ;-)
>>>
>>> What would be your preference? Has this already been discussed?
>> I've never spotted that :)
>>
>> I'd think changing to poky/ would be more consistent, we don't require
>> it to be in ~ but its just an opinion...
> Regardless of the solution, consistency is definitely needed!
>
> So let me propose a 3rd way :) We could assume that poky is install in
> $POKY and use that all over the place. If anyone wants to copy/paste
> snippet from the doc, they would just need to define the POKY env var.


But then, we would be introducing a new environment variable, and some
people may wrongly assume it's used in the code somewhere too, though
it's only for the convenience of documentation... This could be
confusing new users.

Just my two cents, though. You know new users much better than I do.

Cheers,

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com