Skip to content

Commit b2ef88b

Browse files
joewizjoewiz
authored
Merge pull request #178 from eXist-db/eriksiegel-develop
Initial edits by Erik Siegel
2 parents c012f76 + 61994d7 commit b2ef88b

File tree

657 files changed

+48510
-12688
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

657 files changed

+48510
-12688
lines changed

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
# eXist-db Documentation
22
[![Build Status](https://travis-ci.org/eXist-db/documentation.svg?branch=master)](https://travis-ci.org/eXist-db/documentation)
3-
[![Docbook version](https://img.shields.io/badge/docbook-4.5-19a5a4.svg)](http://docbook.org/xml/4.5/)
3+
[![Docbook version](https://img.shields.io/badge/docbook-5.0-19a5a4.svg)](http://docbook.org/xml/5.0/)
44
[![eXist-db version](https://img.shields.io/badge/eXist_db-3.5.0-blue.svg)](http://www.exist-db.org/exist/apps/homepage/index.html)
55

66
<img src="src/main/xar-resources/icon.png" align="left" width="15%"/>
77

88
This repository contains the official documentation for the [eXist-db native XML database](http://www.exist-db.org) and the application for browsing it. You can browse the latest release of the documentation on [eXist-db homepage](http://exist-db.org/exist/apps/doc/). User reporting errors should check the [contributions](#contributions) section below. Core-contributors preparing a release should consult the [release procedure](RELEASE.md)
99

10+
## Notice
11+
As of January 2018 the exist-db documentation is undergoing a major rewrite. While this is work in progress ,we want to keep the contents open for community edits. Consequently, the display of the documentation will at times appear less polished then usual.
1012

1113
## Dependencies
1214
- [Maven](https://maven.apache.org): 3.x

‎pom.xml‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -109,12 +109,15 @@
109109
<validationSets>
110110
<validationSet>
111111
<dir>src/main/xar-resources/data</dir>
112+
<includes>
113+
<include>*/*.xml</include>
114+
</includes>
112115
<excludes>
113-
<exclude>*.xq</exclude>
114-
<exclude>xinclude.xml</exclude>
116+
<exclude>template/template.xml</exclude>
117+
<exclude>db4-versions/*.xml</exclude>
115118
</excludes>
116-
<publicId>-//OASIS//DTD DocBook XML V4.5//EN</publicId>
117-
<systemId>${project.baseUri}/src/main/xsd/docbook.xsd</systemId>
119+
<publicId>-//OASIS//DTD DocBook V5.0//EN//XML</publicId>
120+
<systemId>${project.baseUri}src/main/xsd/docbook.xsd</systemId>
118121
</validationSet>
119122
</validationSets>
120123
</configuration>

‎src/main/xar-resources/collection.xconf‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
<?xml version="1.0" encoding="UTF-8"?>
21
<collection xmlns="http://exist-db.org/collection-config/1.0">
32
<index>
43
<fulltext default="none" attributes="false"/>

‎src/main/xar-resources/controller.xql‎

Lines changed: 98 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,86 +1,119 @@
11
xquery version "1.0";
22

3-
import module namespace request="http://exist-db.org/xquery/request";
3+
(:~
4+
Main controller for the eXist documentation app.
5+
:)
6+
7+
(:============================================================================:)
8+
(:== SETUP: ==:)
9+
10+
import module namespace request = "http://exist-db.org/xquery/request";
411
import module namespace xdb = "http://exist-db.org/xquery/xmldb";
512

13+
import module namespace config = "http://exist-db.org/xquery/apps/config" at "modules/config.xqm";
14+
615
declare variable $exist:path external;
716
declare variable $exist:resource external;
817
declare variable $exist:controller external;
918
declare variable $exist:prefix external;
1019
declare variable $exist:root external;
11-
12-
let $query := request:get-parameter("q", ())
20+
21+
(: Make sure we have a correct resource name. If this thing has no extension, amend it with .xml: :)
22+
declare variable $resource-name as xs:string := if (contains($exist:resource, '.')) then
23+
$exist:resource
24+
else
25+
concat($exist:resource, '.xml');
26+
27+
(: Find out whether the resource has a path component: :)
28+
declare variable $has-path as xs:boolean :=
29+
let $path-no-leading-slash := if (starts-with($exist:path, '/')) then
30+
substring($exist:path, 2)
31+
else
32+
$exist:path
1333
return
34+
contains($path-no-leading-slash, '/');
35+
36+
(:============================================================================:)
37+
(:== MAIN: ==:)
38+
39+
(: No path at all? End it with a /: :)
1440
if ($exist:path eq '') then
41+
<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
42+
<redirect url="{concat(request:get-uri(), '/')}"/>
43+
</dispatch>
44+
45+
(: A path that simply ends with a / goes to the main documentation page: :)
46+
else
47+
if ($exist:path eq "/") then
1548
<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
16-
<redirect url="{concat(request:get-uri(), '/')}"/>
17-
</dispatch>
18-
19-
else if ($exist:path eq "/") then
20-
<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
21-
<forward url="{$exist:controller}/templates/content.html">
49+
<forward url="{$exist:controller}/templates/content.html"/>
50+
<view>
51+
<!-- pass the results through view.xql -->
52+
<forward url="{$exist:controller}/modules/view.xql">
53+
<add-parameter name="doc" value="{config:get-resource-path($config:data-root, 'documentation.xml')}"/>
54+
<set-attribute name="$exist:prefix" value="{$exist:prefix}"/>
55+
<set-attribute name="$exist:controller" value="{$exist:controller}"/>
2256
</forward>
23-
<view>
24-
<!-- pass the results through view.xql -->
25-
<forward url="{$exist:controller}/modules/view.xql">
26-
<add-parameter name="doc" value="documentation.xml"/>
27-
<set-attribute name="$exist:prefix" value="{$exist:prefix}"/>
28-
<set-attribute name="$exist:controller" value="{$exist:controller}"/>
29-
</forward>
30-
</view>
31-
<error-handler>
32-
<forward url="{$exist:controller}/error-page.html" method="get"/>
33-
<forward url="{$exist:controller}/modules/view.xql"/>
34-
</error-handler>
57+
</view>
58+
<error-handler>
59+
<forward url="{$exist:controller}/error-page.html" method="get"/>
60+
<forward url="{$exist:controller}/modules/view.xql"/>
61+
</error-handler>
3562
</dispatch>
36-
37-
(: Pass all requests to XML files through to view.xql, which handles HTML templating :)
38-
else if (ends-with($exist:resource, ".xml")) then
39-
<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
40-
<forward url="{$exist:controller}/templates/content.html">
41-
</forward>
63+
64+
(: Pass all requests to XML files through to view.xql, which handles HTML templating
65+
Request that contain a path are supposed to be resources and not handled here.
66+
:)
67+
else
68+
if (ends-with($resource-name, ".xml") and not($has-path)) then
69+
<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
70+
<forward url="{$exist:controller}/templates/content.html"/>
4271
<view>
43-
<!-- pass the results through view.xql -->
44-
<forward url="{$exist:controller}/modules/view.xql">
45-
<add-parameter name="doc" value="{$exist:resource}"/>
46-
<set-attribute name="$exist:prefix" value="{$exist:prefix}"/>
47-
<set-attribute name="$exist:controller" value="{$exist:controller}"/>
48-
</forward>
72+
<!-- pass the results through view.xql -->
73+
<forward url="{$exist:controller}/modules/view.xql">
74+
<add-parameter name="doc" value="{config:get-resource-path($config:data-root, $resource-name)}"/>
75+
<set-attribute name="$exist:prefix" value="{$exist:prefix}"/>
76+
<set-attribute name="$exist:controller" value="{$exist:controller}"/>
77+
</forward>
4978
</view>
5079
<error-handler>
51-
<forward url="{$exist:controller}/error-page.html" method="get"/>
52-
<forward url="{$exist:controller}/modules/view.xql"/>
80+
<forward url="{$exist:controller}/error-page.html" method="get"/>
81+
<forward url="{$exist:controller}/modules/view.xql"/>
5382
</error-handler>
54-
</dispatch>
55-
56-
(: Pass all requests to HTML files through view.xql, which handles HTML templating :)
57-
else if (ends-with($exist:resource, ".html")) then
58-
<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
59-
<view>
60-
<forward url="{$exist:controller}/modules/view.xql">
61-
<set-attribute name="$exist:prefix" value="{$exist:prefix}"/>
62-
<set-attribute name="$exist:controller" value="{$exist:controller}"/>
83+
</dispatch>
84+
85+
(: Pass all requests to HTML files through view.xql, which handles HTML templating :)
86+
else
87+
if (ends-with($resource-name, ".html")) then
88+
<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
89+
<view>
90+
<forward url="{$exist:controller}/modules/view.xql">
91+
<set-attribute name="$exist:prefix" value="{$exist:prefix}"/>
92+
<set-attribute name="$exist:controller" value="{$exist:controller}"/>
6393
</forward>
64-
</view>
65-
<error-handler>
94+
</view>
95+
<error-handler>
6696
<forward url="{$exist:controller}/error-page.html" method="get"/>
6797
<forward url="{$exist:controller}/modules/view.xql"/>
68-
</error-handler>
69-
</dispatch>
70-
71-
else if (contains($exist:path, "/$shared/")) then
72-
<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
73-
<forward url="/shared-resources/{substring-after($exist:path, '/$shared/')}"/>
74-
</dispatch>
75-
76-
(: images, css are contained in the top /resources/ collection. :)
77-
(: Relative path requests from sub-collections are redirected there :)
78-
else if (contains($exist:path, "/resources/")) then
79-
<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
80-
<forward url="{$exist:controller}/resources/{substring-after($exist:path, '/resources/')}"/>
81-
</dispatch>
82-
83-
else
84-
<ignore xmlns="http://exist.sourceforge.net/NS/exist">
85-
<cache-control cache="yes"/>
86-
</ignore>
98+
</error-handler>
99+
</dispatch>
100+
101+
(: Anything with /$shared/ in it points to the eXist main shared-resources app: :)
102+
else
103+
if (contains($exist:path, "/$shared/")) then
104+
<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
105+
<forward url="/shared-resources/{substring-after($exist:path, '/$shared/')}"/>
106+
</dispatch>
107+
108+
(: Shared images, css, etc. are contained in the top /resources/ collection. :)
109+
(:else
110+
if (starts-with($exist:path, "/resources/")) then
111+
<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
112+
<forward url="{$exist:controller}/resources/{substring-after($exist:path, '/resources/')}"/>
113+
</dispatch>:)
114+
115+
(: Final catch-all: :)
116+
else
117+
<ignore xmlns="http://exist.sourceforge.net/NS/exist">
118+
<cache-control cache="yes"/>
119+
</ignore>

‎src/main/xar-resources/data/advanced-installation/advanced-installation.xml‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng"
2+
schematypens="http://relaxng.org/ns/structure/1.0"?><?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml"
3+
schematypens="http://purl.oclc.org/dsdl/schematron"?><article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
4+
5+
<!-- ================================================================== -->
6+
7+
<info>
8+
<title>Advanced Installation Methods</title>
9+
<date>1Q18</date>
10+
<keywordset>
11+
<keyword>installation</keyword>
12+
<keyword>operations</keyword>
13+
</keywordset>
14+
</info>
15+
16+
<!-- ================================================================== -->
17+
18+
<para>The eXist-db <link xlink:href="basic-installation">Basic Installation</link> article describes how to install and start eXist-db for basic
19+
usage. This article explains more advanced methods of installing and running eXist, for instance for a headless (no GUI) system, running it as a
20+
service, etc.</para>
21+
22+
<!-- ================================================================== -->
23+
24+
<sect1 xml:id="headless">
25+
<title>Headless Installation</title>
26+
27+
<para>The <link xlink:href="basic-installation">Basic Installation</link> of eXist-db requires a graphical desktop. You can also install eXist on
28+
a headless (no GUI) system. For this launch the installer from the command line, using the <code>-console</code> option:</para>
29+
<programlisting>java -jar eXist-{version}.jar -console</programlisting>
30+
<para>In console mode, the installer will prompt for several parameters (almost like the GUI version does). A dump of a sample interaction is
31+
shown below:</para>
32+
<programlisting xlink:href="listings/listing-2.txt"/>
33+
</sect1>
34+
35+
<!-- ================================================================== -->
36+
37+
<sect1 xml:id="service">
38+
<title>Running eXist-db as a Service</title>
39+
40+
<para>Instead of manually running the eXist-db server in a shell window, you can run it as a background service which is automatically launched
41+
during system start-up. This can be convenient, especially for servers. eXist-db continues to run even after users have logged off.</para>
42+
<para>eXist-db comes with pre-configured scripts that use <link condition="_blank" xlink:href="http://yajsw.sourceforge.net/">YAJSW (Yet Another
43+
Java Service Wrapper)</link> to handle the setup procedure. The scripts for this are contained in the directory
44+
<literal>tools/yajsw</literal>. </para>
45+
<para>Out of the box the following mainstream platforms are supported:</para>
46+
<itemizedlist>
47+
<listitem>
48+
<para>Windows x86 (32bit/64bit)</para>
49+
</listitem>
50+
<listitem>
51+
<para>Linux x86 (32bit/64bit) &amp; IA (64bit) </para>
52+
</listitem>
53+
<listitem>
54+
<para>macOS x86 (32bit/64bit) </para>
55+
</listitem>
56+
<listitem>
57+
<para>Solaris x86 (32bit/64bit) &amp; SPARC (32bit/64bit)</para>
58+
</listitem>
59+
</itemizedlist>
60+
61+
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
62+
63+
<sect2 xml:id="windows">
64+
<title>Windows</title>
65+
66+
<para>On Windows there are three identical options:</para>
67+
<itemizedlist>
68+
<listitem>
69+
<para>Choose <guimenuitem>Install eXist-db as Service</guimenuitem> from the eXist-db's system tray application.</para>
70+
</listitem>
71+
<listitem>
72+
<para>Choose <guimenuitem>Install eXist-db as Service</guimenuitem> from eXist-db's entry in the Windows start menu.</para>
73+
</listitem>
74+
<listitem>
75+
<para>Run <literal>tools/yajsw/bin/installService.bat</literal> from the command line.</para>
76+
</listitem>
77+
</itemizedlist>
78+
<para>Installing eXist-db as a service on Windows requires full administrator rights.</para>
79+
80+
<para>After installing eXist-db as a service, you'll find eXist-db in the list of services registered with Windows:</para>
81+
<informalfigure>
82+
<mediaobject>
83+
<imageobject>
84+
<imagedata fileref="assets/services.png"/>
85+
</imageobject>
86+
</mediaobject>
87+
</informalfigure>
88+
<para>Launch it via the service manager (as shown in the screenshot above) or from the command line:</para>
89+
<programlisting>tools\yaysw\bin\startService.bat</programlisting>
90+
</sect2>
91+
92+
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
93+
94+
<sect2 xml:id="linux">
95+
<title>Unix/Linux</title>
96+
97+
<para>The scripts for running eXist-db as a service for Unix and Linux based system (among which MacOS)can be found in the
98+
<literal>tools/yajsw/bin/</literal> sub-directory.</para>
99+
<para>Run the following command to get eXist-db started during initialization of the system:</para>
100+
<programlisting>tools/yajsw/bin/installDaemon.sh</programlisting>
101+
<para> This works for MacOS and many Linux distributions.</para>
102+
<para>It might be required to set some variables for the specific system, among which <code>wrapper.app.account</code> (to have eXist-db started
103+
as a specific user) and <code>wrapper.plist.template</code> for <code>launchd</code>. Details can be found on the <link xlink:href="http://yajsw.sourceforge.net/YAJSW%20Configuration%20Parameters.html">YAJSW website</link>.</para>
104+
<para> If your system supports <code>systemd</code> you can run the service wrapper as a non-privileged user. You will be notified on choosing
105+
<code>systemd</code> non-privileged when running the service wrapper installer and uninstaller.</para>
106+
</sect2>
107+
108+
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
109+
110+
<sect2 xml:id="other">
111+
<title>Other platforms</title>
112+
113+
<para>Support for additional platforms can be bootstrapped by looking at templates in the <code>tools/yajsw/templates</code> sub-directory.
114+
Consult the <link condition="_blank" xlink:href="http://yajsw.sourceforge.net/">YAJSW documentation</link> for more information.</para>
115+
</sect2>
116+
</sect1>
117+
118+
<!-- ================================================================== -->
119+
120+
<sect1 xml:id="bin-executables">
121+
<title>Alternatives for scripts in the bin Directory</title>
122+
123+
<para>Included in the distribution are a number of useful <literal>.sh</literal> (Unix Shell) and <literal>.bat</literal> (DOS batch) programs
124+
located in the <literal>bin</literal> sub-directory. Their names speak for themselves.</para>
125+
<para>However, if you find that programs do not launch, you can try to manually launch them on the command-line without the scripting wrapper.
126+
This often provides useful debugging information.</para>
127+
<para>To manually launch these scripts, give the following commands:</para>
128+
<variablelist spacing="compact">
129+
<varlistentry>
130+
<term>
131+
<code>startup.sh</code> (Unix) / <code>startup.bat</code> (Windows)</term>
132+
<listitem>
133+
<programlisting>java -jar start.jar jetty</programlisting>
134+
<para>Starts the included Jetty web server at port 8080. eXist runs as a web application, located at <link xlink:href="http://localhost:8080/exist/">http://localhost:8080/exist/</link>. </para>
135+
</listitem>
136+
</varlistentry>
137+
<varlistentry>
138+
<term>
139+
<code>shutdown.sh</code> (Unix) / <code>shutdown.bat</code> (Windows)</term>
140+
<listitem>
141+
<programlisting>java -jar start.jar shutdown -p youradminpassword</programlisting>
142+
<para>Closes the running instance of eXist. If eXist has been started with <literal>startup.sh</literal>, calling
143+
<literal>shutdown.sh</literal> will also stop the Jetty web server. Otherwise, only the database is stopped by this call (since eXist
144+
has no control over the environment in which it is running). You should <emphasis>always</emphasis> call <literal>shutdown</literal>
145+
before killing the server process.</para>
146+
</listitem>
147+
</varlistentry>
148+
<varlistentry>
149+
<term>
150+
<code>server.sh</code> (Unix) / <code>server.bat</code> (Windows)</term>
151+
<listitem>
152+
<programlisting>java -jar start.jar standalone</programlisting>
153+
<para>Launches eXist as a stand-alone server process. In this setup, eXist is only accessible through the XMLRPC and the built-in HTTP
154+
interface.</para>
155+
</listitem>
156+
</varlistentry>
157+
<varlistentry>
158+
<term>
159+
<code>client.sh</code> (Unix) / <code>client.bat</code> (Windows)</term>
160+
<listitem>
161+
<programlisting>java -jar start.jar client</programlisting>
162+
<para>Launches the <link xlink:href="java-admin-client">Java Admin Client</link>. This application is also launched if no application is
163+
selected on the command-line, like this:</para>
164+
<programlisting>java -jar start.jar</programlisting>
165+
</listitem>
166+
</varlistentry>
167+
</variablelist>
168+
</sect1>
169+
</article>

‎src/main/xar-resources/data/advanced-installation/assets/services.png‎

36.6 KB
Loading

0 commit comments

Comments
 (0)