code example wrapping

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

"Erik Rijkers" <er(at)xs4all(dot)nl> 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

On Mon, April 5, 2010 18:18, Tom Lane wrote:
> "Erik Rijkers" <er(at)xs4all(dot)nl> 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

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" <er(at)xs4all(dot)nl> 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.

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" <er(at)xs4all(dot)nl> 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

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" <er(at)xs4all(dot)nl> 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 <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

Bruce Momjian <bruce(at)momjian(dot)us> 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

Tom Lane wrote:
> Bruce Momjian <bruce(at)momjian(dot)us> 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 <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

Bruce Momjian wrote:
> Tom Lane wrote:
> > Bruce Momjian <bruce(at)momjian(dot)us> 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

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

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" <er(at)xs4all(dot)nl> 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

Alvaro Herrera <alvherre(at)commandprompt(dot)com> 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

Alvaro Herrera wrote:
> Bruce Momjian wrote:
> > Tom Lane wrote:
> > > Bruce Momjian <bruce(at)momjian(dot)us> 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 <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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