Re: Introductory docs-hacking task: Example markup

From: Matemática A3K <matematica(dot)a3k(at)gmail(dot)com>
To: "David G(dot) Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com>
Cc: Daniel Gustafsson <daniel(at)yesql(dot)se>, Xavier Fischer <xavier_fischer(at)hotmail(dot)fr>, "pgsql-docs(at)lists(dot)postgresql(dot)org" <pgsql-docs(at)lists(dot)postgresql(dot)org>
Subject: Re: Introductory docs-hacking task: Example markup
Date: 2026-11-19 04:04:30
Message-ID: CA+FDnh+KzmSzmtYuxj4hGYHoSCbbfaS4CgJkf8qKZKbcECaoCQ@mail.gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-docs

> A decent number of such potential guidelines have been mentioned in the past, but getting them actually committed right now hasn't been attempted by anyone, for whatever their personal reasons. Sticking an agent on the mailing list archives looking for such - my participation in a thread should narrow the surface area quite a bit though I don't know how big the false negative set would be - would be a fruitful way to start such an endeavor. Its on my own todo list but down quite a ways in priority.

TADA! https://pastebin.com/FTQ7jXj0

I think that from it, something can be extracted. Then a page
"Documentation Guidelines" can be constructed. Something like:

Conventions are largely oral tradition and enforced in review. To
streamline the process, have the following criteria in mind when
writing new documentation and submitting changes for it:

- ..
- The documentation source uses a distinctive style with single-space
indentation, with lines wrapping around 80 characters.
- American English spelling (e.g., "behavior", "initialize")
- Examples should be runnable
- ...

I was thinking in opening a wiki page where this can be worked on, I
see there are some pages related that require login to access, and
once logged in, I don't have permissions to create it.

Can you (or anyone) create a "Documentation_Guidelines" page - or
similar - for this?

> David J.

Also, it provides "reflections" on the markup being used - which is in
the direction of what Daniel was talking about

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Laurenz Albe 2026-11-19 07:18:07 Re: Introductory docs-hacking task: Example markup
Previous Message Andrea Esposito 2026-11-18 21:37:49 doc: explain what can restrict an ltree GiST index search for lquery