| Message ID | 20260831031458.4070250-1-twoerner@gmail.com |
|---|---|
| State | New |
| Headers | show |
| Series | docs: document the conventions used in the manuals | expand |
Hi, On Mon Aug 31, 2026 at 5:14 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote: > The manuals use angle brackets for placeholders and a prompt to mark a > command, and say so nowhere. A reader can only infer both, and one > example reads as advice to paste a line that will not parse. > > Include the new section from every manual, the way the boilerplate is > included, so each is self-contained. We already have a standard.md document that explains these kind of things. I think it would be more appropriate to add these conventions there. Thanks, Antonin
On Mon Aug 31, 2026 at 10:18 AM CEST, Antonin Godard wrote: > Hi, > > On Mon Aug 31, 2026 at 5:14 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote: >> The manuals use angle brackets for placeholders and a prompt to mark a >> command, and say so nowhere. A reader can only infer both, and one >> example reads as advice to paste a line that will not parse. >> >> Include the new section from every manual, the way the boilerplate is >> included, so each is self-contained. > > We already have a standard.md document that explains these kind of things. Sorry, s/standard.md/standards.md/. Antonin
diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst index 4adec9714f2f..6c0e56d9660c 100644 --- a/documentation/brief-yoctoprojectqs/index.rst +++ b/documentation/brief-yoctoprojectqs/index.rst @@ -502,4 +502,6 @@ information including the website, wiki pages, and user manuals: section in the Yocto Project Reference Manual provides a comprehensive list of all related links and other user documentation. +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/bsp-manual/index.rst b/documentation/bsp-manual/index.rst index 37469184e269..4229730080da 100644 --- a/documentation/bsp-manual/index.rst +++ b/documentation/bsp-manual/index.rst @@ -12,4 +12,6 @@ Yocto Project Board Support Package (BSP) Manual bsp +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/contributor-guide/index.rst b/documentation/contributor-guide/index.rst index b374cc1c43ec..39104259785b 100644 --- a/documentation/contributor-guide/index.rst +++ b/documentation/contributor-guide/index.rst @@ -23,4 +23,6 @@ this. recipe-style-guide submit-changes +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/conventions.rst b/documentation/conventions.rst new file mode 100644 index 000000000000..ab020113d046 --- /dev/null +++ b/documentation/conventions.rst @@ -0,0 +1,53 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +================================= +Conventions used in this document +================================= + +Placeholders +============ + +Text enclosed in angle brackets is a placeholder. Replace it, including the +brackets, with a value of your own: + +.. code-block:: none + + SRCREV:pn-<recipe> = "${AUTOREV}" + +Here, ``<recipe>`` stands for the name of your recipe. A placeholder is +never text to be copied as it stands, and an example containing one will +not work until every placeholder in it has been replaced. + +Commands and prompts +==================== + +Commands are shown with the prompt that runs them, and the prompt is not +part of the command. Do not type it. + +A ``$`` introduces a command you run as your normal user: + +.. code-block:: console + + $ bitbake core-image-minimal + +Where a command needs administrative privileges on your build host, it is +shown with ``sudo`` rather than with a root prompt: + +.. code-block:: console + + $ sudo apt install gawk + +A full prompt ending in ``#`` introduces a command run as ``root``, usually +on a target machine rather than on your build host: + +.. code-block:: console + + root@qemux86-64:~# gdb /bin/cat + +Within an example, a line beginning with ``#`` is a comment rather than a +command: + +.. code-block:: console + + # This is a comment, not a command to run as root. + $ bitbake core-image-minimal diff --git a/documentation/dev-manual/index.rst b/documentation/dev-manual/index.rst index 0e1aa89586d6..2a405b418f0c 100644 --- a/documentation/dev-manual/index.rst +++ b/documentation/dev-manual/index.rst @@ -52,4 +52,6 @@ Yocto Project Development Tasks Manual sstate-mirrors-setup hashequivserver +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/kernel-dev/index.rst b/documentation/kernel-dev/index.rst index bd20e371e0c2..8a0e104dc4f9 100644 --- a/documentation/kernel-dev/index.rst +++ b/documentation/kernel-dev/index.rst @@ -17,4 +17,6 @@ Yocto Project Linux Kernel Development Manual maint-appx faq +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/migration-guides/index.rst b/documentation/migration-guides/index.rst index e53215c73b6e..1a7058949b03 100644 --- a/documentation/migration-guides/index.rst +++ b/documentation/migration-guides/index.rst @@ -42,4 +42,6 @@ to move to one release of the Yocto Project from the previous one. migration-1.4 migration-1.3 +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/overview-manual/index.rst b/documentation/overview-manual/index.rst index 0061d1a1807d..3b8aa28f0353 100644 --- a/documentation/overview-manual/index.rst +++ b/documentation/overview-manual/index.rst @@ -70,4 +70,6 @@ For a comprehensive list of links and other documentation, see the Documentation <resources-links-and-related-documentation>`" section in the Yocto Project Reference Manual. +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/profile-manual/index.rst b/documentation/profile-manual/index.rst index 0270932ca0b1..53a87d7bf0bd 100644 --- a/documentation/profile-manual/index.rst +++ b/documentation/profile-manual/index.rst @@ -15,4 +15,6 @@ Yocto Project Profiling and Tracing Manual usage examples +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/ref-manual/index.rst b/documentation/ref-manual/index.rst index aa1a63e0500b..6b44bb461a80 100644 --- a/documentation/ref-manual/index.rst +++ b/documentation/ref-manual/index.rst @@ -28,4 +28,6 @@ Yocto Project Reference Manual faq resources +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/sdk-manual/index.rst b/documentation/sdk-manual/index.rst index a5c35cabaed1..d893ec8ed402 100644 --- a/documentation/sdk-manual/index.rst +++ b/documentation/sdk-manual/index.rst @@ -18,4 +18,6 @@ Yocto Project Application Development and Software Development Kits (SDK/eSDK) M appendix-customizing appendix-customizing-standard +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/security-manual/index.rst b/documentation/security-manual/index.rst index ab1ef445c86c..39ad0ee7a8c1 100644 --- a/documentation/security-manual/index.rst +++ b/documentation/security-manual/index.rst @@ -17,5 +17,7 @@ Yocto Project Security Manual read-only-rootfs sstate-signing +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/security-reference/index.rst b/documentation/security-reference/index.rst index c20a54d1a931..f9b0f0d73777 100644 --- a/documentation/security-reference/index.rst +++ b/documentation/security-reference/index.rst @@ -11,4 +11,6 @@ Yocto Project Security Reference security-team reporting-vulnerabilities +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/test-manual/index.rst b/documentation/test-manual/index.rst index d365d337ea5b..8f7f9e49a2cc 100644 --- a/documentation/test-manual/index.rst +++ b/documentation/test-manual/index.rst @@ -18,4 +18,6 @@ Yocto Project Test Environment Manual reproducible-builds yocto-project-compatible +.. include:: /conventions.rst + .. include:: /boilerplate.rst diff --git a/documentation/toaster-manual/index.rst b/documentation/toaster-manual/index.rst index 3ff4c6913aa4..ca2c38834bbc 100644 --- a/documentation/toaster-manual/index.rst +++ b/documentation/toaster-manual/index.rst @@ -15,4 +15,6 @@ Toaster User Manual setup-and-use reference +.. include:: /conventions.rst + .. include:: /boilerplate.rst
The manuals use angle brackets for placeholders and a prompt to mark a command, and say so nowhere. A reader can only infer both, and one example reads as advice to paste a line that will not parse. Include the new section from every manual, the way the boilerplate is included, so each is self-contained. AI-Generated: codex/claude opus 5 (xhigh) Signed-off-by: Trevor Woerner <twoerner@gmail.com> --- documentation/brief-yoctoprojectqs/index.rst | 2 + documentation/bsp-manual/index.rst | 2 + documentation/contributor-guide/index.rst | 2 + documentation/conventions.rst | 53 ++++++++++++++++++++ documentation/dev-manual/index.rst | 2 + documentation/kernel-dev/index.rst | 2 + documentation/migration-guides/index.rst | 2 + documentation/overview-manual/index.rst | 2 + documentation/profile-manual/index.rst | 2 + documentation/ref-manual/index.rst | 2 + documentation/sdk-manual/index.rst | 2 + documentation/security-manual/index.rst | 2 + documentation/security-reference/index.rst | 2 + documentation/test-manual/index.rst | 2 + documentation/toaster-manual/index.rst | 2 + 15 files changed, 81 insertions(+) create mode 100644 documentation/conventions.rst