diff mbox series

doc: document the conventions used in the manual

Message ID 20260831031444.4070152-1-twoerner@gmail.com
State New
Headers show
Series doc: document the conventions used in the manual | expand

Commit Message

Trevor Woerner Aug. 31, 2026, 3:14 a.m. UTC 
The manual uses angle brackets for placeholders and a prompt to mark a
command, and says so nowhere. A reader can only infer both.

AI-Generated: codex/claude opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
 doc/conventions.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++
 doc/index.rst       |  2 ++
 2 files changed, 55 insertions(+)
 create mode 100644 doc/conventions.rst

Comments

Antonin Godard Aug. 31, 2026, 8:26 a.m. UTC | #1 
Hi,

On Mon Aug 31, 2026 at 5:14 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
> The manual uses angle brackets for placeholders and a prompt to mark a
> command, and says so nowhere. A reader can only infer both.

This only adds the document at the bottom of the main page, which I don't think
is a proper place for it. We should either have a section dedicated to this, or
make this a separate document (similar to standards.md in yocto-docs).

I'm leaning towards a separate document (named "standards.md"?), because these
instructions are not related to Bitbake itself. This document should be easily
found though, so perhaps we should mention it in the main README, under the
Contributing section.

Thanks,
Antonin
diff mbox series

Patch

diff --git a/doc/conventions.rst b/doc/conventions.rst
new file mode 100644
index 000000000000..ab020113d046
--- /dev/null
+++ b/doc/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/doc/index.rst b/doc/index.rst
index 9f2a9067d385..d9547e1c723d 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -29,6 +29,8 @@  BitBake User Manual
 
 ----
 
+.. include:: /conventions.rst
+
 .. include:: <xhtml1-lat1.txt>
 
 | BitBake Community