Unhelpful typesetting of callouts in example queries in the docs

From: Thomas Munro <thomas(dot)munro(at)enterprisedb(dot)com>
To: Pg Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Unhelpful typesetting of callouts in example queries in the docs
Date: 2017-02-28 02:49:22
Message-ID: CAEepm=268=4CJ0bRdkHH-aQ4pwhv4isMnRaGLPo62T=JR8nVYA@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hi

A novice user asked me about the last example here, which kept producing errors:

https://www.postgresql.org/docs/9.6/static/tutorial-agg.html?

It turned out that the 'callout' was causing confusion because it
sticks "(1)" into the middle of the query in approximately the same
typeface:

SELECT city, max(temp_lo)
FROM weather
WHERE city LIKE 'S%'(1)
GROUP BY city
HAVING max(temp_lo) < 40;

Maybe we should move it over a bit (?) and make it a comment, in case
it gets copied-and-pasted or otherwise misinterpreted?

SELECT city, max(temp_lo)
FROM weather
WHERE city LIKE 'S%' -- (1)
GROUP BY city
HAVING max(temp_lo) < 40;

See attached which does that and there and a couple of other places.

--
Thomas Munro
http://www.enterprisedb.com

Attachment Content-Type Size
put-callouts-in-sql-comments.patch application/octet-stream 2.3 KB

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Bruce Momjian 2017-02-28 02:52:10 Re: bytea_output output of base64
Previous Message David Steele 2017-02-28 02:44:46 Final commitfest for 10.0 almost underway