public inbox for [email protected]
help / color / mirror / Atom feedFrom: Michail Nikolaev <[email protected]>
To: [email protected]
Subject: [PATCH] Updating documentation about bulding documentation in Windows.
Date: Tue, 23 Jan 2018 21:05:27 +0000
Message-ID: <CANtu0ohZgcjDn_G2uwACx=8qjiwUDAv8F+8=rv0z8cagh12gbQ@mail.gmail.com> (raw)
Hello everyone.
Current documentation contains outdated instruction and scripts relative to
building documentation on Windows machine.
I removed useless scripts and wrote some guide to build docs using Windows
Linux Subsystem.
Also, could be viewed on github -
https://github.com/michail-nikolaev/postgres/commit/c6781351306810bfebab1fa5b454e8d24b9ea2f6
Thanks,
Michail.
Attachments:
[application/octet-stream] Update-documentation-regarding-building-docs-in-Wind.patch (9.0K, 3-Update-documentation-regarding-building-docs-in-Wind.patch)
download | inline diff:
From c6781351306810bfebab1fa5b454e8d24b9ea2f6 Mon Sep 17 00:00:00 2001
From: nkey <[email protected]>
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';
<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>.
+ Building the PostgreSQL documentation on Windows is not supported at the moment.
+ But it is possible to use
+ <productname>Windows Linux Subsystem</productname> for that purpose.
+ For information about <productname>WSL</productname> installation see
+ <ulink url="https://docs.microsoft.com/en-us/windows/wsl/about"></ulink>.
</para>
+ <para>
+ At first create directory to put PostgreSQL sources onto Windows files ystem -
+ for example <filename>C:\postgres</filename>.
+ </para>
+ <para>
+ Then run <productname>WSL</productname> and navigate to that directory
+ in Linux file system.
+ <screen>
+ <userinput>bash</userinput>
+ <userinput>cd /mnt/c/postgres/</userinput>
+ </screen>
+ </para>
+ <para>
+ Clone repository and set <parameter>core.autocrlf</parameter> to <parameter>false</parameter>
+ (to avoid scripts corruption by Windows-style newline encodings).
+ <screen>
+ <userinput>git clone git://git.postgresql.org/git/postgresql.git</userinput>
+ <userinput>cd postgresql</userinput>
+ <userinput>git config core.autocrlf false</userinput>
+ </screen>
+ </para>
+ <para>
+ Install toolset for bulding docs into WSL. For more details see <xref linkend="docguide-toolsets"/>
+ <screen>
+ <userinput>sudo apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc</userinput>
+ </screen>
+ </para>
+ <para>
+ Run the <filename>configure</filename> script inside <productname>WSL</productname> console.
+ For more information about the building in Linux enviroment, see <xref linkend="installation"/>.
+ <screen>
+ <userinput>./configure</userinput>
+ </screen>
+ </para>
+ <para>
+ Edit docs sources in <filename>C:\postgres\postgresql\doc\src\sgml</filename> using Windows.
+ Make sure your editors uses Unix-style newline endings.
+ Build documentation inside <productname>WSL</productname>. See <xref linkend="docguide-build"/>
+ <screen>
+ <userinput>cd /mnt/c/postgres/postgresql/doc/src</userinput>
+ <userinput>make</userinput>
+ </screen>
+ </para>
</sect2>
</sect1>
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
view thread (3+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected]
Subject: Re: [PATCH] Updating documentation about bulding documentation in Windows.
In-Reply-To: <CANtu0ohZgcjDn_G2uwACx=8qjiwUDAv8F+8=rv0z8cagh12gbQ@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox