Figures in docs

On Wed, Feb 17, 2016 at 4:17 AM, Tatsuo Ishii <ishii@postgresql.org> wrote:

It seems there's no figures/diagrams in our docs. I vaguely recall that
we used to have a few diagrams in our docs. If so, was there any
technical reason to remove them?

I don't know the reason, but it's shame, we are still in sgml !

We already do our translations (as others) in xml using custom scripting.
xml provides us better integration with available tools and ability to
insert graphics. Last time we asked in -docs about moving to xml and
Alexander demonstrated acceptable speed of xml build, but there were no
reply from Peter, who is (?) responsible for our documentation
infrastructure. Probably, we should just created a patch and submit to
commitfest. You can check this thread
/messages/by-id/1428009501118.85114@postgrespro.ru

On Wed, Feb 17, 2016 at 4:17 AM, Tatsuo Ishii <ishii@postgresql.org> wrote:

It seems there's no figures/diagrams in our docs. I vaguely recall that
we used to have a few diagrams in our docs. If so, was there any
technical reason to remove them?

I don't know the reason, but it's shame, we are still in sgml !

We already do our translations (as others) in xml using custom scripting.
xml provides us better integration with available tools and ability to
insert graphics. Last time we asked in -docs about moving to xml and
Alexander demonstrated acceptable speed of xml build, but there were no
reply from Peter, who is (?) responsible for our documentation
infrastructure. Probably, we should just created a patch and submit to
commitfest. You can check this thread
/messages/by-id/1428009501118.85114@postgrespro.ru

Well, there are some PostgreSQL doc translation projects are running
including translation for Japanese, which I am working on.

If we are going to change the manual format and/or the build system, I
need to confirm it does work for Japanese as well. In theory because
the Japanese translation project uses UTF-8, there should be no
problem as far as the whole build system works for UTF-8. But I want
to confirm first...

BTW, are you going to propose a mega patch which changes all the sgml
files to xml files?

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Hi.

In DocBook 4.2 sgml dtd, figure tag is supported already.
that was implemented for multi output format.

I remember that very old postgresql document has some picture (eg.
system architecture, ERD ...).
when release new version, these might be changed, nevertheless these can
not been.

this proposer is not about xml or sgml.
how can new figures be modified for new documents.

regards ioseph.

2016-02-17 (수), 08:26 +0300, Oleg Bartunov:

On Wed, Feb 17, 2016 at 4:17 AM, Tatsuo Ishii <ishii@postgresql.org>
wrote:
It seems there's no figures/diagrams in our docs. I vaguely
recall that
we used to have a few diagrams in our docs. If so, was there
any
technical reason to remove them?

I don't know the reason, but it's shame, we are still in sgml !

We already do our translations (as others) in xml using custom
scripting. xml provides us better integration with available tools
and ability to insert graphics. Last time we asked in -docs about
moving to xml and Alexander demonstrated acceptable speed of xml
build, but there were no reply from Peter, who is (?) responsible for
our documentation infrastructure. Probably, we should just created a
patch and submit to commitfest. You can check this thread
/messages/by-id/1428009501118.85114@postgrespro.ru

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

--
Sent via pgsql-hackers mailing list
(pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Hello,

In fact we use "make postgres.xml" to get a single XML, which we translate.
We convert it to .po using xml2po (with some modifications), and then
convert it back to xml (and then to sgml files with our custom script).
So we have not changed sgml to xml files, and if it's more appropriate
than having a single large XML, then we will propose a procedure to
perform such conversion (that will result in corresponding mega patch).

Best regards,
Alexander Lakhin

17.02.2016 08:41, Tatsuo Ishii пишет:

On Wed, Feb 17, 2016 at 4:17 AM, Tatsuo Ishii <ishii@postgresql.org> wrote:

It seems there's no figures/diagrams in our docs. I vaguely recall that
we used to have a few diagrams in our docs. If so, was there any
technical reason to remove them?

I don't know the reason, but it's shame, we are still in sgml !

We already do our translations (as others) in xml using custom scripting.
xml provides us better integration with available tools and ability to
insert graphics. Last time we asked in -docs about moving to xml and
Alexander demonstrated acceptable speed of xml build, but there were no
reply from Peter, who is (?) responsible for our documentation
infrastructure. Probably, we should just created a patch and submit to
commitfest. You can check this thread
/messages/by-id/1428009501118.85114@postgrespro.ru

Well, there are some PostgreSQL doc translation projects are running
including translation for Japanese, which I am working on.

If we are going to change the manual format and/or the build system, I
need to confirm it does work for Japanese as well. In theory because
the Japanese translation project uses UTF-8, there should be no
problem as far as the whole build system works for UTF-8. But I want
to confirm first...

BTW, are you going to propose a mega patch which changes all the sgml
files to xml files?

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Hi.

In DocBook 4.2 sgml dtd, figure tag is supported already.
that was implemented for multi output format.

Ok, there's no technical problems with figures then. MySQL docs has
some nice figures. I am jealous.

I remember that very old postgresql document has some picture (eg.
system architecture, ERD ...).

So it seems to be a matter of policy? At some point we prefer not to
include figures, maybe.

when release new version, these might be changed, nevertheless these can
not been.

this proposer is not about xml or sgml.
how can new figures be modified for new documents.

Keep the source files (LibreOffice Draw for example).

regards ioseph.

2016-02-17 (수), 08:26 +0300, Oleg Bartunov:

On Wed, Feb 17, 2016 at 4:17 AM, Tatsuo Ishii <ishii@postgresql.org>
wrote:
It seems there's no figures/diagrams in our docs. I vaguely
recall that
we used to have a few diagrams in our docs. If so, was there
any
technical reason to remove them?

I don't know the reason, but it's shame, we are still in sgml !

We already do our translations (as others) in xml using custom
scripting. xml provides us better integration with available tools
and ability to insert graphics. Last time we asked in -docs about
moving to xml and Alexander demonstrated acceptable speed of xml
build, but there were no reply from Peter, who is (?) responsible for
our documentation infrastructure. Probably, we should just created a
patch and submit to commitfest. You can check this thread
/messages/by-id/1428009501118.85114@postgrespro.ru

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

--
Sent via pgsql-hackers mailing list
(pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

17.02.2016 09:17, Tatsuo Ishii wrote:

Hi.

In DocBook 4.2 sgml dtd, figure tag is supported already.
that was implemented for multi output format.

Ok, there's no technical problems with figures then. MySQL docs has
some nice figures. I am jealous.

The "figure" tag is just a placeholder in the Docbook
(http://www.docbook.org/tdg/en/html/figure.html).
The question is what to place inside this tag: "graphic" (not inline),
"mediaobject/imageobject" (alternative object, supports inline contents
and SVG), or something else.
So you surely can insert some picture from an external file (.png,
.jpg), but if it could contain title or some labels that should be
translated, it's not a best solution.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 수, 2016-02-17 at 12:14 +0300, Alexander Lakhin wrote:

17.02.2016 09:17, Tatsuo Ishii wrote:

Hi.

In DocBook 4.2 sgml dtd, figure tag is supported already.
that was implemented for multi output format.

Ok, there's no technical problems with figures then. MySQL docs has
some nice figures. I am jealous.

The "figure" tag is just a placeholder in the Docbook
(http://www.docbook.org/tdg/en/html/figure.html).
The question is what to place inside this tag: "graphic" (not inline),
"mediaobject/imageobject" (alternative object, supports inline contents
and SVG), or something else.
So you surely can insert some picture from an external file (.png,
.jpg), but if it could contain title or some labels that should be
translated, it's not a best solution.

I want say, just about figure tag.
sgml document can include external image file.

in sgml

<para>
<figure>
<title>Some Image</title>
<graphic fileref="images/some_image.jpg">
</figure>
</para>

then make html command generate below html code

<P

<DIV

CLASS="FIGURE"

<A

NAME="AEN126265"

</A
<P
<B
Figure E-1. Some Image</B
</P
<P
<IMG

SRC="images/some_image.jpg"></P

so,
I asked how maintenance that some_image.jpg file.
I think that is so difficult, because new release document might change
these too.
if use svg module for docbook, document sources will are maked very
dirty.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 2/16/16 8:17 PM, Tatsuo Ishii wrote:

It seems there's no figures/diagrams in our docs. I vaguely recall that
we used to have a few diagrams in our docs. If so, was there any
technical reason to remove them?

Because no one has been able to propose a good format for storing and
editing pictures.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 18/02/16 10:38, Peter Eisentraut wrote:

On 2/16/16 8:17 PM, Tatsuo Ishii wrote:

It seems there's no figures/diagrams in our docs. I vaguely recall that
we used to have a few diagrams in our docs. If so, was there any
technical reason to remove them?

Because no one has been able to propose a good format for storing and
editing pictures.

SVG?

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Gavin Flower wrote:

On 18/02/16 10:38, Peter Eisentraut wrote:

On 2/16/16 8:17 PM, Tatsuo Ishii wrote:

It seems there's no figures/diagrams in our docs. I vaguely recall that
we used to have a few diagrams in our docs. If so, was there any
technical reason to remove them?

Because no one has been able to propose a good format for storing and
editing pictures.

SVG?

Did you read the quoted threads? In particular read the well-researched
thread started by Rafael Martinez some years ago.

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Gavin Flower wrote:

On 18/02/16 10:38, Peter Eisentraut wrote:

On 2/16/16 8:17 PM, Tatsuo Ishii wrote:

It seems there's no figures/diagrams in our docs. I vaguely recall that
we used to have a few diagrams in our docs. If so, was there any
technical reason to remove them?

Because no one has been able to propose a good format for storing and
editing pictures.

SVG?

Did you read the quoted threads? In particular read the well-researched
thread started by Rafael Martinez some years ago.

The end of the thread is here:
/messages/by-id/20120712181636.GC11063@momjian.us

It seems the discussion never reached to a conclusion.

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Gavin Flower wrote:

On 18/02/16 10:38, Peter Eisentraut wrote:

On 2/16/16 8:17 PM, Tatsuo Ishii wrote:

It seems there's no figures/diagrams in our docs. I vaguely recall that
we used to have a few diagrams in our docs. If so, was there any
technical reason to remove them?

Because no one has been able to propose a good format for storing and
editing pictures.

SVG?

Did you read the quoted threads? In particular read the well-researched
thread started by Rafael Martinez some years ago.

/messages/by-id/20120712181636.GC11063@momjian.us

It seems the discussion never reached to a conclusion.

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 2/16/16 8:17 PM, Tatsuo Ishii wrote:

It seems there's no figures/diagrams in our docs. I vaguely recall that
we used to have a few diagrams in our docs. If so, was there any
technical reason to remove them?

Because no one has been able to propose a good format for storing and
editing pictures.

What's wrong with LibreOffice?

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Tatsuo Ishii <ishii@postgresql.org> writes:

Because no one has been able to propose a good format for storing and
editing pictures.

What's wrong with LibreOffice?

Is there any reason to think it doesn't have the same disease mentioned
in the previously-cited thread, namely that any change trashes pretty
much the whole file?

That might be okay for things that we only change once every ten years
or so, but otherwise it would be very git-history-unfriendly.

It's possible that we could solve that with some sort of SVG normalizer
(think pgindent for SVG) that we're careful to use before committing.
But I'm afraid that we'd still have issues with significantly different
output from different versions of LibreOffice, for example.

regards, tom lane

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

What's wrong with LibreOffice?

Is there any reason to think it doesn't have the same disease mentioned
in the previously-cited thread, namely that any change trashes pretty
much the whole file?

That might be okay for things that we only change once every ten years
or so, but otherwise it would be very git-history-unfriendly.

It's possible that we could solve that with some sort of SVG normalizer
(think pgindent for SVG) that we're careful to use before committing.
But I'm afraid that we'd still have issues with significantly different
output from different versions of LibreOffice, for example.

Do we really need git history for each figure? It seems we are waiting
for a solution which will never realize.

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 2/17/16 8:23 PM, Tatsuo Ishii wrote:

Do we really need git history for each figure? It seems we are waiting
for a solution which will never realize.

What we need is tooling around a new file format that is similar or
analogous to our existing tooling, so that it is easy to edit, easy to
review, easy to build, easy to test, and so on. Otherwise, the image
files will not get maintained properly.

As an example, if an image contains text (e.g., a flow chart or
architecture diagram), then I expect that git grep will find it there,
so that I know to update it when I rename or augment something.

The above is all solvable. There are certainly image formats that fit
those descriptions.

Personally, I'd want to know specifically what images people would want,
so we could discuss or prototype something around that.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

What we need is tooling around a new file format that is similar or
analogous to our existing tooling, so that it is easy to edit, easy to
review, easy to build, easy to test, and so on. Otherwise, the image
files will not get maintained properly.

As an example, if an image contains text (e.g., a flow chart or
architecture diagram), then I expect that git grep will find it there,
so that I know to update it when I rename or augment something.

The above is all solvable. There are certainly image formats that fit
those descriptions.

Personally, I'd want to know specifically what images people would want,
so we could discuss or prototype something around that.

One of the diagrams I want to have is a query processing flowchart.

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers