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>
From: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Openpgp: preference=signencrypt
Autocrypt: addr=peter.eisentraut@2ndquadrant.com; prefer-encrypt=mutual;
 keydata=
 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
 3jI=
Organization: 2ndQuadrant
Message-ID: <4393cdcd-4efd-3198-4ffc-c080a5af79c7@2ndquadrant.com>
Date: Thu, 7 Feb 2019 12:06:14 +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: <5ad6b96d-47d0-eb08-edc4-803645d2fd31@purtz.de>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

First, let's fix some of these whitespace errors:

firstSvg_2.patch:677: trailing whitespace.
  <rect x="1" y="1" width="99.4%" height="99.4%" rx="1%"
firstSvg_2.patch:752: trailing whitespace.
  <rect x="1" y="1" width="99.4%" height="99.4%" rx="1%"
firstSvg_2.patch:705: new blank line at EOF.
+
firstSvg_2.patch:936: new blank line at EOF.
+
warning: 4 lines add whitespace errors.

Let's not use mixed-case file names:

Inkscape/
PageLayout.svg
gin.svg
pgDump.svg

> @@ -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.

The variable name SVGSRC is a bit confusing.  What is it the source of?

> @@ -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.

> + <part>
> +  <title>Lists of Figures, Tables and Examples</title>
> +  <appendix id="list-of-figures">
> +   <title>List of Figures</title>
> +   <para />
> +  </appendix>
> +  <appendix id="list-of-tables">
> +   <title>List of Tables</title>
> +   <para />
> +  </appendix>
> +  <appendix id="list-of-examples">
> +   <title>List of Examples</title>
> +   <para />
> +  </appendix>
> + </part>

These ought to be created by the stylesheet.  We have probably turned
them off somewhere, so you should see where you can turn them on.

> diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
> index 9e0bb93f08..d31ee2d210 100644
> --- a/doc/src/sgml/ref/pg_dump.sgml
> +++ b/doc/src/sgml/ref/pg_dump.sgml
> @@ -73,6 +73,21 @@
>     architectures.
>    </para>
>
> +  <figure id="pg_dump_svg">
> +   <title><command>pg_dump</command>: Formats and Restore Proceedings</title>

This doesn't work for man page output.

I think we should avoid putting images into reference pages.  This one
could perhaps go into the Backup chapter.

Also, it should be linked to from somewhere.  An image that's just
floating around and not referred to in the text seems odd.

Also we tend to use hyphens instead of underscores for IDs.  (At some
point, underscores where not allowed.  I'm surprised that that's no
longer the case.)  I also wouldn't put "_svg" into the ID.  The format
is irrelevant to the ID.

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