From be566f60132220eb11b1d48485b9043965f80010 Mon Sep 17 00:00:00 2001
From: Lars Bilke <lars.bilke@ufz.de>
Date: Tue, 9 Apr 2019 12:07:18 +0200
Subject: [PATCH] [web] Added instructions on prj-file checking with xmllint.
---
Documentation/ProjectFile/i_ProjectFile.md | 5 ++
.../getting-started/first_steps/index.pandoc | 2 +-
.../docs/userguide/basics/introduction.pandoc | 2 +-
.../troubleshooting/{index.md => general.md} | 4 +-
.../troubleshooting/project-file.pandoc | 55 +++++++++++++++++++
5 files changed, 64 insertions(+), 4 deletions(-)
rename web/content/docs/userguide/troubleshooting/{index.md => general.md} (98%)
create mode 100644 web/content/docs/userguide/troubleshooting/project-file.pandoc
diff --git a/Documentation/ProjectFile/i_ProjectFile.md b/Documentation/ProjectFile/i_ProjectFile.md
index 1b83df2b101..f9f1b026bc0 100644
--- a/Documentation/ProjectFile/i_ProjectFile.md
+++ b/Documentation/ProjectFile/i_ProjectFile.md
@@ -1,4 +1,9 @@
The OGS6 input file parameters are documented in the page hierarchy rooted here.
+A project file has the ending `.prj` and is a valid
+[XML](https://en.wikipedia.org/wiki/XML) document. To check proper formatting
+you can use [`xmllint`](http://xmlsoft.org/xmllint.html), see
+[usage instructions](https://www.opengeosys.org/docs/userguide/troubleshooting/project-file/)
+in the documentation.
Depending on the type of the parameters the corresponding page titles have
different prefixes, namely:
diff --git a/web/content/docs/tools/getting-started/first_steps/index.pandoc b/web/content/docs/tools/getting-started/first_steps/index.pandoc
index 08195fb206a..5a5e545263b 100644
--- a/web/content/docs/tools/getting-started/first_steps/index.pandoc
+++ b/web/content/docs/tools/getting-started/first_steps/index.pandoc
@@ -13,7 +13,7 @@ weight = 101
This section describes a possible general pre-processing workflow using some of the tools provided by OGS.
-To set up a model domain, the project file `*.prj` requires additional input files for the mesh and geometry to apply the boundary conditions accordingly.
+To set up a model domain, [the project file `*.prj`](https://doxygen.opengeosys.org/ogs_file_param__ProjectFile.html) requires additional input files for the mesh and geometry to apply the boundary conditions accordingly.
The mesh must be provided in VTK's `*.vtu` format, whereas the geometry can be provided either in OGS' internal `*.gml` file format (not to be confused with the Geography Markup Language) or as a `*.vtu` file as well, containing boundary elements only (Multiple `*.vtu` files can be provided in the project file using the `<meshes>` tag). We recommend the usage of the first method for simple 2D meshes with constant boundary conditions, whereas more complicated geometries and conditions might require the latter method. One general advantage in the utilization of `*.vtu` files is that they allow a definition of additional field variables at each mesh node/element in order to implement spatially varying boundary conditions in a similar manner as defining inhomogeneous material properties.
diff --git a/web/content/docs/userguide/basics/introduction.pandoc b/web/content/docs/userguide/basics/introduction.pandoc
index cd398c7098e..ec5c8c61f65 100644
--- a/web/content/docs/userguide/basics/introduction.pandoc
+++ b/web/content/docs/userguide/basics/introduction.pandoc
@@ -27,7 +27,7 @@ Download the latest benchmark files from [GitHub as a .zip-package](https://gith
## Running
-OGS is a command line application and requires the path to a `.prj`-file as an argument.
+OGS is a command line application and requires the path to a [`.prj`-file](https://doxygen.opengeosys.org/ogs_file_param__ProjectFile.html) as an argument.
::: {.win}
To run it open a new command line shell (called *cmd.exe*). Now simply type `ogs` (if the executable is in your `PATH`-environment variable) or specify its full path (e.g.: `C:\Users\MyUserName\Downloads\ogs.exe`) and hit `ENTER`.
diff --git a/web/content/docs/userguide/troubleshooting/index.md b/web/content/docs/userguide/troubleshooting/general.md
similarity index 98%
rename from web/content/docs/userguide/troubleshooting/index.md
rename to web/content/docs/userguide/troubleshooting/general.md
index 21f56887fc1..57f31e13b85 100644
--- a/web/content/docs/userguide/troubleshooting/index.md
+++ b/web/content/docs/userguide/troubleshooting/general.md
@@ -1,8 +1,8 @@
+++
date = "2018-11-14T11:00:13+01`:00"
-title = "Troubleshooting"
+title = "General"
author = "Lars Bilke"
-weight = 99
+weight = 1
toc = true
[menu]
diff --git a/web/content/docs/userguide/troubleshooting/project-file.pandoc b/web/content/docs/userguide/troubleshooting/project-file.pandoc
new file mode 100644
index 00000000000..d0028154ead
--- /dev/null
+++ b/web/content/docs/userguide/troubleshooting/project-file.pandoc
@@ -0,0 +1,55 @@
++++
+date = "2018-11-14T11:00:13+01`:00"
+title = "Project file syntax"
+author = "Lars Bilke"
+weight = 2
+
+[menu]
+ [menu.userguide]
+ parent = "troubleshooting"
++++
+
+## Check project file syntax with `xmllint`
+
+[Project files `.prj`](https://doxygen.opengeosys.org/ogs_file_param__ProjectFile.html) have to be valid XML documents. You can check the formatting with the [`xmllint`-tool](http://xmlsoft.org/xmllint.html):
+
+```bash
+xmllint --noout myproj.prj
+```
+
+### Install `xmllint`
+
+::: {.win}
+
+We recommend to install via [Chocolatey](https://chocolatey.org):
+
+```powershell
+choco install xsltproc
+```
+
+::: {.note}
+### <i class="far fa-info-circle"></i> Alternative installation
+Another method is to use the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) where you can simply install Linux packages:
+
+```bash
+sudo apt-get install libxml2-utils
+```
+:::
+
+:::
+
+::: {.linux}
+
+```bash
+sudo apt-get install libxml2-utils
+```
+
+:::
+
+::: {.mac}
+`xmllint` is part of the Homebrew xmlstarlet package:
+
+```bash
+brew install xmlstarlet
+```
+:::
--
GitLab