First SVG graphic

classic Classic list List threaded Threaded
49 messages Options
123
Reply | Threaded
Open this post in threaded view
|

First SVG graphic

Jürgen Purtz
Please find in the attachment a SVG file which shows the internal
structure of PG's pages and a patch to insert it to "storage.sgml".
Because this is the first graphic for our documentation many additional
work must be done. SvgHandling.pdf explains how to create graphics and
integrate them into the textual description, which definitions are
actually missing (style guide?), and what problems may occur.

We shall create two new directories: doc/src/sgml/svg (as source
directory for all svg files) and doc/src/sgml/html/svg. The patch for
Makefile is also attached - HTML, PDF, and EPUB are tested. There is a
conceptual problem with single-page HTML. The SVG files keep separate
and I don't know how to include them into the generated single file
"postgres.html".

@Committers: If you tend to accept this patch, I will start to create
wiki-pages and additional documentation pages to describe the
proceeding. If you reject the patch, please give me a justification.

Kind regards

Jürgen Purtz






PageLayout.svg (4K) Download Attachment
patch.txt (3K) Download Attachment
SvgHandling.pdf (297K) Download Attachment
ScreenshotPDF.png (105K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Jürgen Purtz

After one week no response at all? Neither positive nor negative. It seems that the community has little interest in the SVG issue. Or in my suggestion?

Jürgen Purtz


Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Bruce Momjian
On Wed, Nov 28, 2018 at 06:34:26PM +0100, Jürgen Purtz wrote:
> After one week no response at all? Neither positive nor negative. It seems that
> the community has little interest in the SVG issue. Or in my suggestion?

I have been waiting for someone to take leadership on this important
topic, and have read your 11-page PDF with great interest.

I think your work flow on page 4 clearly illustrates that, even if we
store both native, e.g., Inkscape, and optimized SVG files, we are going
to have a problem.  If someone takes the optimized SVG file, loads it
into a tool other than the tool that created the original file, modifies
it, saves new native and optimized SVG files, and then someone goes back
to the original tool, the native file will not have the modifications
that were made by the new tool and in the new native SVG file.  This
suggests we should just use one tool to handle SVG files, probably
Inkscape.  We can consider other tools later, but let's just standardize
on one tool now and get going.  I realize you can import SVG files into
tools that did not create them, but it seems unlikely the new optimized
SVG file will appear similar to the old one.

As far as rendering in HTML, I think we have two choices:

1.  make images a link to an SVG file that can be rendered in a new
browser tab

2.  convert the SVG to PNG for HTML rendering.

I kind of prefer #2.

--
  Bruce Momjian  <[hidden email]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Bruce Momjian
On Wed, Nov 28, 2018 at 01:05:28PM -0500, Bruce Momjian wrote:
> On Wed, Nov 28, 2018 at 06:34:26PM +0100, Jürgen Purtz wrote:
> > After one week no response at all? Neither positive nor negative. It seems that
> > the community has little interest in the SVG issue. Or in my suggestion?
>
> I have been waiting for someone to take leadership on this important
> topic, and have read your 11-page PDF with great interest.

Also, I like your idea of a default Inkscape configuration file.

--
  Bruce Momjian  <[hidden email]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Andres Freund
In reply to this post by Jürgen Purtz
Hi,

On 2018-11-28 18:34:26 +0100, Jürgen Purtz wrote:
> After one week no response at all? Neither positive nor negative. It seems
> that the community has little interest in the SVG issue. Or in my
> suggestion?

I'd suggest describing your proposed workflow in sgml, not a pdf file.

Greetings,

Andres Freund

Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Bruce Momjian
On Wed, Nov 28, 2018 at 11:46:33AM -0800, Andres Freund wrote:
> Hi,
>
> On 2018-11-28 18:34:26 +0100, Jürgen Purtz wrote:
> > After one week no response at all? Neither positive nor negative. It seems
> > that the community has little interest in the SVG issue. Or in my
> > suggestion?
>
> I'd suggest describing your proposed workflow in sgml, not a pdf file.

Well, there were a number of images in the PDF that would be harder to
do in SGML.

--
  Bruce Momjian  <[hidden email]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Andres Freund
Hi,

On 2018-11-28 14:49:10 -0500, Bruce Momjian wrote:

> On Wed, Nov 28, 2018 at 11:46:33AM -0800, Andres Freund wrote:
> > Hi,
> >
> > On 2018-11-28 18:34:26 +0100, Jürgen Purtz wrote:
> > > After one week no response at all? Neither positive nor negative. It seems
> > > that the community has little interest in the SVG issue. Or in my
> > > suggestion?
> >
> > I'd suggest describing your proposed workflow in sgml, not a pdf file.
>
> Well, there were a number of images in the PDF that would be harder to
> do in SGML.

My point is that that description is going to be needed going forward,
and thus needs to be in a normal doc format. And if the graphics therein
are the first examples for graphics in PG docs, that works for me.

Greetings,

Andres Freund

Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Alvaro Herrera-9
In reply to this post by Bruce Momjian
On 2018-Nov-28, Bruce Momjian wrote:

> On Wed, Nov 28, 2018 at 11:46:33AM -0800, Andres Freund wrote:
> > Hi,
> >
> > On 2018-11-28 18:34:26 +0100, Jürgen Purtz wrote:
> > > After one week no response at all? Neither positive nor negative. It seems
> > > that the community has little interest in the SVG issue. Or in my
> > > suggestion?
> >
> > I'd suggest describing your proposed workflow in sgml, not a pdf file.
>
> Well, there were a number of images in the PDF that would be harder to
> do in SGML.

I think the point is how do you integrate the images from the SVG source
into the documentation output.  Presumably that won't be PDF, for
example the HTML output will not use a PDF as an image embedded in the
page.  It probably works ok for the PDF output (of the whole
documentation) to use the PDF of the image ... I suppose the HTML output
will need a PNG or such.

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

Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Magnus Hagander-2
On Wed, Nov 28, 2018 at 8:53 PM Alvaro Herrera <[hidden email]> wrote:
On 2018-Nov-28, Bruce Momjian wrote:

> On Wed, Nov 28, 2018 at 11:46:33AM -0800, Andres Freund wrote:
> > Hi,
> >
> > On 2018-11-28 18:34:26 +0100, Jürgen Purtz wrote:
> > > After one week no response at all? Neither positive nor negative. It seems
> > > that the community has little interest in the SVG issue. Or in my
> > > suggestion?
> >
> > I'd suggest describing your proposed workflow in sgml, not a pdf file.
>
> Well, there were a number of images in the PDF that would be harder to
> do in SGML.

I think the point is how do you integrate the images from the SVG source
into the documentation output.  Presumably that won't be PDF, for
example the HTML output will not use a PDF as an image embedded in the
page.  It probably works ok for the PDF output (of the whole
documentation) to use the PDF of the image ... I suppose the HTML output
will need a PNG or such.


If the source is SVG, why not just use SVG? SVG support in browsers has to be pushing 10 years now, shouldn't be a problem at all...  And SVG can be embedded in the HTML itself (whether that would work in this particular case I don't know, but in theory it can)

--
Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Tatsuo Ishii-3
> On Wed, Nov 28, 2018 at 8:53 PM Alvaro Herrera <[hidden email]>
> wrote:
>
>> On 2018-Nov-28, Bruce Momjian wrote:
>>
>> > On Wed, Nov 28, 2018 at 11:46:33AM -0800, Andres Freund wrote:
>> > > Hi,
>> > >
>> > > On 2018-11-28 18:34:26 +0100, Jürgen Purtz wrote:
>> > > > After one week no response at all? Neither positive nor negative. It
>> seems
>> > > > that the community has little interest in the SVG issue. Or in my
>> > > > suggestion?
>> > >
>> > > I'd suggest describing your proposed workflow in sgml, not a pdf file.
>> >
>> > Well, there were a number of images in the PDF that would be harder to
>> > do in SGML.
>>
>> I think the point is how do you integrate the images from the SVG source
>> into the documentation output.  Presumably that won't be PDF, for
>> example the HTML output will not use a PDF as an image embedded in the
>> page.  It probably works ok for the PDF output (of the whole
>> documentation) to use the PDF of the image ... I suppose the HTML output
>> will need a PNG or such.
>>
>>
> If the source is SVG, why not just use SVG? SVG support in browsers has to
> be pushing 10 years now, shouldn't be a problem at all...  And SVG can be
> embedded in the HTML itself (whether that would work in this particular
> case I don't know, but in theory it can)

+1.
--
Tatsuo Ishii
SRA OSS, Inc. Japan
English: http://www.sraoss.co.jp/index_en.php
Japanese:http://www.sraoss.co.jp

Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Craig Ringer-3
In reply to this post by Jürgen Purtz
On Thu, 29 Nov 2018 at 01:33, Jürgen Purtz <[hidden email]> wrote:

After one week no response at all? Neither positive nor negative. It seems that the community has little interest in the SVG issue. Or in my suggestion?


I'm excited you're doing it. I thought it was part of an existing/ongoing discussion and didn't really have much to say. I think it's a vital step forward and we really need to get some graphics into Pg.

Personally I want to let go a bit of the diff-able, merge-able requirements and accept that not everything plays well when hand written. I got tired of the arguments that seemed to require that no tool written since 1972 could be used in our source tree lest SunOS 0.9.ancient have a fit, or someone find a (gasp) binary in a diff.

So good on you for getting positive action rolling.

--
 Craig Ringer                   http://www.2ndQuadrant.com/
 PostgreSQL Development, 24x7 Support, Training & Services
Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Oleg Bartunov-3
In reply to this post by Jürgen Purtz
On Wed, Nov 28, 2018 at 8:33 PM Jürgen Purtz <[hidden email]> wrote:
>
> After one week no response at all? Neither positive nor negative. It seems that the community has little interest in the SVG issue. Or in my suggestion?

First of all, I am BIG + for having diagrams in our documentation.

I once estimated the number of diagrams in our official documentation
and it was only  50 or so, that means, it is possible to make them
more or less centralized, at least for the initial version. If Jurgen+
agree to work on this I would be happy to help them in the parts I was
working on. For the initial version we could even provide the
generated images along with SVG-source files.

>
> Jürgen Purtz
>
>


--
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company

Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Jürgen Purtz

I take the reactions of the last days as a strong consent to go on with the effort to integrate graphics into the documentation and use SVG as the language which creates such graphics. Also the proposed parallel handling of two SVG files - a rich but tool-specific version (optional and not normative) and a poor tool-independent version (mandatory and normative) - for the same graphic seems to be accepted. The community agrees that this way is not optimal because the use of different SVG-tools will lead to unnecessary problems - but there is no consensus about tools.

What shall we do next:

  • I will create one or more wiki pages where the procedure is described. Everybody can extend this pages or contribute to their discussion sites. The pages will be found in the category 'Documentation' and its subcategory 'SVG' (to be created).
  • Actually, we have the very simple example 'PageLayout.svg' and an example of medium complexity 'gin.svg'. For testing purposes we shall have a third one of high complexity and with many different graphical elements. Can someone send such an example - as a screenshot or in any other format?
  • I want to engage everybody to identify important issues of PG and visualize them (similar to Oleg's proposal). We will have a - possibly long lasting - period of experiments with different examples. I think, it's necessary that we make our experiences with different tools and proceedings (one person creates a graphic, another one contributes changes, using the same or a different tool, ...). Those examples shall not be pure academic use cases. They shall reflect real situations with the expectation to be included into the documentation - one day or another.
  • In the initial phase, it may be helpful to do some centralized clearings on the first SVG source files. 'Copy&Paste' is widely used and the first examples will have the meaning of a lighthouse.
  • I will contact our web-team to discuss style-guide related issues.


Kind regards, Jürgen


Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Bruce Momjian
On Fri, Nov 30, 2018 at 06:04:06PM +0100, Jürgen Purtz wrote:

> I take the reactions of the last days as a strong consent to go on with the
> effort to integrate graphics into the documentation and use SVG as the language
> which creates such graphics. Also the proposed parallel handling of two SVG
> files - a rich but tool-specific version (optional and not normative) and a
> poor tool-independent version (mandatory and normative) - for the same graphic
> seems to be accepted. The community agrees that this way is not optimal because
> the use of different SVG-tools will lead to unnecessary problems - but there is
> no consensus about tools.
>
> What shall we do next:
>
>   • I will create one or more wiki pages where the procedure is described.
>     Everybody can extend this pages or contribute to their discussion sites.
>     The pages will be found in the category 'Documentation' and its subcategory
>     'SVG' (to be created).
>   • Actually, we have the very simple example 'PageLayout.svg' and an example
>     of medium complexity 'gin.svg'. For testing purposes we shall have a third
>     one of high complexity and with many different graphical elements. Can
>     someone send such an example - as a screenshot or in any other format?
>   • I want to engage everybody to identify important issues of PG and visualize
>     them (similar to Oleg's proposal). We will have a - possibly long lasting -
>     period of experiments with different examples. I think, it's necessary that
>     we make our experiences with different tools and proceedings (one person
>     creates a graphic, another one contributes changes, using the same or a
>     different tool, ...). Those examples shall not be pure academic use cases.
>     They shall reflect real situations with the expectation to be included into
>     the documentation - one day or another.
>   • In the initial phase, it may be helpful to do some centralized clearings on
>     the first SVG source files. 'Copy&Paste' is widely used and the first
>     examples will have the meaning of a lighthouse.
>   • I will contact our web-team to discuss style-guide related issues.

Sounds good.  I have many xfig/SVG images in my presentations if you
want to use any of them:

        https://momjian.us/presentations

--
  Bruce Momjian  <[hidden email]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Jürgen Purtz
In reply to this post by Jürgen Purtz

> I will create one or more wiki pages where the procedure is described.
> Everybody can extend this pages or contribute to their discussion
> sites. The pages will be found in the category 'Documentation' and its
> subcategory 'SVG' (to be created).


The wiki pages are online: https://wiki.postgresql.org/wiki/Category:SVG


Kind regards

Jürgen Purtz



Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Jürgen Purtz
There are three wiki pages describing the procedure: general
description, Inkscape specifics, colors. You can find them in the
category SVG.

This mail has 3 SVG graphics attached, each in pure SVG and in Inksape
SVG format. Furthermore there is a patch for the Makefile and the
modifications to three sgml files, which are necessary to incorporate
the graphics.

Kind regards

Jürgen Purtz



gin.svg (8K) Download Attachment
gin_Inkscape.svg (11K) Download Attachment
PageLayout.svg (4K) Download Attachment
PageLayout_Inkscape.svg (6K) Download Attachment
pgDump.svg (5K) Download Attachment
pgDump_Inkscape.svg (7K) Download Attachment
patch.txt (5K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Jürgen Purtz
a) The "Entry tree" and the "Posting trees" of the graphic "gin.svg"
shows links not only from one tree-level to the next but also within
each level from node to node. Is that correct?

b) Is it worth to visualize PG's tree-implementation in a separate
graphic - or is it the same as in every other tree-implementation that
you have learned in your academic studies? If yes: in which chapter?

Kind regards, Jürgen

Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Jürgen Purtz
In reply to this post by Bruce Momjian

I failed to generate the "single HTML file".

The default Makefile task, which creates multiple HTML files, works properly, because it confines itself to create links to SVG files. The SVG structure keeps hidden to the Docbook validation and processing - Docbook recognises only some additional links. What I have tried to generate a single HTML file is the use of xi:XInclude before validating and further processing. In this case the SVG structure is visible to Docbook.

In general it is possible to use SVG within Docbook 4.x, if you switch the doctype to

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook SVG Module V1.1CR1//EN"
                         "http://www.oasis-open.org/docbook/xml/svg/1.1CR1/dbsvg.dtd" 

This is an Docbook 4.x extension (https://docbook.org/specs/wd-docbook-svg-1.1cr1) for SVG-integration. But it's only a working draft from 2004, it never reached the status of an official OASIS standard. As far as I have seen, it works (with some limitations), if the SVG data is an integral part of the xml/sgml source file. I failed to combine it with xi:XInclude. In opposite to this the combination of xi:XInclude, SVG, and Docbook 5.1 works well. In my opinion this results from the fact, that the structure of Docbook 4.x is based on a DTD, whereas Docbook 5.x uses Relax-NG (and generates xsd files out of rng). DTDs natively are not namespace-aware, you must do some trickery to handle namespaces. Docbook 5.x is not only namespace aware, it natively includes definitions for SVG and other important standards like MathML.

My questions to the community are:

  • Does anyone has an idea how to generate single HTML file in the actual situation?
  • Shall we delay the SVG integration until we have switched to Docbook 5.x? This task is a great step, but it must be done in any case, because Docbook 4.x is outdated since many years. Btw: Because of other problems (https://github.com/docbook/docbook/issues/74) it is likely that we cannot use 5.1 but have to wait for the upcoming release 5.2.

Kind regards

Jürgen Purtz


Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Jürgen Purtz

My questions to the community are:

  • Does anyone has an idea how to generate single HTML file in the actual situation?


Thanks to an additional template created by Alexander Lakhin, which extends the 'nochunk' stylesheet for SVG and MathML processing, it is now possible to create the "single HTML file" of our documentation including SVG. For me this is a working solution as long as we use Docbook 4. After the migration to Docbook 5, both languages as well as full namespace support will be natively included in Docbook.

Does anyone faced some more problems? Or can we start to include the three first SVG graphics into PG's documentation?

Kind regards

Jürgen Purtz




stylesheet-html-nochunk.patch (1009 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: First SVG graphic

Bruce Momjian
In reply to this post by Jürgen Purtz
On Sun, Dec 23, 2018 at 04:10:30PM +0100, Jürgen Purtz wrote:
> a) The "Entry tree" and the "Posting trees" of the graphic "gin.svg" shows
> links not only from one tree-level to the next but also within each level
> from node to node. Is that correct?
>
> b) Is it worth to visualize PG's tree-implementation in a separate graphic -
> or is it the same as in every other tree-implementation that you have
> learned in your academic studies? If yes: in which chapter?

I am CC'ing Oleg, Teodor, and Alexander, who can answer the first
question, and maybe the second.

--
  Bruce Momjian  <[hidden email]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

123