Re: [poky] [PATCH] README.poky: Update to switch to markdown format and update

["Paul Barker" <pbarker@konsulko.com>]

I've given this a quick review for markdown usage, hopefully some of
these comments are useful. I recommend checking with
https://github.com/markdownlint/markdownlint to help find subtle
syntax errors which might trip up the rendering.

On Mon, 7 Jun 2021 at 16:30, Richard Purdie
<richard.purdie@linuxfoundation.org> wrote:
> --- a/meta-poky/README.poky
> +++ b/meta-poky/README.poky
> @@ -1,35 +1,19 @@
> -Poky
> -====
> +#Poky

Underlining with = characters is still supported for h1 headings if
this is preferred.

>
> -Poky is an integration of various components to form a complete prepackaged
> -build system and development environment. It features support for building
> -customised embedded device style images. There are reference demo images
> -featuring a X11/Matchbox/GTK themed UI called Sato. The system supports
> -cross-architecture application development using QEMU emulation and a
> -standalone toolchain and SDK with IDE integration.
> +Poky is an integration of various components to form pre-packaged build system and development environment which is used as a development and validation tool by the [Yocto Project](http://www.yoctoproject.org/ "Yocto Project"). It features support for building customised embedded style device images and custom containers. There are reference demo images ranging from X11/GTK+ to Weston, commandline and more. The system supports cross-architecture application development using QEMU emulation and a standalone toolchain and SDK suitable for IDE integration.

You should be able to hard wrap these lines at a reasonable length in
the source file and they should still be rendered into a single nicely
flowed paragraph by most markdown processors.

>
> -Additional information on the specifics of hardware that Poky supports
> -is available in README.hardware. Further hardware support can easily be added
> -in the form of layers which extend the systems capabilities in a modular way.
> +Additional information on the specifics of hardware that Poky supports is available in README.hardware. Further hardware support can easily be added in the form of BSP layers which extend the systems capabilities in a modular way. Many layers are available and can be found through the [layer index](https://layers.openembedded.org/ "layer index").

The link title is intended to be rendered as a tooltip when hovering
over the link so it's not needed unless it adds extra information. See
the example in https://www.markdownguide.org/basic-syntax/#adding-titles.
So this could just be [layer index](https://layers.openembedded.org/).
The same applies for other links below.

>
> -As an integration layer Poky consists of several upstream projects such as
> -BitBake, OpenEmbedded-Core, Yocto documentation and various sources of information
> -e.g. for the hardware support. Poky is in turn a component of the Yocto Project.
> +As an integration layer Poky consists of several upstream projects such as  [BitBake](https://git.openembedded.org/bitbake/ "BitBake"), [OpenEmbedded-Core](https://git.openembedded.org/openembedded-core/ "OpenEmbedded-Core"), [Yocto documentation](http://git.yoctoproject.org/cgit.cgi/yocto-docs/ "Yocto documentation"), the '[meta-yocto](http://git.yoctoproject.org/cgit.cgi/meta-yocto/ "meta-yocto")' layer which has configuration and hardware support components. These components are all part of the Yocto Project and OpenEmbedded ecosystems.
>
> -The Yocto Project has extensive documentation about the system including a
> -reference manual which can be found at:
> -    http://yoctoproject.org/documentation
> +The Yocto Project has extensive documentation about the system including a  reference manual which can be found at  https://docs.yoctoproject.org/

Raw URLs usually render ok but proper syntax is to surround them in
angle brackets like <https://docs.yoctoproject.org/>.

>
> -OpenEmbedded-Core is a layer containing the core metadata for current versions
> -of OpenEmbedded. It is distro-less (can build a functional image with
> -DISTRO = "") and contains only emulated machine support.
> +OpenEmbedded is the build architecture used by Poky and the Yocto project.
> +For information about OpenEmbedded, see the [OpenEmbedded website](http://www.openembedded.org/ "OpenEmbedded website").
>
> -For information about OpenEmbedded, see the OpenEmbedded website:
> -    http://www.openembedded.org/
> +#Contribution Guidelines
>
> -
> -Contribution Guidelines
> -=======================

These should be h2 headings which can be achieved by underlining with
- characters or using two hashes. Documents render best with just one
h1 heading at the top level.

Thanks,

-- 
Paul Barker
Konsulko Group