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

[Trevor Woerner <twoerner@gmail.com>]

On Mon 2026-08-31 @ 10:18:42 AM, 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. I
> think it would be more appropriate to add these conventions there.

Oh, that's interesting, and I hadn't thought of that.

You know how, whenever you pick up any programming book, there's a
section (usually in the Preface) that shows you what typeface is used
for code (versus prose), how a "Warning" admonition is drawn? That's
what I'm trying to recreate here. A "conventions used in this document"
section that is *reader* facing.

What you're pointing at is a *contributor* facing document. And it's a
good point, something should probably be mentioned there so that
contributors follow the same conventions throughout; it helps make the
document look like it was written by one person.

But I feel that a reader-facing conventions section is still warranted.

> Thanks,
> Antonin