pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedDocumented toolchain for building docs on Windows
9+ messages / 3 participants
[nested] [flat]
Commits from this thread:
2018-07-13 1f4ec89459 Remove obsolete documentation build tools for Windows
2018-06-29 dad335b89f b241c119b7 7e0786e4d9 c91ac358b1 f61a25727c 6acb4e89fe Replace search.cpan.org with metacpan.org
* Documented toolchain for building docs on Windows
@ 2018-06-28 10:17 Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 9+ messages in thread
From: Daniel Gustafsson @ 2018-06-28 10:17 UTC (permalink / raw)
To: pgsql-docs; +Cc: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Section "17.1. Building with Visual C++ or the Microsoft Windows SDK” in the
documentation has a subsection "Building the Documentation” which seems to list
a required toolchain which is out of date with information in the Documentation
appendix (it still lists OpenJade etc).
I don’t know anything about building on Windows so I might be off, but doesn’t
that need to be updated to match the new toolchain?
cheers ./daniel
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Documented toolchain for building docs on Windows
@ 2018-06-28 10:39 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 9+ messages in thread
From: Peter Eisentraut @ 2018-06-28 10:39 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs
On 6/28/18 12:17, Daniel Gustafsson wrote:
> Section "17.1. Building with Visual C++ or the Microsoft Windows SDK” in the
> documentation has a subsection "Building the Documentation” which seems to list
> a required toolchain which is out of date with information in the Documentation
> appendix (it still lists OpenJade etc).
>
> I don’t know anything about building on Windows so I might be off, but doesn’t
> that need to be updated to match the new toolchain?
Yes, I had complained about this before, but nobody responded. I can
review a new text, but I can't write it.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Documented toolchain for building docs on Windows
@ 2018-06-28 11:19 Daniel Gustafsson <daniel@yesql.se>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 1 reply; 9+ messages in thread
From: Daniel Gustafsson @ 2018-06-28 11:19 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs
> On 28 Jun 2018, at 12:39, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
>
> On 6/28/18 12:17, Daniel Gustafsson wrote:
>> Section "17.1. Building with Visual C++ or the Microsoft Windows SDK” in the
>> documentation has a subsection "Building the Documentation” which seems to list
>> a required toolchain which is out of date with information in the Documentation
>> appendix (it still lists OpenJade etc).
>>
>> I don’t know anything about building on Windows so I might be off, but doesn’t
>> that need to be updated to match the new toolchain?
>
> Yes, I had complained about this before, but nobody responded. I can
> review a new text, but I can't write it.
Ah, my archive search skills are apparently lacking, thus the duplicate.
Looking at little more at this, the docs mention builddoc.bat which was
replaced in 2011 in favor of builddoc.pl. This program in turn is using
openjade and is thus, I assume, not working anymore.
Unless someone steps up before 11 is rolled, maybe builddoc.pl should be made
into a exit immediately no-op since "nothing" is better than “broken”?
cheers ./daniel
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Documented toolchain for building docs on Windows
@ 2018-06-29 13:08 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 9+ messages in thread
From: Peter Eisentraut @ 2018-06-29 13:08 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs
On 6/28/18 13:19, Daniel Gustafsson wrote:
> Unless someone steps up before 11 is rolled, maybe builddoc.pl should be made
> into a exit immediately no-op since "nothing" is better than “broken”?
I'm thinking, just delete the file and the documentation section.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Documented toolchain for building docs on Windows
@ 2018-06-29 16:51 Daniel Gustafsson <daniel@yesql.se>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 1 reply; 9+ messages in thread
From: Daniel Gustafsson @ 2018-06-29 16:51 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs
> On 29 Jun 2018, at 15:08, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
>
> On 6/28/18 13:19, Daniel Gustafsson wrote:
>> Unless someone steps up before 11 is rolled, maybe builddoc.pl should be made
>> into a exit immediately no-op since "nothing" is better than “broken”?
>
> I'm thinking, just delete the file and the documentation section.
Well, that's a pretty decisive way to make it a no-op =) The attached patch
does that, along with a note in the relnotes to highlight the dropped support
which I think is warranted should we take this approach.
cheers ./daniel
Attachments:
doc_build_windows.patch (application/octet-stream, 7.7K) download
From 0d9e542858174bc1c841817110d02286d7801729 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <daniel@yesql.se>
Date: Fri, 29 Jun 2018 17:04:43 +0200
Subject: [PATCH] Remove support for building docs on Windows
After the conversion of the docs to XML, the Windows toolchain for
building docs no longer work. As there is no solution in sight at
the moment, remove support rather than keeping it broken. Also add
a note in the release notes to highlight the removed support.
---
doc/src/sgml/install-windows.sgml | 47 ---------------
doc/src/sgml/release-11.sgml | 4 ++
src/tools/msvc/README | 1 -
src/tools/msvc/builddoc.bat | 7 ---
src/tools/msvc/builddoc.pl | 124 --------------------------------------
5 files changed, 4 insertions(+), 179 deletions(-)
delete mode 100755 src/tools/msvc/builddoc.bat
delete mode 100644 src/tools/msvc/builddoc.pl
diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml
index e345471c85..276ea27461 100644
--- a/doc/src/sgml/install-windows.sgml
+++ b/doc/src/sgml/install-windows.sgml
@@ -486,52 +486,5 @@ $ENV{PERL5LIB}=$ENV{PERL5LIB} . ';c:\IPC-Run-0.94\lib';
</para>
</sect2>
- <sect2>
- <title>Building the Documentation</title>
-
- <para>
- Building the PostgreSQL documentation in HTML format requires several tools
- and files. Create a root directory for all these files, and store them
- in the subdirectories in the list below.
- <variablelist>
- <varlistentry>
- <term>OpenJade 1.3.1-2</term>
- <listitem><para>
- Download from
- <ulink url="http://sourceforge.net/projects/openjade/files/openjade/1.3.1/openjade-1_3_1-2-bin.zip/download"></ulink>
- and uncompress in the subdirectory <filename>openjade-1.3.1</filename>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>DocBook DTD 4.2</term>
- <listitem><para>
- Download from
- <ulink url="http://www.oasis-open.org/docbook/sgml/4.2/docbook-4.2.zip"></ulink>
- and uncompress in the subdirectory <filename>docbook</filename>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ISO character entities</term>
- <listitem><para>
- Download from
- <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip"></ulink> and
- uncompress in the subdirectory <filename>docbook</filename>.
- </para></listitem>
- </varlistentry>
- </variablelist>
- Edit the <filename>buildenv.pl</filename> file, and add a variable for the
- location of the root directory, for example:
-<programlisting>
-$ENV{DOCROOT}='c:\docbook';
-</programlisting>
- To build the documentation, run the command
- <filename>builddoc.bat</filename>. Note that this will actually run the
- build twice, in order to generate the indexes. The generated HTML files
- will be in <filename>doc\src\sgml</filename>.
- </para>
- </sect2>
-
</sect1>
</chapter>
diff --git a/doc/src/sgml/release-11.sgml b/doc/src/sgml/release-11.sgml
index 53b600b453..b51e7e5828 100644
--- a/doc/src/sgml/release-11.sgml
+++ b/doc/src/sgml/release-11.sgml
@@ -2612,6 +2612,10 @@ same commits as above
The file names still use an <filename>sgml</filename> extension
for compatibility with back branches.
</para>
+
+ <para>
+ Building the documentation on Windows is no longer supported.
+ </para>
</listitem>
<listitem>
diff --git a/src/tools/msvc/README b/src/tools/msvc/README
index 48082cab90..bfa98045f2 100644
--- a/src/tools/msvc/README
+++ b/src/tools/msvc/README
@@ -47,7 +47,6 @@ arguments.
- User tools -
build.pl tool to build the binaries
-builddoc.pl tool to build the docs
clean.bat batch file for cleaning up generated files
install.pl tool to install the generated files
mkvcbuild.pl tool to generate the Visual Studio build files
diff --git a/src/tools/msvc/builddoc.bat b/src/tools/msvc/builddoc.bat
deleted file mode 100755
index 024706989e..0000000000
--- a/src/tools/msvc/builddoc.bat
+++ /dev/null
@@ -1,7 +0,0 @@
-@echo off
-
-REM src/tools/msvc/builddoc.bat
-REM all the logic for this now belongs in builddoc.pl. This file really
-REM only exists so you don't have to type "perl builddoc.pl"
-REM Resist any temptation to add any logic here.
-@perl builddoc.pl %*
diff --git a/src/tools/msvc/builddoc.pl b/src/tools/msvc/builddoc.pl
deleted file mode 100644
index f6eb73db21..0000000000
--- a/src/tools/msvc/builddoc.pl
+++ /dev/null
@@ -1,124 +0,0 @@
-# -*-perl-*- hey - emacs - this is a perl file
-
-# Adjust path for your docbook installation in buildenv.pl
-
-# src/tools/msvc/builddoc.pl
-# translated from an earlier .bat file
-
-use strict;
-use File::Copy;
-use Cwd qw(abs_path getcwd);
-
-my $startdir = getcwd();
-
-my $openjade = 'openjade-1.3.1';
-my $dsssl = 'docbook-dsssl-1.79';
-
-chdir '../../..' if (-d '../msvc' && -d '../../../src');
-
-noversion() unless -e 'doc/src/sgml/version.sgml';
-
-do 'src/tools/msvc/buildenv.pl' if -e 'src/tools/msvc/buildenv.pl';
-
-my $docroot = $ENV{DOCROOT};
-die "bad DOCROOT '$docroot'" unless ($docroot && -d $docroot);
-
-my @notfound;
-foreach my $dir ('docbook', $openjade, $dsssl)
-{
- push(@notfound, $dir) unless -d "$docroot/$dir";
-}
-missing() if @notfound;
-
-my $arg = shift;
-renamefiles();
-
-chdir 'doc/src/sgml';
-
-$ENV{SGML_CATALOG_FILES} =
- "$docroot/$openjade/dsssl/catalog;" . "$docroot/docbook/docbook.cat";
-
-my $cmd;
-
-# openjade exits below with a harmless non-zero status, so we
-# can't die on "failure"
-
-$cmd =
- "perl mk_feature_tables.pl YES "
- . "../../../src/backend/catalog/sql_feature_packages.txt "
- . "../../../src/backend/catalog/sql_features.txt "
- . "> features-supported.sgml";
-system($cmd);
-die "features_supported" if $?;
-$cmd =
- "perl mk_feature_tables.pl NO "
- . "\"../../../src/backend/catalog/sql_feature_packages.txt\" "
- . "\"../../../src/backend/catalog/sql_features.txt\" "
- . "> features-unsupported.sgml";
-system($cmd);
-die "features_unsupported" if $?;
-$cmd =
- "perl generate-errcodes-table.pl \"../../../src/backend/utils/errcodes.txt\" "
- . "> errcodes-table.sgml";
-system($cmd);
-die "errcodes-table" if $?;
-
-print "Running first build...\n";
-$cmd =
- "\"$docroot/$openjade/bin/openjade\" -V html-index -wall "
- . "-wno-unused-param -wno-empty -D . -c \"$docroot/$dsssl/catalog\" "
- . "-d stylesheet.dsl -i output-html -t sgml postgres.sgml 2>&1 "
- . "| findstr /V \"DTDDECL catalog entries are not supported\" ";
-system($cmd); # die "openjade" if $?;
-print "Running collateindex...\n";
-$cmd = "perl \"$docroot/$dsssl/bin/collateindex.pl\" -f -g -i bookindex "
- . "-o bookindex.sgml HTML.index";
-system($cmd);
-die "collateindex" if $?;
-mkdir "html";
-print "Running second build...\n";
-$cmd =
- "\"$docroot/$openjade/bin/openjade\" -wall -wno-unused-param -wno-empty "
- . "-D . -c \"$docroot/$dsssl/catalog\" -d stylesheet.dsl -t sgml "
- . "-i output-html -i include-index postgres.sgml 2>&1 "
- . "| findstr /V \"DTDDECL catalog entries are not supported\" ";
-
-system($cmd); # die "openjade" if $?;
-
-copy "stylesheet.css", "html/stylesheet.css";
-
-print "Docs build complete.\n";
-
-exit;
-
-########################################################
-
-sub renamefiles
-{
-
- # Rename ISO entity files
- my $savedir = getcwd();
- chdir "$docroot/docbook";
- foreach my $f (glob('ISO*'))
- {
- next if $f =~ /\.gml$/i;
- my $nf = $f;
- $nf =~ s/ISO(.*)/ISO-$1.gml/;
- move $f, $nf;
- }
- chdir $savedir;
- return;
-}
-
-sub missing
-{
- print STDERR "could not find $docroot/$_\n" foreach (@notfound);
- exit 1;
-}
-
-sub noversion
-{
- print STDERR "Could not find version.sgml. ",
- "Please run mkvcbuild.pl first!\n";
- exit 1;
-}
--
2.14.1.145.gb3622a4ee
=
* Re: Documented toolchain for building docs on Windows
@ 2018-07-13 08:09 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 9+ messages in thread
From: Peter Eisentraut @ 2018-07-13 08:09 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs
On 29.06.18 18:51, Daniel Gustafsson wrote:
>> On 29 Jun 2018, at 15:08, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
>>
>> On 6/28/18 13:19, Daniel Gustafsson wrote:
>>> Unless someone steps up before 11 is rolled, maybe builddoc.pl should be made
>>> into a exit immediately no-op since "nothing" is better than “broken”?
>>
>> I'm thinking, just delete the file and the documentation section.
>
> Well, that's a pretty decisive way to make it a no-op =) The attached patch
> does that, along with a note in the relnotes to highlight the dropped support
> which I think is warranted should we take this approach.
I have committed this to master now. The scripts have already been
broken since PG10, so mentioning it in the PG11 release notes doesn't
seem appropriate.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Documented toolchain for building docs on Windows
@ 2018-07-13 22:23 Daniel Gustafsson <daniel@yesql.se>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 1 reply; 9+ messages in thread
From: Daniel Gustafsson @ 2018-07-13 22:23 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs
> On 13 Jul 2018, at 10:09, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
>
> On 29.06.18 18:51, Daniel Gustafsson wrote:
>>> On 29 Jun 2018, at 15:08, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
>>>
>>> On 6/28/18 13:19, Daniel Gustafsson wrote:
>>>> Unless someone steps up before 11 is rolled, maybe builddoc.pl should be made
>>>> into a exit immediately no-op since "nothing" is better than “broken”?
>>>
>>> I'm thinking, just delete the file and the documentation section.
>>
>> Well, that's a pretty decisive way to make it a no-op =) The attached patch
>> does that, along with a note in the relnotes to highlight the dropped support
>> which I think is warranted should we take this approach.
>
> I have committed this to master now. The scripts have already been
> broken since PG10, so mentioning it in the PG11 release notes doesn't
> seem appropriate.
Ok, that makes sense. Thanks!
cheers ./daniel
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Documented toolchain for building docs on Windows
@ 2018-07-18 09:17 Michail Nikolaev <michail.nikolaev@gmail.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 9+ messages in thread
From: Michail Nikolaev @ 2018-07-18 09:17 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; pgsql-docs
Hello.
Also, please check
http://www.postgresql-archive.org/PATCH-Updating-documentation-about-bulding-documentation-in-Window...
I have done the same on 23 Jan + additional docs on how to build
documentation using Windows Linux Subsystem :)
It will be cool to include docs about WLS method.
Thanks,
Michail.
сб, 14 июл. 2018 г. в 1:24, Daniel Gustafsson <daniel@yesql.se>:
> > On 13 Jul 2018, at 10:09, Peter Eisentraut <
> peter.eisentraut@2ndquadrant.com> wrote:
> >
> > On 29.06.18 18:51, Daniel Gustafsson wrote:
> >>> On 29 Jun 2018, at 15:08, Peter Eisentraut <
> peter.eisentraut@2ndquadrant.com> wrote:
> >>>
> >>> On 6/28/18 13:19, Daniel Gustafsson wrote:
> >>>> Unless someone steps up before 11 is rolled, maybe builddoc.pl
> should be made
> >>>> into a exit immediately no-op since "nothing" is better than “broken”?
> >>>
> >>> I'm thinking, just delete the file and the documentation section.
> >>
> >> Well, that's a pretty decisive way to make it a no-op =) The attached
> patch
> >> does that, along with a note in the relnotes to highlight the dropped
> support
> >> which I think is warranted should we take this approach.
> >
> > I have committed this to master now. The scripts have already been
> > broken since PG10, so mentioning it in the PG11 release notes doesn't
> > seem appropriate.
>
> Ok, that makes sense. Thanks!
>
> cheers ./daniel
>
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Documented toolchain for building docs on Windows
@ 2018-07-22 21:27 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Michail Nikolaev <michail.nikolaev@gmail.com>
0 siblings, 0 replies; 9+ messages in thread
From: Peter Eisentraut @ 2018-07-22 21:27 UTC (permalink / raw)
To: Michail Nikolaev <michail.nikolaev@gmail.com>; Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs
On 18.07.18 11:17, Michail Nikolaev wrote:
> Also, please
> check http://www.postgresql-archive.org/PATCH-Updating-documentation-about-bulding-documentation-in-Window...
>
> I have done the same on 23 Jan + additional docs on how to build
> documentation using Windows Linux Subsystem :)
It doesn't seem that that documentation is very much about how to build
the documentation on WLS. It's just a description of how to set up a
PostgreSQL build environment under WLS and then ... see the Unix build
instructions. That's nice, but then it's not in the right place in the
documentation.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 9+ messages in thread
end of thread, other threads:[~2018-07-22 21:27 UTC | newest]
Thread overview: 9+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2018-06-28 10:17 Documented toolchain for building docs on Windows Daniel Gustafsson <daniel@yesql.se>
2018-06-28 10:39 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2018-06-28 11:19 ` Daniel Gustafsson <daniel@yesql.se>
2018-06-29 13:08 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2018-06-29 16:51 ` Daniel Gustafsson <daniel@yesql.se>
2018-07-13 08:09 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2018-07-13 22:23 ` Daniel Gustafsson <daniel@yesql.se>
2018-07-18 09:17 ` Michail Nikolaev <michail.nikolaev@gmail.com>
2018-07-22 21:27 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox