Unhelpful typesetting of callouts in example queries in the docs
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
Attachments:
put-callouts-in-sql-comments.patchapplication/octet-stream; name=put-callouts-in-sql-comments.patchDownload
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index d3272e1..d356deb 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -5328,14 +5328,14 @@ SELECT * FROM cs_parse_url('http://foobar.com/query.cgi?baz');
<programlisting>
CREATE OR REPLACE PROCEDURE cs_create_job(v_job_id IN INTEGER) IS
a_running_job_count INTEGER;
- PRAGMA AUTONOMOUS_TRANSACTION;<co id="co.plpgsql-porting-pragma">
+ PRAGMA AUTONOMOUS_TRANSACTION; -- <co id="co.plpgsql-porting-pragma">
BEGIN
- LOCK TABLE cs_jobs IN EXCLUSIVE MODE;<co id="co.plpgsql-porting-locktable">
+ LOCK TABLE cs_jobs IN EXCLUSIVE MODE; -- <co id="co.plpgsql-porting-locktable">
SELECT count(*) INTO a_running_job_count FROM cs_jobs WHERE end_stamp IS NULL;
IF a_running_job_count > 0 THEN
- COMMIT; -- free lock<co id="co.plpgsql-porting-commit">
+ COMMIT; -- free lock <co id="co.plpgsql-porting-commit">
raise_application_error(-20000,
'Unable to create a new job: a job is currently running.');
END IF;
@@ -5402,7 +5402,7 @@ BEGIN
SELECT count(*) INTO a_running_job_count FROM cs_jobs WHERE end_stamp IS NULL;
IF a_running_job_count > 0 THEN
- RAISE EXCEPTION 'Unable to create a new job: a job is currently running';<co id="co.plpgsql-porting-raise">
+ RAISE EXCEPTION 'Unable to create a new job: a job is currently running'; -- <co id="co.plpgsql-porting-raise">
END IF;
DELETE FROM cs_active_job;
@@ -5411,7 +5411,7 @@ BEGIN
BEGIN
INSERT INTO cs_jobs (job_id, start_stamp) VALUES (v_job_id, now());
EXCEPTION
- WHEN unique_violation THEN <co id="co.plpgsql-porting-exception">
+ WHEN unique_violation THEN -- <co id="co.plpgsql-porting-exception">
-- don't worry if it already exists
END;
END;
diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml
index f4fbf11..5664d41 100644
--- a/doc/src/sgml/query.sgml
+++ b/doc/src/sgml/query.sgml
@@ -754,7 +754,7 @@ SELECT city, max(temp_lo)
<programlisting>
SELECT city, max(temp_lo)
FROM weather
- WHERE city LIKE 'S%'<co id="co.tutorial-agg-like">
+ WHERE city LIKE 'S%' -- <co id="co.tutorial-agg-like">
GROUP BY city
HAVING max(temp_lo) < 40;
</programlisting>
On 2/27/17 21:49, Thomas Munro wrote:
It turned out that the 'callout' was causing confusion because it
sticks "(1)" into the middle of the query in approximately the same
typeface:
Maybe we should move it over a bit (?) and make it a comment, in case
it gets copied-and-pasted or otherwise misinterpreted?
committed
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers