French PDF manual

Hi,

Michael Glaesemann asked me to share details about our toolchain to
build a french PDF manual. So here are the details.

We started by changing SGML files in a way that makes them syntactically
correct and valid with an XML toolchain :
- add <?xml... on the beginning of each file ;
- change </> tag with the correct ending one ;
- add / for unitary tags (xref for example) ;
- change <!entity with <!ENTITY ;
- *delete* standalone ignore and include tags but keep some of the
text ;
- put all id, linkend, endterm in lowercase ;
- etc (I probably have forgotten some).

Then we used XSLT stylesheets from the LFS project to build XHTML and
PDF manual. We used xsltproc and fop 0.20.5. And, after much tweaking
(to get good computeroutput, to fix columns' size of each table), we
finaly got this PDF :
http://docs.postgresqlfr.org/pgsql-8.1.3-fr/pg813.pdf

Of course, you've seen the only problem for your move to XML : we
deleted standalone tags. But I think the result deserv some more work. I
would be glad to work on this if you think this could be a useful
addition to the project.

FYI, building the PDF file take me about 6 minutes on a Athlon 2.2 GHz
with 1 GB of RAM. I think this is good news :) Bad news is it takes
about half an hour to build the HTML one... pretty ugly... I don't
really know why it takes so much time.

If you're still interested on this work, should I work on 8.1 branch or
on HEAD ?

Hope you find this useful and forgive my bad english,

Regards.

--
Guillaume.

Hi,

2006/5/4, Guillaume LELARGE <guillaume(dot)lelarge(at)gmail(dot)com>:
> [...]
> Of course, you've seen the only problem for your move to XML : we
> deleted standalone tags. But I think the result deserv some more work. I
> would be glad to work on this if you think this could be a useful
> addition to the project.
>

Well, it was really easy to do. Instead of putting standalone tags,
you just have to add a parameter and its value on each tag that
depends on the kind of document you build. For example, I put
'standalone="yes"' when I want that the tag's content only appears on
standalone mode and I put 'standalone="no"' when I want that the tag's
content only appears on book mode.

Then I give these parameters to xsltprc so that it knows which mode I ask.

http://svn.postgresqlfr.org/changeset/242 will give you every change I
made to make it work.

My PDF file is still the same but I can now build the INSTALL.html document :
http://docs.postgresqlfr.org/pgsql-8.1.3-fr-ng/standalone-install.html

I'm still willing to do or help you on this matter.

--
Guillaume.

Guillaume LELARGE wrote:
> We started by changing SGML files in a way that makes them
> syntactically correct and valid with an XML toolchain :

Well, you can go into the documentation source directory and type 'make
postgres.xml' to get an XML formatted DocBook file automatically.

It has occasionally been suggested to convert the source of the
documentation to XML, but while I'm not opposed to that, I don't see
any specific advantages coming from such a move.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Peter Eisentraut wrote:
> Guillaume LELARGE wrote:
> > We started by changing SGML files in a way that makes them
> > syntactically correct and valid with an XML toolchain :
>
> Well, you can go into the documentation source directory and type 'make
> postgres.xml' to get an XML formatted DocBook file automatically.
>
> It has occasionally been suggested to convert the source of the
> documentation to XML, but while I'm not opposed to that, I don't see
> any specific advantages coming from such a move.

It would allow us to use xml2po to maintain translations, for one.

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

Alvaro Herrera <alvherre(at)commandprompt(dot)com> writes:
> Peter Eisentraut wrote:
>> Well, you can go into the documentation source directory and type 'make
>> postgres.xml' to get an XML formatted DocBook file automatically.
>>
>> It has occasionally been suggested to convert the source of the
>> documentation to XML, but while I'm not opposed to that, I don't see
>> any specific advantages coming from such a move.

> It would allow us to use xml2po to maintain translations, for one.

Sounds like you can use that today, if you want to; it's just one extra
step. But would it really be helpful on the documentation? I see where
.po works for a lot of short, independent error messages, but I don't
see it being real useful for big manuscripts.

regards, tom lane

On 08/05/06, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Alvaro Herrera <alvherre(at)commandprompt(dot)com> writes:
> > Peter Eisentraut wrote:
> >> Well, you can go into the documentation source directory and type 'make
> >> postgres.xml' to get an XML formatted DocBook file automatically.
> >>
> >> It has occasionally been suggested to convert the source of the
> >> documentation to XML, but while I'm not opposed to that, I don't see
> >> any specific advantages coming from such a move.
>
> > It would allow us to use xml2po to maintain translations, for one.
>
> Sounds like you can use that today, if you want to; it's just one extra
> step. But would it really be helpful on the documentation? I see where
> .po works for a lot of short, independent error messages, but I don't
> see it being real useful for big manuscripts.
>

Hello! my name is Mario and I've been working in that. For learning
purposes I'm writing the FAQ in a xml document. And, like Alvaro said,
«it would allow us to use xml2po»

So, what can we use for big documents instead?

>

Peter Eisentraut a écrit :
> Guillaume LELARGE wrote:
>> We started by changing SGML files in a way that makes them
>> syntactically correct and valid with an XML toolchain :
>
> Well, you can go into the documentation source directory and type 'make
> postgres.xml' to get an XML formatted DocBook file automatically.
>
> It has occasionally been suggested to convert the source of the
> documentation to XML, but while I'm not opposed to that, I don't see
> any specific advantages coming from such a move.
>

The PDF manual available on the postgresql web site is quite difficult
to use. For example, take a look at table 9.5 (pages 125 and 126). Text
goes beyond the cells. It's really difficult to read it. Sometimes you
can't read the text because it goes beyond the page : see pages 223 and
345).

I think these are real important issues.

--
Guillaume.

Guillaume LELARGE wrote:
> The PDF manual available on the postgresql web site is quite
> difficult to use. For example, take a look at table 9.5 (pages 125
> and 126). Text goes beyond the cells. It's really difficult to read
> it. Sometimes you can't read the text because it goes beyond the page
> : see pages 223 and 345).
>
> I think these are real important issues.

Certainly, but what do they have to do with the question whether the
source format of the documentation should be XML or SGML?

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

2006/5/9, Peter Eisentraut <peter_e(at)gmx(dot)net>:
> Guillaume LELARGE wrote:
> > The PDF manual available on the postgresql web site is quite
> > difficult to use. For example, take a look at table 9.5 (pages 125
> > and 126). Text goes beyond the cells. It's really difficult to read
> > it. Sometimes you can't read the text because it goes beyond the page
> > : see pages 223 and 345).
> >
> > I think these are real important issues.
>
> Certainly, but what do they have to do with the question whether the
> source format of the documentation should be XML or SGML?
>

OK, I understand what you mean. I don't know if there is a fix for
this issue with sgml and the jade toolkit but I do know there is one
available with xml and the xsltproc toolkit. And I'm available to do
it.

If someone wants to work on sgml/jade/dsssl stylesheets to fix the
issues I talked earlier, great, good news. But I haven't seen anyone
talking about this. So perhaps, the good way to handle this is to go
the xml way.

Regards.

--
Guillaume.

Am Dienstag, 9. Mai 2006 11:19 schrieb Guillaume Lelarge:
> If someone wants to work on sgml/jade/dsssl stylesheets to fix the
> issues I talked earlier, great, good news. But I haven't seen anyone
> talking about this. So perhaps, the good way to handle this is to go
> the xml way.

I don't think you got my point. The SGML sources can be converted to XML
automatically. The fact that the XSLT toolchain might work better is no
reason to convert the sources manually.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Peter Eisentraut wrote:
> Am Dienstag, 9. Mai 2006 11:19 schrieb Guillaume Lelarge:
> > If someone wants to work on sgml/jade/dsssl stylesheets to fix the
> > issues I talked earlier, great, good news. But I haven't seen anyone
> > talking about this. So perhaps, the good way to handle this is to go
> > the xml way.
>
> I don't think you got my point. The SGML sources can be converted to XML
> automatically. The fact that the XSLT toolchain might work better is no
> reason to convert the sources manually.

I have a counter-question. What value is there in continuing to use
SGML?

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

2006/5/9, Peter Eisentraut <peter_e(at)gmx(dot)net>:
> Am Dienstag, 9. Mai 2006 11:19 schrieb Guillaume Lelarge:
> > If someone wants to work on sgml/jade/dsssl stylesheets to fix the
> > issues I talked earlier, great, good news. But I haven't seen anyone
> > talking about this. So perhaps, the good way to handle this is to go
> > the xml way.
>
> I don't think you got my point. The SGML sources can be converted to XML
> automatically. The fact that the XSLT toolchain might work better is no
> reason to convert the sources manually.
>

How do you take care of the columns' size in a table ? I use this :
<colspec colnum="1" colwidth="1.5*"/>
But I don't know if there is the same thing in SGML.

This is something you need to fix to get proper content in a table's cells.

--
Guillaume.

Am Dienstag, 9. Mai 2006 14:00 schrieb Guillaume Lelarge:
> How do you take care of the columns' size in a table ? I use this :
> <colspec colnum="1" colwidth="1.5*"/>
> But I don't know if there is the same thing in SGML.

DocBook is DocBook. It doesn't matter if it's written in SGML or XML.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Am Dienstag, 9. Mai 2006 13:40 schrieb Alvaro Herrera:
> I have a counter-question. What value is there in continuing to use
> SGML?

Tag reduction makes editing easier (for some).

There's the question whether all the files should be renamed to .xml.

Marked sections would need to be replaced with a profiling mechanism. The
mechanisms for this exist but they are not all that elegant.

I'm all in favor of considering a move to XML, but we need to work with the
facts.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Alvaro Herrera <alvherre(at)commandprompt(dot)com> writes:
> I have a counter-question. What value is there in continuing to use
> SGML?

We're already used to it, and it's not clear what we'd buy from the
effort of converting all our documentation.

regards, tom lane