Docs Format

[Regina Obe]

> > On Jun 12, 2026, at 11:20 AM, Sandro Santilli <strk at kbt.io> wrote:
> > But even better some good old shell or perl script to stub the
> > sections of a new function so we don't need GPUs to release the XML pain.
> >
> >> I think I would like to see a migration before signing on to a big change.
> >
> > What do you mean by “migration”
> 
> I mean a conversion of docbook to md or rst would be proceeded by said
> conversion a “best effort” PoC
> 
> P

I think people probably know how I feel about docbook vs. md as Paul pointed out.

https://lists.osgeo.org/pipermail/postgis-devel/2026-June/030777.html

I love md for readability, but I love docbook more for its exactness.
I think it will always be easier to morph docbook into md or any other human niceable format and not lose any meaning than it would be the other way around.
To go from a human niceable format to docbook I see as a somewhat ambiguous thing.

I do see Darafei's point about the docs in source being hard to navigate.  That seems to be the most fundamental problem and would like it if we can solve in other ways.
Like I mentioned in matrix/irc, perhaps putting a link on the viewable docs to the xml file it belongs.  

To Sandro's point, it would make more sense for us to allow a human to write in whatever format they want and have it at least
partially translate it for them if they are struggling.

As Laurențiu mentioned https://lists.osgeo.org/pipermail/postgis-devel/2026-June/030778.html

I find it hard to believe that AI has any issue with docbook and I think quite the contrary.  So doing this cause AI has an easier time seems like a very bad reason.

Thanks,
Regna