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]> 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-26 05:03 Peter Eisentraut <[email protected]> parent: 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-26 09:10 Michail Nikolaev <[email protected]> parent: Peter Eisentraut <[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