Re: [docs] [PATCH] docs: document the conventions used in the manuals

[Trevor Woerner <twoerner@gmail.com>]

On Tue 2026-09-22 @ 09:32:38 AM, Antonin Godard wrote:
> On Tue Sep 22, 2026 at 3:35 AM CEST, Trevor Woerner wrote:
> > On Mon 2026-09-21 @ 04:34:35 PM, Antonin Godard wrote:
> >> Hi,
> >> 
> >> On Sat Sep 19, 2026 at 8:17 AM CEST, Trevor Woerner wrote:
> >> > On Mon 2026-09-14 @ 06:39:59 PM, Quentin Schulz wrote:
> >> [...]
> >> > having a
> >> > prompt clearly shows what are commands to type and what is output. For
> >> > the sake of uniformity I would rather not have code-block examples that
> >> > have and others that don't have prompts.
> >> 
> >> I agree.
> >> 
> >> >
> >> > As for the "what to copy" issue. Every code-block has a "copy" symbol
> >> > that appears in the code-block when you hover over the code-block. If
> >> > the code-block contains things to type with prompts and you click on the
> >> > copy icon of a code-block, the commands are copied and the prompts are
> >> > not. However, if the user highlights what to copy by clicking and
> >> > dragging with the mouse, they will get both the commands as well as the
> >> > prompts. However, that is configurable! It is possible to configure any
> >> > code-block identified as console to not copy the prompts, even when
> >> > clicked-and-dragged with the mouse.
> >> 
> >> Do you have a working solution for this?
> >
> > Yes (to follow).
> 
> Actually it seems to be already working for me. After building the docs, I
> cannot select either "$" or "root@qemux86-64:~#" so things seem to be working as
> expected?

Out of the box you are correct that in the case where there is a "#"
prompt, the prompt is not selected (just the command). But look for an
example where there is both a "#" prompt and output lines prefixed with
# [1], the comment # will be skipped too (not correct). Plus if you test
with the copybutton the whole block is selected (prompt and all).

There are 2 ways of copying: clicking the copybutton, or dragging with
the mouse. Be sure to test both and make sure both methods do the same
thing, and the thing they do is the correct thing.

See patch 2 of my docs-fixes set:
https://lore.kernel.org/r/20260922020339.481929-3-twoerner@gmail.com

The full patchsets that I have (not all of them sent yet) fixes all of
this, but I didn't want to overwhelm with too many patches at once. The
docs-fixes all stand on their own and are good to have regardless of
anything else. The conventions-v2 is slightly out of place,
conventions-v1 really should have only been suggested after all the
others were agreed on, but I felt compelled to send a conventions-v2 now
since v1 had been reviewed. conventions-v3 (to be sent) will be correct
for now if docs-fixes is accepted.

> Antonin

[1] "Basic ftrace usage" in the profile manual, the "cat trace | less" one