Thread: 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@xs4all.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@xs4all.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@xs4all.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@xs4all.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
Attachment
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@xs4all.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@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
Bruce Momjian <bruce@momjian.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@momjian.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@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com
Bruce Momjian wrote:
> Tom Lane wrote:
> > Bruce Momjian <bruce@momjian.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@xs4all.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@commandprompt.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@momjian.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@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + 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>