public inbox for [email protected]
help / color / mirror / Atom feed[PATCH] Updating documentation about bulding documentation in Windows.
3+ messages / 2 participants
[nested] [flat]
* [PATCH] Updating documentation about bulding documentation in Windows.
@ 2018-01-23 21:05 Michail Nikolaev <[email protected]>
2018-01-26 05:03 ` Re: [PATCH] Updating documentation about bulding documentation in Windows. Peter Eisentraut <[email protected]>
0 siblings, 1 reply; 3+ messages in thread
From: Michail Nikolaev @ 2018-01-23 21:05 UTC (permalink / raw)
To: pgsql-docs
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
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: [PATCH] Updating documentation about bulding documentation in Windows.
2018-01-23 21:05 [PATCH] Updating documentation about bulding documentation in Windows. Michail Nikolaev <[email protected]>
@ 2018-01-26 05:03 ` Peter Eisentraut <[email protected]>
2018-01-26 09:10 ` Re: [PATCH] Updating documentation about bulding documentation in Windows. Michail Nikolaev <[email protected]>
0 siblings, 1 reply; 3+ messages in thread
From: Peter Eisentraut @ 2018-01-26 05:03 UTC (permalink / raw)
To: Michail Nikolaev <[email protected]>; pgsql-docs
On 1/23/18 16:05, Michail Nikolaev wrote:
> 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.
Why not fix the script instead?
Using WSL is also a good idea, but then we could just say, use WSL and
follow the instructions for the particular Linux distribution. We don't
need to repeat all that again.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: [PATCH] Updating documentation about bulding documentation in Windows.
2018-01-23 21:05 [PATCH] Updating documentation about bulding documentation in Windows. Michail Nikolaev <[email protected]>
2018-01-26 05:03 ` Re: [PATCH] Updating documentation about bulding documentation in Windows. Peter Eisentraut <[email protected]>
@ 2018-01-26 09:10 ` Michail Nikolaev <[email protected]>
0 siblings, 0 replies; 3+ messages in thread
From: Michail Nikolaev @ 2018-01-26 09:10 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: pgsql-docs
Hello.
It is not so easy to fix the script because it is based on old toolset
(probably on 9.6).
I'll try one more attempt.
Regardning WSL:
I think it is better to keep some instructions because there are a lot of
common errors - line ending, correct usage of linux\windows file system
mappings.
Most of Windows users are not familiar with it. I could rewrtite it as:
1. clone using WSL to Windows filesystem
2. disable autoclrf
3. edit documentation in Windows (usig Unix line-ending) and build in
WLS.
Thanks,
Michail.
пт, 26 янв. 2018 г. в 8:03, Peter Eisentraut <
[email protected]>:
> On 1/23/18 16:05, Michail Nikolaev wrote:
> > 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.
>
> Why not fix the script instead?
>
> Using WSL is also a good idea, but then we could just say, use WSL and
> follow the instructions for the particular Linux distribution. We don't
> need to repeat all that again.
>
> --
> Peter Eisentraut http://www.2ndQuadrant.com/
> PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
>
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2018-01-26 09:10 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2018-01-23 21:05 [PATCH] Updating documentation about bulding documentation in Windows. Michail Nikolaev <[email protected]>
2018-01-26 05:03 ` Peter Eisentraut <[email protected]>
2018-01-26 09:10 ` Michail Nikolaev <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox