From c6781351306810bfebab1fa5b454e8d24b9ea2f6 Mon Sep 17 00:00:00 2001 From: nkey Date: Tue, 23 Jan 2018 23:55:46 +0300 Subject: [PATCH] Update documentation regarding building docs in Windows. Remove useless scripts. --- doc/src/sgml/install-windows.sgml | 88 +++++++++++++++------------ src/tools/msvc/README | 1 - src/tools/msvc/builddoc.bat | 7 --- src/tools/msvc/builddoc.pl | 124 -------------------------------------- 4 files changed, 48 insertions(+), 172 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 99e9c7b..a4badde 100644 --- a/doc/src/sgml/install-windows.sgml +++ b/doc/src/sgml/install-windows.sgml @@ -490,47 +490,55 @@ $ENV{PERL5LIB}=$ENV{PERL5LIB} . ';c:\IPC-Run-0.94\lib'; Building the Documentation - 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. - - - OpenJade 1.3.1-2 - - Download from - - and uncompress in the subdirectory openjade-1.3.1. - - - - - DocBook DTD 4.2 - - Download from - - and uncompress in the subdirectory docbook. - - - - - ISO character entities - - Download from - and - uncompress in the subdirectory docbook. - - - - Edit the buildenv.pl file, and add a variable for the - location of the root directory, for example: - -$ENV{DOCROOT}='c:\docbook'; - - To build the documentation, run the command - builddoc.bat. Note that this will actually run the - build twice, in order to generate the indexes. The generated HTML files - will be in doc\src\sgml. + Building the PostgreSQL documentation on Windows is not supported at the moment. + But it is possible to use + Windows Linux Subsystem for that purpose. + For information about WSL installation see + . + + At first create directory to put PostgreSQL sources onto Windows files ystem - + for example C:\postgres. + + + Then run WSL and navigate to that directory + in Linux file system. + + bash + cd /mnt/c/postgres/ + + + + Clone repository and set core.autocrlf to false + (to avoid scripts corruption by Windows-style newline encodings). + + git clone git://git.postgresql.org/git/postgresql.git + cd postgresql + git config core.autocrlf false + + + + Install toolset for bulding docs into WSL. For more details see + + sudo apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc + + + + Run the configure script inside WSL console. + For more information about the building in Linux enviroment, see . + + ./configure + + + + Edit docs sources in C:\postgres\postgresql\doc\src\sgml using Windows. + Make sure your editors uses Unix-style newline endings. + Build documentation inside WSL. See + + cd /mnt/c/postgres/postgresql/doc/src + make + + diff --git a/src/tools/msvc/README b/src/tools/msvc/README index 48082ca..bfa9804 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 0247069..0000000 --- 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 e0b5c50..0000000 --- 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; - -} - -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.9.0.windows.1