diff mbox series

[v3] docs: document the conventions used in the manuals

Message ID 20260922120620.2386763-1-twoerner@gmail.com
State Under Review
Headers show
Series [v3] docs: document the conventions used in the manuals | expand

Commit Message

Trevor Woerner Sept. 22, 2026, 12:06 p.m. UTC 
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.

Add a page stating them, in the sidebar beside the other top-level
entries, so it is reachable from every manual.

AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
Applies to: yocto-docs, on top of master. Paths under documentation/.
In reply to: <20260922013912.55583-1-twoerner@gmail.com>

Changes in v3, all from Antonin's review:
- :term:`build host` for both mentions of the build host.
- The root prompt example uses a generic "root@machine:~#" rather than a
  real board, as a default for generic target examples.
- The comment example stays tagged text, in answer to the question about
  shell. shell reads the "#" line as a comment but stops reading "$" as a
  prompt; console does the reverse. A lexer change and a re-tagging
  patch, neither sent yet, fix both together, so text is the right tag
  until those land and the best one if they never do.

Changes in v2:
- The page is a document in its own right, reached from a toctree in
  documentation/index.rst, rather than included into each manual's index.
  This is Antonin's suggestion and it is the better shape: the page
  appears in the sidebar of every manual, so a reader meets it wherever
  they are, and the diff touches two files rather than fifteen.
- Retitled "Documentation Conventions", which is short enough for the
  sidebar and matches "Documentation Downloads" beside it. The old title
  said "this document", which no longer describes a standalone page.
- The example showing that a leading "#" is a comment is tagged text
  rather than console. Pygments' console lexer reads a leading "#" as a
  root prompt and lexes the rest of the line as bash, so v1 rendered that
  line as a prompt running a command, with the word "command" coloured as
  a shell builtin - the opposite of what the sentence above it says.
- Added an opening sentence saying the conventions apply throughout the
  documentation, since the page is now landed on directly rather than
  read at the end of a manual.

This page says that commands carry a prompt and that a "#" line is a
comment. Neither is quite true of the manuals yet, so the docs-fixes
series does want to land first:
https://lore.kernel.org/r/20260922020339.481929-1-twoerner@gmail.com

 documentation/conventions.rst | 56 +++++++++++++++++++++++++++++++++++
 documentation/index.rst       |  7 +++++
 2 files changed, 63 insertions(+)
 create mode 100644 documentation/conventions.rst

Comments

Antonin Godard Sept. 22, 2026, 12:23 p.m. UTC | #1 
On Tue Sep 22, 2026 at 2:06 PM 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.
>
> Add a page stating them, in the sidebar beside the other top-level
[...]

Applied to master-next, thanks!

Antonin
diff mbox series

Patch

diff --git a/documentation/conventions.rst b/documentation/conventions.rst
new file mode 100644
index 000000000000..3bba4223aee0
--- /dev/null
+++ b/documentation/conventions.rst
@@ -0,0 +1,56 @@ 
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+=========================
+Documentation Conventions
+=========================
+
+These conventions apply throughout the Yocto Project documentation.
+
+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
+:term:`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 :term:`build host`:
+
+.. code-block:: console
+
+   root@machine:~# gdb /bin/cat
+
+Within an example, a line beginning with ``#`` is a comment rather than a
+command:
+
+.. code-block:: text
+
+   # This is a comment, not a command to run as root.
+   $ bitbake core-image-minimal
diff --git a/documentation/index.rst b/documentation/index.rst
index 4bfc40bef070..72e51a4454d7 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -116,3 +116,10 @@  Release notes and migration guides for the different Yocto Project releases.
    :hidden:
 
    downloads
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Documentation Conventions
+   :hidden:
+
+   conventions