Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtp (Exim 4.84_2) (envelope-from ) id 1atLJK-0002Jp-P2 for pgsql-docs@arkaria.postgresql.org; Thu, 21 Apr 2016 20:34:51 +0000 Received: from localhost ([127.0.0.1] helo=postgresql.org) by malur.postgresql.org with smtp (Exim 4.84_2) (envelope-from ) id 1atLJK-0007QG-Bc for pgsql-docs@arkaria.postgresql.org; Thu, 21 Apr 2016 20:34:50 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1asuX9-0000mv-Qb for pgsql-docs@postgresql.org; Wed, 20 Apr 2016 15:59:19 +0000 Received: from mail-lf0-x244.google.com ([2a00:1450:4010:c07::244]) by magus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.84_2) (envelope-from ) id 1asuWy-0002Cn-7e for pgsql-docs@postgresql.org; Wed, 20 Apr 2016 15:59:12 +0000 Received: by mail-lf0-x244.google.com with SMTP id p64so5922277lfg.0 for ; Wed, 20 Apr 2016 08:59:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=subject:to:references:from:message-id:date:user-agent:mime-version :in-reply-to; bh=o0F+9ZCqYF8c05/rzmzzdivN0xMRZoumXFeFgCsLuSE=; b=CkxflFdlQVEuvbAcLUHJzifuKID6tp1P6D9h5bs6pI5N5u6EsxDeDEORC3sIuDevNW DJIzfWktGCYAdmb3RGEi1X1kBd6YC32zAgF2hgGV3yRSm1bbPmR37YPsZlaRI/NNZKPe gFKZSFAA3d7kCzfC1YD0NX1k/HrXj8uv+EytxONlMkCzWeW126LJLpt4Ikx0eMzLf47v ySBArq8z/MxIAs311Fyv3lSCv9lWVoOxNKVc0f+t5ql4fGOreQkJVbp1HqESzt8RpgTs piiCSxN3Oj5wHYuq2BToqcLByhV8zpdbIemVyv2KoeLFefUsQjHebxH+R/Qb/Gh8mvPJ ZiTA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:subject:to:references:from:message-id:date :user-agent:mime-version:in-reply-to; bh=o0F+9ZCqYF8c05/rzmzzdivN0xMRZoumXFeFgCsLuSE=; b=aqS5ruxQfcl5CZvzsMSi6vCUiozK3QT5vV4bC7VI9iykWK3e9bAhm3MPrqBGeEqhv4 ncO3Nw1vCn1NiccO9J/UR8jcVVtA6VoAiXiL87vw7txMRmTF/+bFRt7/Mz9t3qb1Karz f/p7rj3FuDJlXEN+gprsH3OhujwGcXThVC13S+WzccCLluBasw7kamBjqJtyKbLsFiMp Lxhj0K733kjguB2od8ms8ynJyvHd0/cWyC+9L4/DVhiL1Uti2kD5H8+7+B2pFjjphubQ yLP6h1YOIwgS7aH9aw7uU0pB4VQqf1FuKn7Fbhm0sr78yS1z7XoaRlu5g7xAWDZgBY58 104Q== X-Gm-Message-State: AOPr4FWJbXL403c3nsBDtf8M309krB03C0ZNzwnR5UlDoF4DvAANuziiekfN75bFULillw== X-Received: by 10.25.142.137 with SMTP id q131mr3446259lfd.10.1461167947637; Wed, 20 Apr 2016 08:59:07 -0700 (PDT) Received: from [1.0.0.7] ([109.196.196.67]) by smtp.gmail.com with ESMTPSA id d199sm1210750lfg.4.2016.04.20.08.59.06 (version=TLSv1/SSLv3 cipher=OTHER); Wed, 20 Apr 2016 08:59:06 -0700 (PDT) Subject: Re: Docbook 5.x To: =?UTF-8?Q?J=c3=bcrgen_Purtz?= , pgsql-docs@postgresql.org References: <57179283.6080704@purtz.de> From: Alexander Law Message-ID: <5717A749.9010206@gmail.com> Date: Wed, 20 Apr 2016 18:59:05 +0300 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.6.0 MIME-Version: 1.0 In-Reply-To: <57179283.6080704@purtz.de> Content-Type: multipart/alternative; boundary="------------000604030709070307060105" X-Pg-Spam-Score: -2.7 (--) List-Archive: List-Help: List-ID: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: X-Mailing-List: pgsql-docs Precedence: bulk Sender: pgsql-docs-owner@postgresql.org This is a multi-part message in MIME format. --------------000604030709070307060105 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit Hello Jürgen, Please look at the discussion that we had some time ago: http://www.postgresql.org/message-id/56337365.2080104@postgrespro.ru And we (postgrespro) still have plans to migrate to XML as soon as we get documentation translated. We had no issues with SGML->XML conversion, "make postgres.xml" creates XML (with entities and alike), which we use. When you talking about "conversion of html, fo, pdf, ..." do you mean using docs/sgml/Makefile or some other scripts? As to conversion SGML to XML, we need to decide whether to generate a single XML, or a set of XMLs (corresponding to current SGMLs). In the latter case - how to include XML-fragments into the main document (as entities or with xi:include)? Please, can you explain what are "Docbooks xslt-migration scripts"? Is Docbook 4.x incompatible with Docbook 5.x and we need to convert it additionally? Best regards, Alexander ----- Alexander Lakhin Postgres Professional: http://www.postgrespro.com The Russian Postgres Company 20.04.2016 17:30, Jürgen Purtz пишет: > Hi, > actually we use DocBook V4.2 for the PostgreSQL manuals. I suggest an > upgrade to DocBook 5.x. This sounds simple, but it will be a long > process with many sub-tasks. > > Rationale: > > * Sooner or later we MUST migrate as the 4.x series is outdated: > V4.2 dates back to 2002. The 4.x series is no longer actively > developed since 2006. See: > http://www.docbook.org/tdg5/en/html/ch01.html "In October 2006, > the DocBook Technical Committee released DocBook V4.5, the last > release planned in the 4.x series." > * V5.0 is available since 2009. See: > http://www.docbook.org/tdg5/en/html/ch01.html: "DocBook V5.0 > became an official Committee Specification in June 2009 and became > an officia7l OASIS Standard in October 2009." > * Actually the technical committee has the third Candidate Release > for V5.1. > > > PROs: > > * The formal part of the migration is supported by existing tools: > http://docbook.org/docs/howto/#convert4to5 (nevertheless some > scripts written by ourself will be necessary). > * The normative schema for Docbook 5.x is written in RELAX NG. > Additionally the technical committee converts this normative > schema to a XSD schema and to DTD, which are not normative but > very near to RELAX NG and will fit for most applications. Hence, > we have the choice between three schema syntaxes and everybody can > use his favourite one. > * Our source file format will switch from SGML to XML. This implies > that we have access to all XML features like XLink, XPath, XSLT, > XSL-FO, SVG, MathML, namespaces, ... . > > CONs: > > * The migration from 4.x to 5.x implies major changes at 3 different > levels. > o DocBook structure: Previously it was defined in SGML syntax > (DTD). Now it is defined in RELAX NG schema language plus > Schematron rules. > o DocBook files: Previously we used SGML syntax for our files. > We must convert them to a valid XML syntax, eg: tag omission. > o Tools and style sheets: All tools which operate at the native > SGML-level (editors, conversions, ...) must be replaced by XML > conforming tools. As valid XML implicitly conforms to a valid > SGML syntax this step may be accomplished by reconfiguring > some of the tools, eg.: .emacs. > > What I have done so far is: > > * Conversion of sgml files to valid xml syntax with a perl skript. I > failed to use 'osx' or 'spam'. > * Conversion of these xml files to Docbook5.x format using xsltproc > and Docbooks xslt-migration skripts. > * Creation of html files using xsltproc and Docbooks xslt skripts. > * Creation of fo files using xsltproc and Docbooks xslt skripts. > * Creation of pdf files using fop. > * The conversions needs less than 10 minutes on a Intel i5 processor. > > This is a very first raw round-trip with one output file per sgml file > and output type. Not supported: entities (__gt__ as a surrogate), > <[CDATA and similar SGML constructs, PostgreSQL specific style sheets, > Makefile, additional errors occur, .... . I append one file of every > new format for the chapter "Advanced Features": xml (the new source), > html, fo, pdf. > > Any ideas or suggestions? Shall we go further on this way? Has anybody > more experiences in SGML-->XML conversions or Docbook 4.x --> 5.x > conversions? > > Kind regards > Jürgen Purtz > > > --------------000604030709070307060105 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: 8bit
Hello Jürgen,

Please look at the discussion that we had some time ago:
http://www.postgresql.org/message-id/56337365.2080104@postgrespro.ru

And we (postgrespro) still have plans to migrate to XML as soon as we get documentation translated.
We had no issues with SGML->XML conversion, "make postgres.xml" creates XML (with entities and alike), which we use.

When you talking about "conversion of html, fo, pdf, ..." do you mean using docs/sgml/Makefile or some other scripts?

As to conversion SGML to XML, we need to decide whether to generate a single XML, or a set of XMLs (corresponding to current SGMLs).
In the latter case - how to include XML-fragments into the main document (as entities or with xi:include)?

Please, can you explain what are "Docbooks xslt-migration scripts"?
Is Docbook 4.x incompatible with Docbook 5.x and we need to convert it additionally?


Best regards,
Alexander

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




20.04.2016 17:30, Jürgen Purtz пишет:
Hi,
actually we use DocBook V4.2 for the PostgreSQL manuals. I suggest an upgrade to DocBook 5.x. This sounds simple, but it will be a long process with many sub-tasks.

Rationale:
  • Sooner or later we MUST migrate as the 4.x series is outdated: V4.2 dates back to 2002. The 4.x series is no longer actively developed since 2006. See: http://www.docbook.org/tdg5/en/html/ch01.html "In October 2006, the DocBook Technical Committee released DocBook V4.5, the last release planned in the 4.x series."
  • V5.0 is available since 2009. See: http://www.docbook.org/tdg5/en/html/ch01.html: "DocBook V5.0 became an official Committee Specification in June 2009 and became an officia7l OASIS Standard in October 2009."
  • Actually the technical committee has the third Candidate Release for V5.1.

PROs:
  • The formal part of the migration is supported by existing tools: http://docbook.org/docs/howto/#convert4to5 (nevertheless some scripts written by ourself will be necessary).
  • The normative schema for Docbook 5.x is written in RELAX NG. Additionally the technical committee converts this normative schema to a XSD schema and to DTD, which are not normative but very near to RELAX NG and will fit for most applications. Hence, we have the choice between three schema syntaxes and everybody can use his favourite one.
  • Our source file format will switch from SGML to XML. This implies that we have access to all XML features like XLink, XPath, XSLT, XSL-FO, SVG, MathML, namespaces, ... .
CONs:
  • The migration from 4.x to 5.x implies major changes at 3 different levels.
    • DocBook structure: Previously it was defined in SGML syntax (DTD). Now it is defined in RELAX NG schema language plus Schematron rules.
    • DocBook files: Previously we used SGML syntax for our files. We must convert them to a valid XML syntax, eg: tag omission.
    • Tools and style sheets: All tools which operate at the native SGML-level (editors, conversions, ...) must be replaced by XML conforming tools. As valid XML implicitly conforms to a valid SGML syntax this step may be accomplished by reconfiguring some of the tools, eg.: .emacs.
What I have done so far is:
  • Conversion of sgml files to valid xml syntax with a perl skript. I failed to use 'osx' or 'spam'.
  • Conversion of these xml files to Docbook5.x format using xsltproc and Docbooks xslt-migration skripts.
  • Creation of html files using xsltproc and Docbooks xslt skripts.
  • Creation of fo files using xsltproc and Docbooks xslt skripts.
  • Creation of pdf files using fop.
  • The conversions needs less than 10 minutes on a Intel i5 processor.
This is a very first raw round-trip with one output file per sgml file and output type. Not supported: entities (__gt__ as a surrogate), <[CDATA and similar SGML constructs, PostgreSQL specific style sheets, Makefile, additional errors occur, .... .  I append one file of every new format for the chapter "Advanced Features": xml (the new source), html, fo, pdf.

Any ideas or suggestions? Shall we go further on this way? Has anybody more experiences in SGML-->XML conversions or Docbook 4.x --> 5.x conversions?

Kind regards
Jürgen Purtz

 


    

    

  


--------------000604030709070307060105--