Subject: Re: First SVG graphic
To: =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de>,
 pgsql-docs@lists.postgresql.org
References: <0e0b8e73-cc7c-0557-c76f-35d9592eb50e@purtz.de>
 <e7a76303-c2fb-afba-5dd2-9ef30f2983c4@purtz.de>
 <20190117174053.GC10895@momjian.us>
 <20190118.074307.1409947743977067766.t-ishii@sraoss.co.jp>
 <2e5ef806-c4f8-3fe7-e9a4-4fcfd124568e@purtz.de>
 <20190123235312.GB8334@momjian.us>
 <6a97acaf-06e8-519c-a4ff-04a13e0d2675@2ndquadrant.com>
 <5ad6b96d-47d0-eb08-edc4-803645d2fd31@purtz.de>
 <4393cdcd-4efd-3198-4ffc-c080a5af79c7@2ndquadrant.com>
 <e5e6fa66-80b5-1225-8d22-07897435d0e2@purtz.de>
From: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Openpgp: preference=signencrypt
Autocrypt: addr=peter.eisentraut@2ndquadrant.com; prefer-encrypt=mutual;
 keydata=
 xsFNBFUUt6kBEADZd9NNTBJbHmAXXJgPGOdd6Q73l80oifIVgn2tRxP9dYkCfTlo/yLqbKTl
 JNqTcyM6XrJDnB2sMEUGYCewYZXl+9C4bBJWyNqcEI1ae9u71vEq/fknFLArJ+2wN+f7QuRx
 Q8d94ZJAiJQ5g3fNk2HVeedCQCKP5dCzU+ZLt2dbsx1PDZLjTO9gf+JswWuGFb5wY5PZVM5V
 hq66Xk7ZJzHuARacza2RT7J2fkMmQBY+kr7L98Perb0GhafnlhXB0PvUB+N3xpmggMfwuhTu
 BngS/G/r3GvemxJuFxouw8xsMqrsfdksJXA2gLXYtwRCssdPV3PO0rlD9twqDo8URfIJ5fb6
 1g/MV8aTOKjg3Q8MpJPtkwJqN4o3PvbwYdedeFnOVkkYAJdu/aX1v1BeCBDu7Hy3sF52scD3
 pQbyQSl9vUDpTLarASAxNbAV0NRJE8dp4vfW6AH1ccryGiFqw/czPK/iN0+MT8wsjAW6WW4w
 hvjm5UPA1KTwi3ZT8eT5uycuH7QpuNk7LnGGXQ6KaRALFywzkr0A0V0AvFNa+l4wstMaXaB6
 dmMXyF0/hfryqyOeu1gAdq4q0/PNC2dPgb/6uoh4eMjN6A5GXcprilhz5DulmsilY21hfSoU
 S64ODed96pKhprsOxjZiDRsN1QM5MwB+uwVWUNfsX7fIxE0BrwARAQABzSdQZXRlciBFaXNl
 bnRyYXV0IDxwZXRlckBlaXNlbnRyYXV0Lm9yZz7CwXoEEwEIACQCGwMFCwkIBwMFFQoJCAsF
 FgIDAQACHgECF4AFAlUUuKQCGQEACgkQoZ8SQ+xBJp8llw//RbGoXnF72FZTlOFsnNyxnWbF
 vViPCfdAlZl1GGK9OYCvV1dp/956HuhB0wpaGQHiBmQfOPJf/jLOPjXFYm2iEChEycrBChuE
 j4TSYemMp5BSPILYk9Uwd16kVD/+U6fQfK6H5pOhfBvbM6asMnmpY2wQuvktxHvaGlytFw84
 EzFWNZtAZfxkw28w3AhIQkKe9hJanfyDL750RcbyEr8AAHty5IErrvS7tM5vQwIeh5BF26ND
 CyKPRdZgOgMpcwFfROKBDpAt052CgWIpNdhBdfIKlkCs4/ILxmC3rT/Mb/qZiHcoMMwEu6k+
 T7vRAFZZAk62Yrr/U8/vUGKlzRZQoo86fyojCfI0ibCIc0z8rwCVY9P40G9wD9BTCZS/z8Vh
 jjpBlNnIKw2hM6hbxavKndCJjFFJD08rXrTyrLF/of18xD37vNdYooP9VATB5QjOWFRrscSZ
 4a89e+to3m7YVnd4xdXwGp47dYusoax84C8tg1gZrH38ol9dPmnKX6GZrXeS7tH9k8VeUpJ8
 HQbRThQRWAT936QpYbLConBmOtmbLmjQOGtiXPo1oK57X/7U/WBja5vWmm2q+Yxtt+3uHGVg
 DdDU4CJpXo4lX0v2n3QV5EBSW9hjdF3bNfl6GFBb1pPEhqNcMDUc7zkx/2uENdAdk/BnqMgH
 umip7b0pVfvOwU0EVRS3qQEQAJf6p0P7D+hMYUgCPkvgrcz6OJYsAYdUMUmokfqmkKwK0oJM
 ew8TNGM53ocKAgQGma5f10rwbZNPlpVPNRX5hwUmwVlcwSut0oE+JfUBH7mpysWvpF05RKIy
 q9RCoJZrAbXS7Tig56A1QD8IcM00rERZMcCOlI1+q9m4u9AOI+0LyGGSH+VvoyDHD/Jew4R2
 TmPEF8Pu7lYiNYK88Q6u0kBkc+Tz3BNlyc6fi3HxnFfp0b75HLXPSTu2SwA/0Q31wHZXwrEU
 BR9KgSn/qbgy8ydPc97i82fhiFE3cbGexfPrQSMYmDGi+dcQ0s+AMQwC3XyMC0JkHpYUuFkR
 QdlIvaIhgFUUN2Vr4xF2ADaNTNFc4DYaiPHFAgHZw+3pZWqS4uIiWgJynrEaHw4F3QWU8/JB
 iyEWDhNq4WBrRA0u914TCCAoFOOKMnRdl8eJrRQKM/5/lXbHFjjlI/LDKhLRFsuQsnJJ3331
 RjCzpHPZG5/p5KR1RHiAXa0p/DW5lXyq21hS3kjDlleoHqOxCN/cy0Jgz7qLDq1vZoCl67Sy
 RAH60c2Xu4may9SVltmot0OzWVHdrfS+85FQGp9580DaeLio7YMFKy2bfEvwQJ/c9xD2QPB+
 oSb3V8ueSznXBG5+dyfOsZFRPxceA0wA2rSWZSjxLdKxvyGTj9vsCjaDu13rABEBAAHCwV8E
 GAEIAAkFAlUUt6kCGwwACgkQoZ8SQ+xBJp+HJhAAxmSTsC5y7p9Zu+nnLpucv/h88oEx985e
 qWeXzQiwM3pfRZS+PdTH9TyzHK0KOgKoAiubk0vt+BrT91D9d0G5kVQaTctAErGBoMkTaZJT
 XVEcNphiPzysdSqvprjojMp1y7rG8AP+Xd6m0rE1LRnkRRm8HyI8vdXsuLQPITGWXDLMjaNq
 AOV3BUnzkgtjMuIYw7SCr+12ZOb5dEKvaG4kjC4kaJ/TLbuBhVANcXkC90yp0AOZLs/cB1Dj
 OAXno/RUUruJ3r27a+pFv768UAi9QWcdw58yPxreMNMLqAgsS9oTHwHfGNWcB2dJ4UW+GMLJ
 hTf9TjQ2f+N/sIx5XMQ9pYw6CAJMK29qPx6/ZayrPxf22EXf0D3zTwIEZgwfSkynFVwV25L7
 awQq60fifdMYheSxq7GbhpsixmcD+e161cCmLIt75YDt5bQ0B1yf7EmxG8n7pGZAOM6LoNsU
 fkSldba5XVwh8LuN5mK0nQBELGW6Os4TDq4REggLpfcvFC215zpuo0iCGnmE/Bns4nowqUSP
 u4tkWL+nxW4qgv8wo8HJ52jd79EJ8iqfIBoidBfy9AIUiEUApGQzWPu6yWcI8fY0rN5D+tc+
 Yw1Zt6Mm+huYJpgCRsTcfzEcahnBn521CWcWvhW1ff3KFileFMtNmnBBhMncmRKHphtTKEpN
 3jI=
Organization: 2ndQuadrant
Message-ID: <55a6a8cb-bfaa-e5a6-4596-82f445f1ec7c@2ndquadrant.com>
Date: Fri, 8 Feb 2019 09:01:09 +0100
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.13; rv:52.0)
 Gecko/20100101 Thunderbird/52.9.1
MIME-Version: 1.0
In-Reply-To: <e5e6fa66-80b5-1225-8d22-07897435d0e2@purtz.de>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 8bit
Precedence: bulk

On 07/02/2019 18:11, Jürgen Purtz wrote:
>>> @@ -152,15 +156,15 @@ postgres.txt: postgres.html
>>>  postgres.pdf:
>>>   $(error Invalid target;  use postgres-A4.pdf or postgres-US.pdf as targets)
>>>
>>> -%-A4.fo: stylesheet-fo.xsl %.sgml $(ALLSGML)
>>> +%-A4.fo: stylesheet-fo.xsl %.sgml
>>>   $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
>>>   $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $(wordlist 1,2,$^)
>>>
>>> -%-US.fo: stylesheet-fo.xsl %.sgml $(ALLSGML)
>>> +%-US.fo: stylesheet-fo.xsl %.sgml
>>>   $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
>>>   $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
>>>
>>> -%.pdf: %.fo
>>> +%.pdf: %.fo $(ALLSGML) $(SVGSRC)
>>>   $(FOP) -fo $< -pdf $@
>>>
>> This seems a bit wrong.  The .fo target does depend on ALLSGML.  The
>> .pdf target does not, but it presumably does depend on SVGSRC.
> It's a transitive dependency: the pdf target is triggered after changes
> in svg (or sgml), this triggers the fo targets. Therefore it's not
> necessary to have svg (or sgml) dependencies at the fo level.

If $(ALLSGML) changes, then the .fo file needs to be rebuilt.  If
$(SVGSRC) changes, then the .pdf file needs to be rebuilt.  So those two
groups of files need to be handled differently.  The way you have
written it, a change in $(ALLSGML) will just rebuild the .pdf file from
a stale .fo.

>> The variable name SVGSRC is a bit confusing.  What is it the source of?
> The variable SVGSRC points to all svg-files, similar to ALLSGML which
> points to the sgml files. Whenever any of them changes, certain targets
> will fire.

Right, so maybe name it ALLSVG?

>>> @@ -209,7 +213,7 @@ check: postgres.sgml $(ALLSGML) check-tabs
>>>  install: install-html install-man
>>>
>>>  installdirs:
>>> - $(MKDIR_P) '$(DESTDIR)$(htmldir)'/html $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum))
>>> + $(MKDIR_P) '$(DESTDIR)$(htmldir)'/html/svg html/svg $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum))
>>>
>>>  # If the install used a man directory shared with other applications, this will remove all files.
>>>  uninstall:
>> html/svg is not an installation directory.  You need to create it
>> somewhere else.
> Please help. I haven't understood the distinction between installation
> directory and DESTDIR. On the other hand, in the Makefile there is a -
> redundant - command within the html-stamp target: $(MKDIR_P) html/svg.
> But this will run frequently, which is not necessary.

Right, so you probably don't need this change in the installdirs target
at all.

> There is a simple mechanism to create those list of figures: change line
> 55 of stylesheet-html-common.xsl to "book      toc,title,*figure*". But
> the result is ugly - see attached screenshot. The list is out-of-line.
> Additionally, in the future we will have many figures (and examples and
> tables). This will lead to similar problems we actually faced with the
> release notes.

Maybe we don't need a list of figures at all?  Let's just turn it off if
we don't like it.

> What is the problem here? Actually I don't have enough time to evaluate
> it in deep. If it is an urgent problem (I have seen that the
> commitfest-entry is tagged as "release 12") we shall shift the pg_dump
> figure to a later release.

The problem is that images don't show up in man pages, so we can't put
any images in there, or it will look silly.

> I think that the Backup chapter isn't a good place for this because it
> does not explain the complete interaction between pg_dump, psql and restore.

Then maybe it should explain it.  The pg_dump man page should be
strictly about pg_dump.  The Backup chapter should explain how it fits
together with the other tools.

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