Re: [HACKERS] [PATCH] Remove trailing whitespaces from documentation - Mailing list pgsql-hackers

From Stephen Frost
Subject Re: [HACKERS] [PATCH] Remove trailing whitespaces from documentation
Date
Msg-id 20161214222109.GB23417@tamriel.snowman.net
Whole thread Raw
In response to Re: [HACKERS] [PATCH] Remove trailing whitespaces from documentation  (Alvaro Herrera <alvherre@2ndquadrant.com>)
List pgsql-hackers
Alvaro,

* Alvaro Herrera (alvherre@2ndquadrant.com) wrote:
> Tom Lane wrote:
>
> > Thinking about this, I'm wondering what is the connection between
> > what psql does and what should be in the SGML (or XML) docs, anyway.
> > Nobody says boo when we have to do s/</</g to an example in order
> > to put it in the docs; why is stripping trailing whitespace a bigger
> > issue?
>
> Why do we need to put regular psql output verbatim in SGML/XML?  One
> idea is to add an output format to psql for docbook table markup, then
> use that whenever we need to paste stuff into the docs.

I do tend to like this idea.

Though, if we want to talk about writing lots of new code, what I really
like is the pgBackrest doc building system, which actually executes
pgBackrest during the documentation build process to run the commands
and get exactly what they produce included in the docs.  There's been
more than one example of *incorrect* hacking up of the example in the
docs, to the point where the example doesn't actually run, just this
year.

Perhaps if the regression tests ran the examples and produced the output
in a way which could be included in the docs...

Thanks!

Stephen

pgsql-hackers by date:

Previous
From: Alvaro Herrera
Date:
Subject: Re: [HACKERS] [PATCH] Remove trailing whitespaces from documentation
Next
From: Josh Berkus
Date:
Subject: Re: [HACKERS] Proposal for changes to recovery.conf API