Thread: Documentation nits

Documentation nits

From
Rich Morin
Date:
I am not a PostgreSQL user, just an editor who has looked over some
of your printable documentation.  I found some problems and thought
you'd like to know about them...

-r


PostreSQL 7.1 Administrator's Guide

   On page iii (2nd line), something is printing as a square (?).

   On page xv (antepenultimate line), "Gnu Project" should be "GNU
   Project".

   On page 78, the "Release date" is listed as "2001-??-??".


PostreSQL 7.1 Developer's Guide

   The Arabic page numbers do not match the actual page numbers for
   "List of Tables" and "List of Examples".


PostreSQL 7.1 Programmer's Guide

   The Arabic page numbers do not match the actual page numbers for
   "List of Tables" , "List of Figures", and "List of Examples".  Also,
   there seem to be two sequences of Arabic page numbers (e.g., the
   Preface is not the first item, yet it is listed as Page "i").


PostreSQL 7.1 Reference Manual

   Certain entries in the Table of Contents are exdented slightly
   (alternatively, the other entries may be indented slightly :-):

     CHECKPOINT, RESET, SET, SET CONSTRAINTS, SET TRANSACTION, SHOW,
     createdb, createuser, etc.


PostreSQL 7.1 User's Guide

   The Arabic page numbers do not start with the first page of the
   document; the "Table of Contents" should be on page "iii".  Also,
   there seem to be two sequences of Arabic page numbers (e.g., the
   Preface is not the first item, yet it is listed as Page "i").

   In Table 3-10, the text is jammed up against the lefthand rules.

   On page 53 (3rd line), something is printing as a square (?).
--
email: rdm@cfcl.com; phone: +1 650-873-7841
http://www.cfcl.com/rdm - home page, resume, etc.
http://www.cfcl.com/Meta/md_fb.html - The FreeBSD Browser
http://www.ptf.com/tdc - Prime Time Freeware's Darwin Collection

Re: Documentation nits

From
Bruce Momjian
Date:
>    On page xv (antepenultimate line), "Gnu Project" should be "GNU
>    Project".

Fixed.  Thanks.

>    On page 78, the "Release date" is listed as "2001-??-??".

This is a tough one.  We generate the docs before we know the date of
final release.  Does anyone have a suggestion on how to fix that?

I can't comment on the others because they relate to rendering problems.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Re: Documentation nits

From
Peter Eisentraut
Date:
Rich Morin writes:

> PostreSQL 7.1 Administrator's Guide
>
>    On page iii (2nd line), something is printing as a square (?).

Could you give some context?  I don't have the specific document at hand.

> PostreSQL 7.1 Developer's Guide
>
>    The Arabic page numbers do not match the actual page numbers for
>    "List of Tables" and "List of Examples".

> PostreSQL 7.1 Programmer's Guide
>
>    The Arabic page numbers do not match the actual page numbers for
>    "List of Tables" , "List of Figures", and "List of Examples".  Also,
>    there seem to be two sequences of Arabic page numbers (e.g., the
>    Preface is not the first item, yet it is listed as Page "i").

I've found that the Arabic page numbers in the front matter don't work
correctly.  I think I have this fixed for the 7.2 release, but it's a
combination of a newer stylesheet release, patches yet to be included in
an even newer stylesheet release, plus the new PG customization layer, so
it might be a bit hard to reproduce for outsiders.

> PostreSQL 7.1 Reference Manual
>
>    Certain entries in the Table of Contents are exdented slightly
>    (alternatively, the other entries may be indented slightly :-):
>
>      CHECKPOINT, RESET, SET, SET CONSTRAINTS, SET TRANSACTION, SHOW,
>      createdb, createuser, etc.

I vote for indented.  I can see the issue from a theoretical point of
view, but it doesn't appear to happen with the newer toolchain I have
here.  Will have to watch this.

> PostreSQL 7.1 User's Guide
>
>    The Arabic page numbers do not start with the first page of the
>    document; the "Table of Contents" should be on page "iii".  Also,
>    there seem to be two sequences of Arabic page numbers (e.g., the
>    Preface is not the first item, yet it is listed as Page "i").
>
>    In Table 3-10, the text is jammed up against the lefthand rules.

Peculiar.

>    On page 53 (3rd line), something is printing as a square (?).

Again, some context would help me find this faster.

Thanks for those reports.

--
Peter Eisentraut   peter_e@gmx.net

Re: Documentation nits

From
Rich Morin
Date:
At 5:13 PM +0100 11/15/01, Peter Eisentraut wrote:
>Rich Morin writes:
>
>>  PostreSQL 7.1 Administrator's Guide
>>
>>     On page iii (2nd line), something is printing as a square (?).
>
>Could you give some context?  I don't have the specific document at hand.

It is a ToC entry, looking like

   "12.1.7. The #random# test  ... 76"

where the '#'s actually show up as squares.  Looking at page 76 (and some
surrounding pages), I see a number of other instances where these little
squares show up, as:

   73    There is a #parallel# and a #sequential# mode ...

   74    When a test is reported as #failed#, ...

   75    Some of the queries in the #timestamp# test ...

   76    ... thereby eliminate the bogus #failure# in future releases.
         So, to eliminate bogus test #failures# for a particular ...

Evidently, the square is an indication that some bit of markup hasn't
been translated properly.

>I've found that the Arabic page numbers in the front matter don't work
>correctly.  I think I have this fixed for the 7.2 release, but it's a
>combination of a newer stylesheet release, patches yet to be included in
>an even newer stylesheet release, plus the new PG customization layer, so
>it might be a bit hard to reproduce for outsiders.

Well, in my case, I only care whether the PostScript files you generate
are clean.  OTOH, the Arabic page numbers in the front matter work
correctly on most of the PostgreSQL docs, so that should give you a hint
as to the underlying nature of the problem in these documents...

>I vote for indented.  I can see the issue from a theoretical point of
>view, but it doesn't appear to happen with the newer toolchain I have
>here.  Will have to watch this.

As long as the entries line up, I don't think anyone will care whether
they are an "en" one way or the other (:-).

>>     On page 53 (3rd line), something is printing as a square (?).
>
>Again, some context would help me find this faster.

This problem seems to be pandemic.  Hmmmm.  As an experiment, I took
the Administrator's Guide and distilled it into PDF.  Looking at one
of the instances in question (page 57, section 5.3, "#Cyrillic recode
support#"), I see no squares, but I DO see that the spaces around the
text are wider than normal.  I then told Acrobat to print out the page;
the squares didn't show up there, either.  OK; let's look at the raw
PostScript:

...
2193 6403 M (described ) 567 X GR
0.0000 0.0000 0.0000 1.0000 SET_CMYK GS n
2763 6403 M (as ) 151 X GR
0.0000 0.0000 0.0000 1.0000 SET_CMYK GS n
2917 6403 M (\223Cyrillic ) 461 X GR
              ^^^^
0.0000 0.0000 0.0000 1.0000 SET_CMYK GS n
3381 6403 M (recode ) 405 X GR
0.0000 0.0000 0.0000 1.0000 SET_CMYK GS n
3789 6403 M (support\224 ) 450 X GR
                     ^^^^
0.0000 0.0000 0.0000 1.0000 SET_CMYK GS n
4242 6403 M (which ) 374 X GR
0.0000 0.0000 0.0000 1.0000 SET_CMYK GS
...

I dunno what \223 and \224 are supposed to be...

-r
--
email: rdm@cfcl.com; phone: +1 650-873-7841
http://www.cfcl.com/rdm - home page, resume, etc.
http://www.cfcl.com/Meta/md_fb.html - The FreeBSD Browser
http://www.ptf.com/tdc - Prime Time Freeware's Darwin Collection

Re: Documentation nits

From
Rich Morin
Date:
The peculiar codes (\223, \224) appear to be "character codes", but
not ones that seem very standardized.  The "PostScript Language
Reference Manual" (2nd Ed.) gives the following information:

   "E.6  StandardEncoding Encoding Vector", p. 598
   "E.9  Expert           Encoding Vector", p. 602
   "E.10 ExpertSubset     Encoding Vector", p. 603
   "E.12 Symbol           Encoding Vector", p. 606

      \223 and \224 are undefined

   "E.7 ISOLatin1Encoding Encoding Vector", p. 599

      \223 is a caret and \224 is a tilde

Could this be some sort of Micro$oft encoding?

-r
--
email: rdm@cfcl.com; phone: +1 650-873-7841
http://www.cfcl.com/rdm - home page, resume, etc.
http://www.cfcl.com/Meta/md_fb.html - The FreeBSD Browser
http://www.ptf.com/tdc - Prime Time Freeware's Darwin Collection

Re: Documentation nits

From
Peter Eisentraut
Date:
Rich Morin writes:

> It is a ToC entry, looking like
>
>    "12.1.7. The #random# test  ... 76"
>
> where the '#'s actually show up as squares.

Those are supposed to be double quotes.  It's possible that the
Microsoftish "smart quotes" snuck in here.  We'll be alert next time
around.

--
Peter Eisentraut   peter_e@gmx.net