Horton

Thread

Commits

  1. Doc: render π more nicely in PDF output.

  1. Rendering pi more nicely in PDF

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-26T19:13:35Z

    In the department of nitpickery ...

"&pi;" renders poorly in our PDF docs: as shown in the attached
screenshot, it doesn't line up on the baseline.  I realized that
this is the same problem I'd run into recently with right-arrow,
and it can be solved in the same way, namely we have to specify
use of the symbol font explicitly.  So attached is a proposed
patch to fix it.

Use of a new processing-instruction might not be the most elegant
way to do this ... anyone have a better suggestion?

(BTW, I tried to use "&pi;" in the stylesheet files and it
didn't work; apparently that entity isn't loaded yet.)

			regards, tom lane

  2. Re: Rendering pi more nicely in PDF

    Alexander Law <exclusion@gmail.com> — 2020-04-27T05:00:01Z

    From the symbolic unit of the department...

Hello Tom,
26.04.2020 22:13, Tom Lane wrote:
> In the department of nitpickery ...
>
> "&pi;" renders poorly in our PDF docs: as shown in the attached
> screenshot, it doesn't line up on the baseline.  I realized that
> this is the same problem I'd run into recently with right-arrow,
> and it can be solved in the same way, namely we have to specify
> use of the symbol font explicitly.  So attached is a proposed
> patch to fix it.
>
> Use of a new processing-instruction might not be the most elegant
> way to do this ... anyone have a better suggestion?
I would use the phrase tag, which is intended for such uses: [1] [2].
The "phrase" sounds too generic, but it doesn't require yet another
processing instruction e.g. for &sum; or a similar entity.

[1] http://www.sagehill.net/docbookxsl/CustomInlines.html
[2] https://tdg.docbook.org/tdg/4.5/phrase.html

Best regards,
Alexander

  3. Re: Rendering pi more nicely in PDF

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-27T15:04:14Z

    Alexander Lakhin <exclusion@gmail.com> writes:
> 26.04.2020 22:13, Tom Lane wrote:
>> Use of a new processing-instruction might not be the most elegant
>> way to do this ... anyone have a better suggestion?

> I would use the phrase tag, which is intended for such uses: [1] [2].

Good idea, done that way.

> The "phrase" sounds too generic, but it doesn't require yet another
> processing instruction e.g. for &sum; or a similar entity.

Yeah, lack of easy applicability to other cases was the main thing
bothering me about the processing-instruction fix.

BTW, I tried to also use this <phrase> markup inside the template for
<returnvalue>, so we'd only need one font-switching special case not two.
Didn't work though --- apparently templates don't get applied recursively?
Oh well.

			regards, tom lane

  4. Re: Rendering pi more nicely in PDF

    Alexander Law <exclusion@gmail.com> — 2020-04-27T16:00:01Z

    27.04.2020 18:04, Tom Lane wrote:
> Alexander Lakhin <exclusion@gmail.com> writes:
>> 26.04.2020 22:13, Tom Lane wrote:
>> BTW, I tried to also use this <phrase> markup inside the template for
>> <returnvalue>, so we'd only need one font-switching special case not two.
>> Didn't work though --- apparently templates don't get applied recursively?
>> Oh well.
We can have a single template "symbol_font" and reuse it, but it doesn't
seem cleaner to me (for just two cases).
(Placing <phrase ...>  into <xsl:template match="returnvalue"> wouldn't
work as such a content goes into the output, whilst all xsl:templates
apply to the input tree.)

Best regards,
Alexander

  5. Re: Rendering pi more nicely in PDF

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-27T16:24:00Z

    Alexander Lakhin <exclusion@gmail.com> writes:
> 27.04.2020 18:04, Tom Lane wrote:
>> BTW, I tried to also use this <phrase> markup inside the template for
>> <returnvalue>, so we'd only need one font-switching special case not two.
>> Didn't work though --- apparently templates don't get applied recursively?

> We can have a single template "symbol_font" and reuse it, but it doesn't
> seem cleaner to me (for just two cases).

Yeah, I agree, that's not an improvement.  It's invoking the template
two different ways, which seems pretty weird (at least to an XSL novice
like me).

			regards, tom lane

  6. Re: Rendering pi more nicely in PDF

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2020-04-29T18:59:07Z

    On 2020-04-26 21:13, Tom Lane wrote:
> "&pi;" renders poorly in our PDF docs: as shown in the attached
> screenshot, it doesn't line up on the baseline.  I realized that
> this is the same problem I'd run into recently with right-arrow,
> and it can be solved in the same way, namely we have to specify
> use of the symbol font explicitly.  So attached is a proposed
> patch to fix it.

The real problem here is that the default font (Times or Times New 
Roman) embedded in PDF readers doesn't have these off-the-beaten-path 
glyphs.  I'm surprised you see anything at all.  The fix is to use a 
different font with more glyphs.  I looked into that some time ago 
because this also effects the contributors list in the release notes, 
which has to be dumbed down because of this.

To use a different font, you have to (a) pick one, and (b) install it 
locally when you build the PDFs.

My proposal is to use the DejaVu fonts, which are open source and easily 
available for common operating systems.  (Arguably, they also give the 
documentation a slightly fresher look.)

The attached patch implements this.  You just have to install the fonts 
somehow.  Red Hat and Debian should have packages for this.  We should 
write instructions for this in any case.

(With this you can undo the other patches discussed here and just write 
&pi; and it should look correctly.)

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

  7. Re: Rendering pi more nicely in PDF

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-29T19:58:26Z

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> On 2020-04-26 21:13, Tom Lane wrote:
>> "&pi;" renders poorly in our PDF docs: as shown in the attached
>> screenshot, it doesn't line up on the baseline.

> The real problem here is that the default font (Times or Times New 
> Roman) embedded in PDF readers doesn't have these off-the-beaten-path 
> glyphs.  I'm surprised you see anything at all.

Well, I do ...

> My proposal is to use the DejaVu fonts, which are open source and easily 
> available for common operating systems.  (Arguably, they also give the 
> documentation a slightly fresher look.)
> The attached patch implements this.  You just have to install the fonts 
> somehow.  Red Hat and Debian should have packages for this.  We should 
> write instructions for this in any case.

I think making the built documentation depend on nonstandard fonts
is a truly awful idea.  It'd be okay perhaps if the requirement only
applied to people building the docs, but won't the requirement also
flow through to end users?

			regards, tom lane

  8. Re: Rendering pi more nicely in PDF

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2020-04-29T20:28:22Z

    On 2020-04-29 21:58, Tom Lane wrote:
> I think making the built documentation depend on nonstandard fonts
> is a truly awful idea.  It'd be okay perhaps if the requirement only
> applied to people building the docs, but won't the requirement also
> flow through to end users?

No, the font is embedded into the built PDF.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

  9. Re: Rendering pi more nicely in PDF

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-29T20:44:57Z

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> On 2020-04-29 21:58, Tom Lane wrote:
>> I think making the built documentation depend on nonstandard fonts
>> is a truly awful idea.  It'd be okay perhaps if the requirement only
>> applied to people building the docs, but won't the requirement also
>> flow through to end users?

> No, the font is embedded into the built PDF.

Ah.  Well, if it doesn't enlarge the file very much, I guess that'd
be fine.

			regards, tom lane

  10. Re: Rendering pi more nicely in PDF

    Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-04-29T21:23:31Z

    On 2020-Apr-29, Peter Eisentraut wrote:

> To use a different font, you have to (a) pick one, and (b) install it
> locally when you build the PDFs.
> 
> My proposal is to use the DejaVu fonts, which are open source and easily
> available for common operating systems.  (Arguably, they also give the
> documentation a slightly fresher look.)
> 
> The attached patch implements this.  You just have to install the fonts
> somehow.  Red Hat and Debian should have packages for this.  We should write
> instructions for this in any case.

It's not easy to build the PDF with this. There's a stray > in fop.xml.
After fixing that, I get a warning about fontbox java lib not being installed.
OK, I can install libfontbox-java and that one disappears.  Then there's
this other warning:

[warning] /usr/bin/fop: JVM flavor 'sun' not understood

which seems to be innocuous.  The build it still dies because of a CFF
type1 something or other:

Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/fontbox/cff/CFFType1Font
        at org.apache.fop.fonts.truetype.OTFFile.isType1(OTFFile.java:151)

After a quick search I found this bug
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=584472
which suggests that I patch /usr/bin/fop to find_jars in "fontbox2"
instead of fontbox.  OK, remove package libfontbox-java, patch the
script, try again.  Now it seems to work, and the doc looks pretty.

But apparently it's not sufficient -- the new font is not used
everywhere.  For example footnotes seem to use a different font than the
main body of text.  (I altered the fontname to Gentium, which I like
better, and uses a different glyph for "g" which is easy to spot ... and
notably absent in footnote in page 5 under 1.4 Accessing a Database.)

I +1 the idea of using a more complete font if it means we can render
contributor names better, though :-)

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

  11. Re: Rendering pi more nicely in PDF

    Alexander Law <exclusion@gmail.com> — 2020-04-30T04:00:07Z

    Hello hackers,

30.04.2020 00:23, Alvaro Herrera wrote:
> But apparently it's not sufficient -- the new font is not used
> everywhere.  For example footnotes seem to use a different font than the
> main body of text.  (I altered the fontname to Gentium, which I like
> better, and uses a different glyph for "g" which is easy to spot ... and
> notably absent in footnote in page 5 under 1.4 Accessing a Database.)
>
> I +1 the idea of using a more complete font if it means we can render
> contributor names better, though :-)
We at Postgres Pro use the attached fop-config.xml (passed to fop as "-c
.../fop-config.xml"). Please try it and see, whether the glyphs rendered
as expected.
You can also look at the generated pdf:
https://postgrespro.com/media/docs/postgresql/12/en/postgres-A4.pdf
But π (pi) is still rendered unusual as you can see on the page 179, so
I would prefer the symbol font anyway.

Best regards,
Alexander