Subject: code example wrapping

From: "Erik Rijkers" <[email-masked]>
Date: Mon, 5 Apr 2010 17:59:26 +0200

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

---

From: Tom Lane <[email-masked]>
Date: Mon, 05 Apr 2010 12:18:34 -0400

> 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

---

From: "Erik Rijkers" <[email-masked]>
Date: Mon, 5 Apr 2010 18:30:26 +0200

> Exactly what width do you intend to wrap to, and how did you arrive at

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

---

From: Peter Eisentraut <[email-masked]>
Date: Mon, 05 Apr 2010 20:29:31 +0300

> 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.

---

From: "Erik Rijkers" <[email-masked]>
Date: Tue, 6 Apr 2010 02:43:32 +0200

On Mon, April 5, 2010 19:29, Peter Eisentraut wrote:
> On mÃ¥n, 2010-04-05 at 18:30 +0200, Erik Rijkers wrote:
>> >> 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

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 13 Apr 2010 21:11:17 -0400 (EDT)

Erik Rijkers wrote:
> > On m??n, 2010-04-05 at 18:30 +0200, Erik Rijkers wrote:

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-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

---

From: Tom Lane <[email-masked]>
Date: Tue, 13 Apr 2010 23:58:41 -0400

> 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

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 14 Apr 2010 10:38:56 -0400 (EDT)

> 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.

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 14 Apr 2010 18:28:06 -0400

> 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

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 14 Apr 2010 18:30:09 -0400

> 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).

---

From: Alvaro Herrera <[email-masked]>
Date: Tue, 27 Apr 2010 10:34:38 -0400

> 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.

---

From: Tom Lane <[email-masked]>
Date: Tue, 27 Apr 2010 12:02:22 -0400

> (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

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 31 May 2010 18:14:26 -0400 (EDT)

> already too wide so maybe there's no point.

I have applied the attached documentation patch to explain how to find
TeX overflow boxes.

  + None of us is going to be here forever. +

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>