Thread: rename sgml files?
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
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
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
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
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
> 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
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
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
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
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