Thread: rename sgml files?

rename sgml files?

From
Peter Eisentraut
Date:
So, should we rename the *.sgml files to *.xml, since they are actually
now XML files?

Advantages: better automatic editor integration, better automatic syntax
highlighting (e.g., on GitHub), less confusion in general in the future

And maybe while we're at it, truncate the directory structure
doc/src/sgml/ a bit?  The intermediate directories had a meaning at some
point, but now they're mostly empty.

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


Re: rename sgml files?

From
Tom Lane
Date:
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> So, should we rename the *.sgml files to *.xml, since they are actually
> now XML files?

At that point, back-patching documentation fixes would become effectively
impossible except through manual intervention in the patching process.
I don't want to go there.  The recent changes have already imposed a
significant PITA factor on generating minor-release notes, and this
would push it past what I care to deal with.

As I've remarked before, the issue would disappear if we were to
back-patch the XML-ization of the documentation.  So I'd be fine
with this if we did it uniformly in the supported branches.  Otherwise
I think the costs outweigh the benefits.

            regards, tom lane


Re: rename sgml files?

From
David Fetter
Date:
On Mon, Feb 12, 2018 at 04:19:48PM -0500, Tom Lane wrote:
> Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> > So, should we rename the *.sgml files to *.xml, since they are actually
> > now XML files?
> 
> At that point, back-patching documentation fixes would become effectively
> impossible except through manual intervention in the patching process.
> I don't want to go there.  The recent changes have already imposed a
> significant PITA factor on generating minor-release notes, and this
> would push it past what I care to deal with.
> 
> As I've remarked before, the issue would disappear if we were to
> back-patch the XML-ization of the documentation.  So I'd be fine
> with this if we did it uniformly in the supported branches.  Otherwise
> I think the costs outweigh the benefits.

+1 for back-patching.

Are there scripts for (at least the first cut of) this?

Best,
David.
-- 
David Fetter <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate


Re: rename sgml files?

From
Tom Lane
Date:
David Fetter <david@fetter.org> writes:
> On Mon, Feb 12, 2018 at 04:19:48PM -0500, Tom Lane wrote:
>> As I've remarked before, the issue would disappear if we were to
>> back-patch the XML-ization of the documentation.  So I'd be fine
>> with this if we did it uniformly in the supported branches.  Otherwise
>> I think the costs outweigh the benefits.

> +1 for back-patching.

> Are there scripts for (at least the first cut of) this?

IIRC, Peter said basically that it was more work than he cared to tackle,
which I guess means that there was significant manual effort involved.

The most practical answer might be to wait a few years till all the live
branches use XML, and then we can do the renaming in all branches
trivially.  Perhaps finishing the XML conversion in v10 would be cheap
enough that it'd be worth doing that to shave one year off the wait.

            regards, tom lane


Re: rename sgml files?

From
Michael Paquier
Date:
On Mon, Feb 12, 2018 at 06:38:36PM -0500, Tom Lane wrote:
> The most practical answer might be to wait a few years till all the live
> branches use XML, and then we can do the renaming in all branches
> trivially.  Perhaps finishing the XML conversion in v10 would be cheap
> enough that it'd be worth doing that to shave one year off the wait.

My vote would be to backport the build changes to v10, which should be
simple enough, and wait for 9.6 to be EOL'd before doing the rename.
--
Michael

Attachment

Re: rename sgml files?

From
Tatsuo Ishii
Date:
> My vote would be to backport the build changes to v10, which should be
> simple enough, and wait for 9.6 to be EOL'd before doing the rename.

Me too. However my concern is the tool chain. Maybe we should notice
packagers to prepare it?

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


Re: rename sgml files?

From
Michael Paquier
Date:
On Tue, Feb 13, 2018 at 12:58:22PM +0900, Tatsuo Ishii wrote:
>> My vote would be to backport the build changes to v10, which should be
>> simple enough, and wait for 9.6 to be EOL'd before doing the rename.
>
> Me too. However my concern is the tool chain. Maybe we should notice
> packagers to prepare it?

Definitely.  Preparing for a new major upgrade is a lot of work
already, so doing things for minor versions is risky.  Asking those
folks would be necessary first as this changes the build dependencies.
--
Michael

Attachment

Re: rename sgml files?

From
Tom Lane
Date:
Michael Paquier <michael@paquier.xyz> writes:
> On Tue, Feb 13, 2018 at 12:58:22PM +0900, Tatsuo Ishii wrote:
>>> My vote would be to backport the build changes to v10, which should be
>>> simple enough, and wait for 9.6 to be EOL'd before doing the rename.

>> Me too. However my concern is the tool chain. Maybe we should notice
>> packagers to prepare it?

> Definitely.

Absolutely.  But part of the calculation here is that packagers who
build the docs for themselves already need to have the new toolchain
in place for v10.  So it seems like it shouldn't be that hard for them
to use it for older branches as well.  But yeah, if we were seriously
going to pursue back-porting the XML conversion, we'd have to poll
pgsql-packagers to see if anybody had a problem with that.

            regards, tom lane


Re: rename sgml files?

From
Peter Eisentraut
Date:
On 2/12/18 16:19, Tom Lane wrote:
> At that point, back-patching documentation fixes would become effectively
> impossible except through manual intervention in the patching process.

Are you not using git cherry-pick?

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


Re: rename sgml files?

From
Tom Lane
Date:
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> On 2/12/18 16:19, Tom Lane wrote:
>> At that point, back-patching documentation fixes would become effectively
>> impossible except through manual intervention in the patching process.

> Are you not using git cherry-pick?

Yes, when it works, which it tends not to in cases that are even a little
bit complicated.  I have zero faith that it works across a file rename,
and would not like to give up the option of using patch(1) instead.  (See,
eg, recent discussions about the fragility of "git apply" vs "patch".)

            regards, tom lane