Обсуждение: Splitting up release.sgml
(I'm sure this has come up before, but it hasn't got done for some reason...) I think it's time for $SUBJECT. release.sgml is growing at a rate of several thousand lines per major release and several hundred for each group of minor releases. It's getting to be a pain to edit, and I don't even want to think about how large the underlying RCS file must be. This clearly doesn't scale for the long term. What I propose we do is: Create a separate file for each major release branch, eg release-8.3.sgml for the 8.3.x series. This will contain exactly the <sect1> ... </sect1> material that is currently in release.sgml for that branch. It's probably not worth carrying out the above split back beyond 8.0. I suggest throwing 7.4 and all prior branches into one file release-old.sgml. This will leave release.sgml containing just the chapter header material and include directives for the release-xxx.sgml files. In the future it will change only to add a new include line when a new major branch is started. I propose making this change in the active back branches, not only HEAD. This will mean that the process for updating back-branch release notes reduces to copying the appropriate release-xxx.sgml files into each older branch; we won't need the major_release_split script, which is rather dangerous because it doesn't understand that the header material has to be different in the oldest branches. (In this scheme, the link difference is still located in the release.sgml file, but that doesn't change anymore in back branches so there's no risk of overwriting it.) Thoughts? regards, tom lane
Le samedi 25 avril 2009 à 21:28:46, Tom Lane a écrit : > [...] > What I propose we do is: > > Create a separate file for each major release branch, eg > release-8.3.sgml for the 8.3.x series. This will contain exactly > the <sect1> ... </sect1> material that is currently in release.sgml > for that branch. > I completely agree. This huge file is also really painful for translators. Splitting it will make the job easier. > It's probably not worth carrying out the above split back beyond 8.0. > I suggest throwing 7.4 and all prior branches into one file > release-old.sgml. > I would have included 7.4 branch in this, but that's not really a big issue. > This will leave release.sgml containing just the chapter header > material and include directives for the release-xxx.sgml files. > In the future it will change only to add a new include line > when a new major branch is started. > > I propose making this change in the active back branches, not only HEAD. > This will mean that the process for updating back-branch release notes > reduces to copying the appropriate release-xxx.sgml files into each > older branch; we won't need the major_release_split script, which is > rather dangerous because it doesn't understand that the header material > has to be different in the oldest branches. (In this scheme, the link > difference is still located in the release.sgml file, but that doesn't > change anymore in back branches so there's no risk of overwriting it.) > I'm also OK with this. -- Guillaume. http://www.postgresqlfr.org http://dalibo.com
I wrote: > I think it's time for $SUBJECT. I started to play with this and found out that there's one roadblock in the way; it's doc/src/sgml/Makefile's method for building the plain-text HISTORY file. That starts out with # remove links to main documentation HISTORY.html: release.sgml ( echo '<!doctype appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN">'; \ cat $< ) | \ $(PERL) -p -0 -e 's/<link\s+linkend[^>]*>//g' | \ $(PERL) -p -e 's/<\/link>//g' >tempfile_HISTORY.sgml $(JADE.text) -V nochunks tempfile_HISTORY.sgml >$@ rm tempfile_HISTORY.sgml which will not work to remove links from files that are included into release.sgml. The best answer is probably to expand the inclusions before the Perl processing, but I can't think of any reasonably simple way to do that. Any ideas? The Make dependency on release.sgml alone wouldn't be adequate either, given that it won't change nearly as fast as the included files. regards, tom lane