public inbox for [email protected]help / color / mirror / Atom feed
code example wrapping 13+ messages / 5 participants [nested] [flat]
* code example wrapping @ 2010-04-05 15:59 Erik Rijkers <[email protected]> 0 siblings, 1 reply; 13+ messages in thread From: Erik Rijkers @ 2010-04-05 15:59 UTC (permalink / raw) To: pgsql-docs The manual has quite a few cases in the code-examples where, in the pdf version, there isn't enough width to show the whole line. Unfortunately, the rest of the line is then simply cut off, making the example 'invalid' (while reading, but also for copy-paste). I would like to reformat (only) those cases so that the text is completely readable on the pdf page. Of course, such lines will then also take the extra space in the html version (arguably, an advantage there as well). Anyone have any objections to this? Erik Rijkers ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: code example wrapping @ 2010-04-05 16:18 Tom Lane <[email protected]> parent: Erik Rijkers <[email protected]> 0 siblings, 1 reply; 13+ messages in thread From: Tom Lane @ 2010-04-05 16:18 UTC (permalink / raw) To: Erik Rijkers <[email protected]>; +Cc: pgsql-docs "Erik Rijkers" <[email protected]> writes: > The manual has quite a few cases in the code-examples where, in the pdf version, there isn't > enough width to show the whole line. Unfortunately, the rest of the line is then simply cut off, > making the example 'invalid' (while reading, but also for copy-paste). > I would like to reformat (only) those cases so that the text is completely readable on the pdf page. Exactly what width do you intend to wrap to, and how did you arrive at the number? regards, tom lane ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: code example wrapping @ 2010-04-05 16:30 Erik Rijkers <[email protected]> parent: Tom Lane <[email protected]> 0 siblings, 1 reply; 13+ messages in thread From: Erik Rijkers @ 2010-04-05 16:30 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: pgsql-docs On Mon, April 5, 2010 18:18, Tom Lane wrote: > "Erik Rijkers" <[email protected]> writes: >> The manual has quite a few cases in the code-examples where, in the pdf version, there isn't >> enough width to show the whole line. Unfortunately, the rest of the line is then simply cut >> off, >> making the example 'invalid' (while reading, but also for copy-paste). > >> I would like to reformat (only) those cases so that the text is completely readable on the pdf >> page. > Exactly what width do you intend to wrap to, and how did you arrive at > the number? > I want to manually reformat, rather than automatically wrap to some fixed width. The width would be determined by readability of the .pdf versions (-A4, -US). Maybe I should check other formats at the same time? It looks like less than 60 or 80 would already solve most of the problem-cases. Obviously, the actual split should be determined by the syntax of the example. Erik Rijkers ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: code example wrapping @ 2010-04-05 17:29 Peter Eisentraut <[email protected]> parent: Erik Rijkers <[email protected]> 0 siblings, 1 reply; 13+ messages in thread From: Peter Eisentraut @ 2010-04-05 17:29 UTC (permalink / raw) To: Erik Rijkers <[email protected]>; +Cc: Tom Lane <[email protected]>; pgsql-docs On mån, 2010-04-05 at 18:30 +0200, Erik Rijkers wrote: > On Mon, April 5, 2010 18:18, Tom Lane wrote: > > "Erik Rijkers" <[email protected]> writes: > >> The manual has quite a few cases in the code-examples where, in the pdf version, there isn't > >> enough width to show the whole line. Unfortunately, the rest of the line is then simply cut > >> off, > >> making the example 'invalid' (while reading, but also for copy-paste). > > > >> I would like to reformat (only) those cases so that the text is completely readable on the pdf > >> page. > > > Exactly what width do you intend to wrap to, and how did you arrive at > > the number? > > > > I want to manually reformat, rather than automatically wrap to some fixed width. > > The width would be determined by readability of the .pdf versions (-A4, -US). Maybe I should > check other formats at the same time? > > It looks like less than 60 or 80 would already solve most of the problem-cases. Obviously, the > actual split should be determined by the syntax of the example. Sure, makes sense. Lines much longer than 60-80 characters are probably not too readable in any format. ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: code example wrapping @ 2010-04-06 00:43 Erik Rijkers <[email protected]> parent: Peter Eisentraut <[email protected]> 0 siblings, 2 replies; 13+ messages in thread From: Erik Rijkers @ 2010-04-06 00:43 UTC (permalink / raw) To: Peter Eisentraut <[email protected]>; +Cc: Tom Lane <[email protected]>; pgsql-docs On Mon, April 5, 2010 19:29, Peter Eisentraut wrote: > On mån, 2010-04-05 at 18:30 +0200, Erik Rijkers wrote: >> On Mon, April 5, 2010 18:18, Tom Lane wrote: >> > "Erik Rijkers" <[email protected]> writes: >> > >> >> I would like to reformat (only) those cases so that the text is completely readable on the Here is plpgsql.sgml with reformatted code-examples for pdf readability (mainly split long lines; also fixed an concat error in one example). I've checked A4+US pdf's and html with these changes - they look OK, I think. Thanks, Erik Rijkers Attachments: [application/octet-stream] plpgsql.sgml.diff (4.7K, 2-plpgsql.sgml.diff) download | inline diff: --- doc/src/sgml/plpgsql.sgml.orig 2010-04-06 00:29:32.000000000 +0200 +++ doc/src/sgml/plpgsql.sgml 2010-04-06 02:06:51.000000000 +0200 @@ -481,9 +481,11 @@ is with <literal>RETURNS TABLE</>, for example: <programlisting> -CREATE FUNCTION extended_sales(p_itemno int) RETURNS TABLE(quantity int, total numeric) AS $$ +CREATE FUNCTION extended_sales(p_itemno int) +RETURNS TABLE(quantity int, total numeric) AS $$ BEGIN - RETURN QUERY SELECT quantity, quantity * price FROM sales WHERE itemno = p_itemno; + RETURN QUERY SELECT quantity, quantity * price FROM sales + WHERE itemno = p_itemno; END; $$ LANGUAGE plpgsql; </programlisting> @@ -2154,9 +2156,12 @@ -- Now "mviews" has one record from cs_materialized_views - PERFORM cs_log('Refreshing materialized view ' || quote_ident(mviews.mv_name) || ' ...'); + PERFORM cs_log('Refreshing materialized view ' + || quote_ident(mviews.mv_name) || ' ...'); EXECUTE 'TRUNCATE TABLE ' || quote_ident(mviews.mv_name); - EXECUTE 'INSERT INTO ' || quote_ident(mviews.mv_name) || ' ' || mviews.mv_query; + EXECUTE 'INSERT INTO ' + || quote_ident(mviews.mv_name) || ' ' + || mviews.mv_query; END LOOP; PERFORM cs_log('Done refreshing materialized views.'); @@ -2495,7 +2500,8 @@ <title><command>OPEN FOR EXECUTE</command></title> <synopsis> -OPEN <replaceable>unbound_cursorvar</replaceable> <optional> <optional> NO </optional> SCROLL </optional> FOR EXECUTE <replaceable class="command">query_string</replaceable> <optional> USING <replaceable>expression</replaceable> <optional>, ... </optional> </optional>; +OPEN <replaceable>unbound_cursorvar</replaceable> <optional> <optional> NO </optional> SCROLL </optional> FOR EXECUTE <replaceable class="command">query_string</replaceable> + <optional> USING <replaceable>expression</replaceable> <optional>, ... </optional> </optional>; </synopsis> <para> @@ -2517,7 +2523,8 @@ <para> An example: <programlisting> -OPEN curs1 FOR EXECUTE 'SELECT * FROM ' || quote_ident(tabname) ' WHERE col1 = $1' USING keyvalue; +OPEN curs1 FOR EXECUTE 'SELECT * FROM ' || quote_ident(tabname) + || ' WHERE col1 = $1' USING keyvalue; </programlisting> In this example, the table name is inserted into the query textually, so use of <function>quote_ident()</> is recommended to guard against @@ -2810,6 +2817,7 @@ END; ' LANGUAGE plpgsql; +-- need to be in a transaction to use cursors. BEGIN; SELECT reffunc2(); @@ -2966,7 +2974,8 @@ This example will abort the transaction with the given error message and hint: <programlisting> -RAISE EXCEPTION 'Nonexistent ID --> %', user_id USING HINT = 'Please check your user id'; +RAISE EXCEPTION 'Nonexistent ID --> %', user_id + USING HINT = 'Please check your user id'; </programlisting> </para> @@ -3394,7 +3403,8 @@ -- -- Function and trigger to amend summarized column(s) on UPDATE, INSERT, DELETE. -- -CREATE OR REPLACE FUNCTION maint_sales_summary_bytime() RETURNS TRIGGER AS $maint_sales_summary_bytime$ +CREATE OR REPLACE FUNCTION maint_sales_summary_bytime() RETURNS TRIGGER +AS $maint_sales_summary_bytime$ DECLARE delta_time_key integer; delta_amount_sold numeric(15,2); @@ -3416,7 +3426,8 @@ -- (probably not too onerous, as DELETE + INSERT is how most -- changes will be made). IF ( OLD.time_key != NEW.time_key) THEN - RAISE EXCEPTION 'Update of time_key : % -> % not allowed', OLD.time_key, NEW.time_key; + RAISE EXCEPTION 'Update of time_key : % -> % not allowed', + OLD.time_key, NEW.time_key; END IF; delta_time_key = OLD.time_key; @@ -3867,7 +3878,7 @@ <para> Another good way to develop in <application>PL/pgSQL</> is with a GUI database access tool that facilitates development in a - procedural language. One example of such as a tool is + procedural language. One example of such a tool is <application>pgAdmin</>, although others exist. These tools often provide convenient features such as escaping single quotes and making it easier to recreate and debug functions. @@ -4450,7 +4461,8 @@ IF a_running_job_count > 0 THEN COMMIT; -- free lock<co id="co.plpgsql-porting-commit"> - raise_application_error(-20000, 'Unable to create a new job: a job is currently running.'); + raise_application_error(-20000, + 'Unable to create a new job: a job is currently running.'); END IF; DELETE FROM cs_active_job; ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: code example wrapping @ 2010-04-14 01:11 Bruce Momjian <[email protected]> parent: Erik Rijkers <[email protected]> 1 sibling, 1 reply; 13+ messages in thread From: Bruce Momjian @ 2010-04-14 01:11 UTC (permalink / raw) To: Erik Rijkers <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; Tom Lane <[email protected]>; pgsql-docs Erik Rijkers wrote: > On Mon, April 5, 2010 19:29, Peter Eisentraut wrote: > > On m??n, 2010-04-05 at 18:30 +0200, Erik Rijkers wrote: > >> On Mon, April 5, 2010 18:18, Tom Lane wrote: > >> > "Erik Rijkers" <[email protected]> writes: > >> > > >> >> I would like to reformat (only) those cases so that the text is completely readable on the > > Here is plpgsql.sgml with reformatted code-examples for pdf readability > (mainly split long lines; also fixed an concat error in one example). > > I've checked A4+US pdf's and html with these changes - they look OK, I think. Also, I am looking at the PG9.0 Alpha 5 US-PDFs and see that the archive_command example on page 511 is also too long and extends off of the page: http://www.postgresql.org/files/documentation/pdf/9.0/postgresql-9.0alpha4-US.pdf and I bet my new test -f example is also going to go off the end once a PDF is built now that we are using the directory name twice on the same line. I have fiddled with that example for so long I am out of ideas. :-( Also, is there any way to get a report of the lines that are too long? -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: code example wrapping @ 2010-04-14 03:58 Tom Lane <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 1 reply; 13+ messages in thread From: Tom Lane @ 2010-04-14 03:58 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Peter Eisentraut <[email protected]>; pgsql-docs Bruce Momjian <[email protected]> writes: > Also, is there any way to get a report of the lines that are too long? grep "Overfull hbox" from the tex log ... regards, tom lane ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: code example wrapping @ 2010-04-14 14:38 Bruce Momjian <[email protected]> parent: Tom Lane <[email protected]> 0 siblings, 1 reply; 13+ messages in thread From: Bruce Momjian @ 2010-04-14 14:38 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Peter Eisentraut <[email protected]>; pgsql-docs Tom Lane wrote: > Bruce Momjian <[email protected]> writes: > > Also, is there any way to get a report of the lines that are too long? > > grep "Overfull hbox" from the tex log ... Can someone who can build the PDF docs post the output showing these lines? I can't build the PDF docs here. -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: code example wrapping @ 2010-04-14 22:28 Alvaro Herrera <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 2 replies; 13+ messages in thread From: Alvaro Herrera @ 2010-04-14 22:28 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Tom Lane <[email protected]>; Erik Rijkers <[email protected]>; Peter Eisentraut <[email protected]>; pgsql-docs Bruce Momjian wrote: > Tom Lane wrote: > > Bruce Momjian <[email protected]> writes: > > > Also, is there any way to get a report of the lines that are too long? > > > > grep "Overfull hbox" from the tex log ... > > Can someone who can build the PDF docs post the output showing these > lines? I can't build the PDF docs here. There are 1853 such reports in the output I have for a US run, but they reference a line number in the TeX source not SGML, so it's not easy to see what they are referring to. For example Overfull \hbox (141.59937pt too wide) in paragraph at lines 65564--65564 Overfull \hbox (28.1995pt too wide) in paragraph at lines 65612--65612 Overfull \hbox (11.99951pt too wide) in paragraph at lines 65702--65702 Overfull \hbox (17.3995pt too wide) in paragraph at lines 68738--68738 Overfull \hbox (28.1995pt too wide) in paragraph at lines 68739--68739 I think we could script extracting the TeX source that it refers to with some scripting. For now, the reports that are 4 digits or more points overfull are in paragraph at lines 268934 and following, which is just after this text: view is restricted to show only rows about tables that the current user can read.) For example, we might do: This is a very wide table in perform.sgml, lines 556ff. Maybe it can be displayed in \x for better formatting ... but then, the widest column is already too wide so maybe there's no point. -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: code example wrapping @ 2010-04-14 22:30 Alvaro Herrera <[email protected]> parent: Alvaro Herrera <[email protected]> 1 sibling, 0 replies; 13+ messages in thread From: Alvaro Herrera @ 2010-04-14 22:30 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Tom Lane <[email protected]>; Erik Rijkers <[email protected]>; Peter Eisentraut <[email protected]>; pgsql-docs Alvaro Herrera wrote: > For now, the reports that are 4 digits or more points overfull are in > paragraph at lines 268934 and following, which is just after this text: There are 105 reports of overfull hboxes of 3-digit number of points, 788 of 2-digit, and 957 of single-digit (these can probably be ignored). -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: code example wrapping @ 2010-04-27 14:34 Alvaro Herrera <[email protected]> parent: Erik Rijkers <[email protected]> 1 sibling, 1 reply; 13+ messages in thread From: Alvaro Herrera @ 2010-04-27 14:34 UTC (permalink / raw) To: Erik Rijkers <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; Tom Lane <[email protected]>; pgsql-docs Erik Rijkers wrote: > On Mon, April 5, 2010 19:29, Peter Eisentraut wrote: > > On mån, 2010-04-05 at 18:30 +0200, Erik Rijkers wrote: > >> On Mon, April 5, 2010 18:18, Tom Lane wrote: > >> > "Erik Rijkers" <[email protected]> writes: > >> > > >> >> I would like to reformat (only) those cases so that the text is completely readable on the > > Here is plpgsql.sgml with reformatted code-examples for pdf readability > (mainly split long lines; also fixed an concat error in one example). > > I've checked A4+US pdf's and html with these changes - they look OK, I think. Just applied it. I checked the HTML output and it looks good. I couldn't generate the PDF now; it died like this: $ make postgres-A4.pdf openjade -D . -D /pgsql/source/900orig/doc/src/sgml -c /usr/share/sgml/docbook/stylesheet/dsssl/modular/catalog -d /pgsql/source/900orig/doc/src/sgml/stylesheet.dsl -t tex -V tex-backend -i output-print -i include-index -V texpdf-output -V '%paper-type%'=A4 -o postgres-A4.tex-pdf /pgsql/source/900orig/doc/src/sgml/postgres.sgml pdfjadetex postgres-A4.tex-pdf This is pdfTeX, Version 3.1415926-1.40.10 (TeX Live 2009/Debian) restricted \write18 enabled. ---! /var/lib/texmf/web2c/pdftex/pdfjadetex.fmt doesn't match pdftex.pool (Fatal format file error; I'm stymied) make: *** [postgres-A4.pdf] Error 1 rm postgres-A4.tex-pdf I don't know what's going on but I bet it has to do with something I upgraded on this machine. -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: code example wrapping @ 2010-04-27 16:02 Tom Lane <[email protected]> parent: Alvaro Herrera <[email protected]> 0 siblings, 0 replies; 13+ messages in thread From: Tom Lane @ 2010-04-27 16:02 UTC (permalink / raw) To: Alvaro Herrera <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Peter Eisentraut <[email protected]>; pgsql-docs Alvaro Herrera <[email protected]> writes: > Just applied it. I checked the HTML output and it looks good. I > couldn't generate the PDF now; it died like this: > ---! /var/lib/texmf/web2c/pdftex/pdfjadetex.fmt doesn't match pdftex.pool > (Fatal format file error; I'm stymied) That's an installation problem... I can still build the .pdf, but only if I have a jadetex.cfg with a modified FlowObjectSetup macro as per http://archives.postgresql.org/pgsql-docs/2010-04/msg00022.php I'm not entirely sure that that macro is right, but we really are going to need to do something about it soon, if we'd like people to be able to build the beta docs. Anybody have any comments? regards, tom lane ^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: code example wrapping @ 2010-05-31 22:14 Bruce Momjian <[email protected]> parent: Alvaro Herrera <[email protected]> 1 sibling, 0 replies; 13+ messages in thread From: Bruce Momjian @ 2010-05-31 22:14 UTC (permalink / raw) To: Alvaro Herrera <[email protected]>; +Cc: Tom Lane <[email protected]>; Erik Rijkers <[email protected]>; Peter Eisentraut <[email protected]>; pgsql-docs Alvaro Herrera wrote: > Bruce Momjian wrote: > > Tom Lane wrote: > > > Bruce Momjian <[email protected]> writes: > > > > Also, is there any way to get a report of the lines that are too long? > > > > > > grep "Overfull hbox" from the tex log ... > > > > Can someone who can build the PDF docs post the output showing these > > lines? I can't build the PDF docs here. > > There are 1853 such reports in the output I have for a US run, but they > reference a line number in the TeX source not SGML, so it's not easy to > see what they are referring to. For example > > Overfull \hbox (141.59937pt too wide) in paragraph at lines 65564--65564 > Overfull \hbox (28.1995pt too wide) in paragraph at lines 65612--65612 > Overfull \hbox (11.99951pt too wide) in paragraph at lines 65702--65702 > Overfull \hbox (17.3995pt too wide) in paragraph at lines 68738--68738 > Overfull \hbox (28.1995pt too wide) in paragraph at lines 68739--68739 > > > I think we could script extracting the TeX source that it refers to with > some scripting. > > For now, the reports that are 4 digits or more points overfull are in > paragraph at lines 268934 and following, which is just after this text: > > view is restricted to show only > rows about tables that the current user can read.) > For example, we might do: > > This is a very wide table in perform.sgml, lines 556ff. Maybe it can be > displayed in \x for better formatting ... but then, the widest column is > already too wide so maybe there's no point. I have applied the attached documentation patch to explain how to find TeX overflow boxes. -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + None of us is going to be here forever. + Attachments: [text/x-diff] /rtmp/diff (1.4K, 2-%2Frtmp%2Fdiff) download | inline diff: Index: doc/src/sgml/docguide.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v retrieving revision 1.81 diff -c -c -r1.81 docguide.sgml *** doc/src/sgml/docguide.sgml 17 Mar 2010 17:12:31 -0000 1.81 --- doc/src/sgml/docguide.sgml 31 May 2010 22:13:00 -0000 *************** *** 643,648 **** --- 643,668 ---- save_size.pdfjadetex = 15000 </programlisting> </para> + + </sect2> + + <sect2> + <title>Overflow Text</title> + + <para> + Occasionally text is too wide for the printed margins, and in + extreme cases, too wide for the printed page, e.g. non-wrapped + text, wide tables. Overly wide text generates <quote>Overfull + hbox</quote> messages in the TeX log output file, e.g. + <filename>postgres-US.log</> or <filename>postgres-A4.log</>. + There are 72 points in an inch so anything reported as over 72 + points too wide will probably not fit on the printed page (assuming + one inch margins). To find the <acronym>SGML</acronym> text + causing the overflow, find the first page number mentioned above + the overflow message, e.g. <literal>[50 XXX]</> (page 50), and look + at that page in the <acronym>PDF</acronym> file to see the overflow + text and adjust the <acronym>SGML</acronym> accordingly. + </para> </sect2> <sect2> ^ permalink raw reply [nested|flat] 13+ messages in thread
end of thread, other threads:[~2010-05-31 22:14 UTC | newest] Thread overview: 13+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2010-04-05 15:59 code example wrapping Erik Rijkers <[email protected]> 2010-04-05 16:18 ` Tom Lane <[email protected]> 2010-04-05 16:30 ` Erik Rijkers <[email protected]> 2010-04-05 17:29 ` Peter Eisentraut <[email protected]> 2010-04-06 00:43 ` Erik Rijkers <[email protected]> 2010-04-14 01:11 ` Bruce Momjian <[email protected]> 2010-04-14 03:58 ` Tom Lane <[email protected]> 2010-04-14 14:38 ` Bruce Momjian <[email protected]> 2010-04-14 22:28 ` Alvaro Herrera <[email protected]> 2010-04-14 22:30 ` Alvaro Herrera <[email protected]> 2010-05-31 22:14 ` Bruce Momjian <[email protected]> 2010-04-27 14:34 ` Alvaro Herrera <[email protected]> 2010-04-27 16:02 ` Tom Lane <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox