From 53944716926576275a6be06bb5794e78fd4cf7ef Mon Sep 17 00:00:00 2001 From: Lars Bilke <lars.bilke@ufz.de> Date: Thu, 6 May 2021 13:23:09 +0200 Subject: [PATCH] [web] Added documentation on xml patch and include. --- Documentation/ProjectFile/i_ProjectFile.md | 2 +- web/config/_default/config.toml | 8 +- .../docs/userguide/basics/container.md | 2 +- .../docs/userguide/basics/project-file.md | 154 ++++++++++++++++++ .../post-processing/paraview-on-eve.md | 2 +- .../Heat_Transport_BHE.md | 2 +- .../Heat_Transport_BHE_PipelineNetwork.md | 2 +- .../docs/userguide/troubleshooting/general.md | 2 +- .../userguide/troubleshooting/get-support.md | 2 +- .../userguide/troubleshooting/project-file.md | 59 ------- 10 files changed, 165 insertions(+), 70 deletions(-) create mode 100644 web/content/docs/userguide/basics/project-file.md delete mode 100644 web/content/docs/userguide/troubleshooting/project-file.md diff --git a/Documentation/ProjectFile/i_ProjectFile.md b/Documentation/ProjectFile/i_ProjectFile.md index f9f1b026bc0..9417112dcf4 100644 --- a/Documentation/ProjectFile/i_ProjectFile.md +++ b/Documentation/ProjectFile/i_ProjectFile.md @@ -2,7 +2,7 @@ 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/) +[usage instructions](https://www.opengeosys.org/docs/userguide/basics/project-file/) in the documentation. Depending on the type of the parameters the corresponding page titles have diff --git a/web/config/_default/config.toml b/web/config/_default/config.toml index a0bdf80d77a..4ff26b299ca 100644 --- a/web/config/_default/config.toml +++ b/web/config/_default/config.toml @@ -112,12 +112,12 @@ name = "Basics" identifier = "basics" weight = 1 [[menu.userguide]] -name = "Post Processing" -identifier = "post-processing" -weight = 2 -[[menu.userguide]] name = "Troubleshooting" identifier = "troubleshooting" +weight = 2 +[[menu.userguide]] +name = "Post Processing" +identifier = "post-processing" weight = 3 [[menu.userguide]] name = "Process Dependent Configuration" diff --git a/web/content/docs/userguide/basics/container.md b/web/content/docs/userguide/basics/container.md index a4834562f78..0b84aedd88c 100644 --- a/web/content/docs/userguide/basics/container.md +++ b/web/content/docs/userguide/basics/container.md @@ -2,7 +2,7 @@ date = "2018-11-14T15:00:13+01:00" title = "Running OGS in a container" author = "Lars Bilke" -weight = 10 +weight = 2 [menu] [menu.userguide] diff --git a/web/content/docs/userguide/basics/project-file.md b/web/content/docs/userguide/basics/project-file.md new file mode 100644 index 00000000000..04c0e5e4f7d --- /dev/null +++ b/web/content/docs/userguide/basics/project-file.md @@ -0,0 +1,154 @@ ++++ +date = "2018-11-14T11:00:13+01`:00" +title = "Project file syntax" +author = "Lars Bilke" +weight = 3 + +[menu] + [menu.userguide] + parent = "basics" ++++ + +Project files `.prj` have to be valid XML documents. For information of specific tags see our [Doxygen-documentation](https://doxygen.opengeosys.org/d1/d91/ogs_file_param__projectfile). + +Two methods allow you to modularize your project files and avoid repetition: + +## Option 1: Include XML-content from other files + +The `<include filename="other_file.xml" />`-tag allows to include the content of another XML into the current project file. + +**Limitation:** Only one child `include`-element per (regular) XML-element is allowed. + +### Example + +`Tests/Data/Elliptic/circle_radius_1/circle_1e1_axi.prj`: + +```xml + <processes> + <include file="../cube_1x1x1_SteadyStateDiffusion/SteadyStateDiffusion.xml"/> + </processes> +``` + +`Tests/Data/Elliptic/cube_1x1x1_SteadyStateDiffusion/SteadyStateDiffusion.xml`: +```xml +<process> + <name>SteadyStateDiffusion</name> + <type>STEADY_STATE_DIFFUSION</type> + <integration_order>2</integration_order> + <process_variables> + <process_variable>pressure</process_variable> + </process_variables> + <secondary_variables> + <secondary_variable internal_name="darcy_velocity" output_name="v"/> + </secondary_variables> +</process> +``` + +## Option 2: Apply patch files to the project file + +Patch files contain `<replace>`, `<add>` and `<remove>`-elements with [XPath](https://en.wikipedia.org/wiki/XPath)-selectors to modify a specific part of the project file (in-memory during run-time): + +`Tests/Data/Elliptic/square_1x1_SteadyStateDiffusion/square_neumann.xml`: +```xml +<?xml version="1.0" encoding="ISO-8859-1"?> +<OpenGeoSysProjectDiff> + <add sel="/*/time_loop/output/prefix/text()" pos="after">_neumann</add> + <replace sel="/*/parameters/parameter[2]/name/text()">p_neumann</replace> + <replace sel="/*/parameters/parameter[3]/name/text()">p_Dirichlet</replace> + <replace sel="/*/parameters/parameter[3]/value/text()">1</replace> + <replace sel="/*/process_variables/process_variable/boundary_conditions/boundary_condition[1]/parameter/text()">p_Dirichlet</replace> + <replace sel="/*/process_variables/process_variable/boundary_conditions/boundary_condition[2]/type/text()">Neumann</replace> + <replace sel="/*/process_variables/process_variable/boundary_conditions/boundary_condition[2]/parameter/text()">p_neumann</replace> + <add sel="/*/process_variables/process_variable/boundary_conditions/boundary_condition[1]" pos="after"> + <boundary_condition> + <geometrical_set>square_1x1_geometry</geometrical_set> + <geometry>bottom</geometry> + <type>Dirichlet</type> + <parameter>p_Dirichlet</parameter> + </boundary_condition> + </add> +</OpenGeoSysProjectDiff> +``` + +### Option 2a: Supply patch file(s) additionally to the prj-file + +```bash +ogs -p path/to/square_1e0_neumann.xml [other/optional/patch_file.xml] path/to/square_1e0.prj +``` + +### Option 2b: Use a patch file directly + +If the patch file specifies a `base_file`: + +`Tests/Data/Elliptic/cube_1x1x1_SteadyStateDiffusion/cube_1e1.xml`: +```xml +<?xml version="1.0" encoding="ISO-8859-1"?> +<OpenGeoSysProjectDiff base_file="cube_1e0.prj"> + <replace sel="/*/mesh/text()">cube_1x1x1_hex_1e1.vtu</replace> + <replace sel="/*/time_loop/output/prefix/text()">cube_1e1</replace> +</OpenGeoSysProjectDiff> + +``` + +you can just pass this patch file: + +```bash +ogs path/to/cube_1e1.xml +``` + +In this case you have just one patch file. + +--- + +Both methods, include and patch, can be combined. + +--- + +## Check project file syntax with `xmllint` + + You can check the formatting with the [`xmllint`-tool](http://xmlsoft.org/xmllint.html): + +```bash +xmllint --noout myproj.prj +``` + +### Install `xmllint` + +<div class='win'> + +We recommend to install via [Chocolatey](https://chocolatey.org): + +```powershell +choco install xsltproc +``` + +<div class='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 +``` + +</div> + +</div> + +<div class='linux'> + +```bash +sudo apt-get install libxml2-utils +``` + +</div> + +<div class='mac'> +`xmllint` is part of the Homebrew xmlstarlet package: + +```bash +brew install xmlstarlet +``` + +</div> diff --git a/web/content/docs/userguide/post-processing/paraview-on-eve.md b/web/content/docs/userguide/post-processing/paraview-on-eve.md index 90e82d62caa..3be4f5c36e3 100644 --- a/web/content/docs/userguide/post-processing/paraview-on-eve.md +++ b/web/content/docs/userguide/post-processing/paraview-on-eve.md @@ -2,7 +2,7 @@ date = "2018-11-14T14:00:13+01`:00" title = "ParaView on Eve frontends / envinf1" author = "Lars Bilke" -weight = 1 +weight = 31 [menu] [menu.userguide] diff --git a/web/content/docs/userguide/process-dependent-configuration/Heat_Transport_BHE.md b/web/content/docs/userguide/process-dependent-configuration/Heat_Transport_BHE.md index 722bffeea8c..3458d361425 100644 --- a/web/content/docs/userguide/process-dependent-configuration/Heat_Transport_BHE.md +++ b/web/content/docs/userguide/process-dependent-configuration/Heat_Transport_BHE.md @@ -2,7 +2,7 @@ date = "2019-11-21T12:00:13+01:00" title = "Heat_Transport_BHE" author = "Wanlong Cai, Haibing Shao" -weight = 1 +weight = 41 [menu] [menu.userguide] diff --git a/web/content/docs/userguide/process-dependent-configuration/Heat_Transport_BHE_PipelineNetwork.md b/web/content/docs/userguide/process-dependent-configuration/Heat_Transport_BHE_PipelineNetwork.md index b14c6262105..9e8422af0bf 100644 --- a/web/content/docs/userguide/process-dependent-configuration/Heat_Transport_BHE_PipelineNetwork.md +++ b/web/content/docs/userguide/process-dependent-configuration/Heat_Transport_BHE_PipelineNetwork.md @@ -2,7 +2,7 @@ date = "2020-02-03T12:00:13+01:00" title = "Heat_Transport_BHE PipeNetwork Feature" author = "Shuang Chen, Haibing Shao, Francesco Witte" -weight = 123 +weight = 42 project = "Parabolic/T/3D_3BHEs_array/3bhes_1U.prj" [menu] diff --git a/web/content/docs/userguide/troubleshooting/general.md b/web/content/docs/userguide/troubleshooting/general.md index 9e17d405861..fab6047a7d3 100644 --- a/web/content/docs/userguide/troubleshooting/general.md +++ b/web/content/docs/userguide/troubleshooting/general.md @@ -2,7 +2,7 @@ date = "2018-11-14T11:00:13+01`:00" title = "General" author = "Lars Bilke" -weight = 2 +weight = 22 toc = true [menu] diff --git a/web/content/docs/userguide/troubleshooting/get-support.md b/web/content/docs/userguide/troubleshooting/get-support.md index 7dd6abeb978..ae5317a27e8 100644 --- a/web/content/docs/userguide/troubleshooting/get-support.md +++ b/web/content/docs/userguide/troubleshooting/get-support.md @@ -2,7 +2,7 @@ date = "2020-11-24T09:45:13+01`:00" title = "Get support / fill a bug report" author = "Lars Bilke" -weight = 1 +weight = 21 [menu] [menu.userguide] diff --git a/web/content/docs/userguide/troubleshooting/project-file.md b/web/content/docs/userguide/troubleshooting/project-file.md deleted file mode 100644 index 4ba796408d6..00000000000 --- a/web/content/docs/userguide/troubleshooting/project-file.md +++ /dev/null @@ -1,59 +0,0 @@ -+++ -date = "2018-11-14T11:00:13+01`:00" -title = "Project file syntax" -author = "Lars Bilke" -weight = 3 - -[menu] - [menu.userguide] - parent = "troubleshooting" -+++ - -## Check project file syntax with `xmllint` - -Project files `.prj` 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` - -<div class='win'> - -We recommend to install via [Chocolatey](https://chocolatey.org): - -```powershell -choco install xsltproc -``` - -<div class='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 -``` - -</div> - -</div> - -<div class='linux'> - -```bash -sudo apt-get install libxml2-utils -``` - -</div> - -<div class='mac'> -`xmllint` is part of the Homebrew xmlstarlet package: - -```bash -brew install xmlstarlet -``` - -</div> -- GitLab