Обсуждение: Figures in docs

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?

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

> 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
> http://www.postgresql.org/message-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

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
> http://www.postgresql.org/message-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
> 
> 

> 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
>> http://www.postgresql.org/message-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
>>
>>
>
>

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.

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
>> http://www.postgresql.org/message-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

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.

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.

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?

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

> 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:
http://www.postgresql.org/message-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

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

http://www.postgresql.org/message-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

> 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

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

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

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.

> 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