diff --git a/README.md b/README.md index ae1a46d..29a66ba 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,54 @@ -# SUSE Schemas +# GeekoDoc -[![Build Status](https://travis-ci.org/openSUSE/geekodoc.svg?branch=develop)](https://travis-ci.org/openSUSE/geekodoc) +[![Validating GeekoDoc](https://github.com/openSUSE/geekodoc/actions/workflows/validate.yml/badge.svg)](https://github.com/openSUSE/geekodoc/actions/workflows/validate.yml) -## GeekoDoc -GeekoDoc is a RELAX NG schema and a subset of DocBook 5. Currently, it can be -used in two variants: +## What is GeekoDoc? -1. As the file `geekodoc-v?.rn{c,g}` which is based on `docbookxi.rn{c,g}`. In - other words, the GeekoDoc schema cannot life without the DocBook schema. -2. As a single`geekodoc-v?-flat.rn{c,g}`. This file is independent from the - DocBook schema and can be used without having DocBook 5 installed on - your system. +GeekoDoc is a RELAX NG schema and a subset of DocBook 5. It restricts the +content model of some elements and attributes to make it easier to +write documents. -Both variants contain the same structure, elements, and attributes. They -serve different purposes. +Valid GeekoDoc documents are also valid DocBook 5 documents. -## Available GeekoDoc Versions +## GeekoDoc Versions -To support legacy documentation, there are two GeekoDoc schema versions: +GeekoDoc comes in two versions that are currently very similar. +Their main difference is that GeekoDoc 2 restricts `xml:id` attributes +to a more SEO-friendly subset of characters. More changes are to be +expected in the future. -* **Version 1** this is the legacy version. -* **Version 2** this is where all the new features are added. +In general, we recommend using GeekoDoc 2 for all new projects. -Select the version you want using the appropriate URI. +* GeekoDoc 1: available via the URI `urn:x-suse:rng:v1:geekodoc-flat` +* GeekoDoc 2: available via the URI `urn:x-suse:rng:v2:geekodoc-flat` -* Version 1 URIs +## Additional versions of GeekoDoc - These URIs are deprecated and shouldn't be use for new documents. - General syntax is: +* New, versioned URIs: + * Available for GeekoDoc 1 and GeekoDoc 2 + * General syntax: `urn:x-suse:FORMAT:VERSION:SCHEMA` + * FORMAT: can be `rnc` or `rng` + * VERSION: can be `v1` or `v2` + * SCHEMA: `geekodoc-flat` + * Includes the following URIs: - urn:x-suse:rng:FILE + urn:x-suse:rnc:v1:geekodoc-flat + urn:x-suse:rng:v1:geekodoc-flat + urn:x-suse:rnc:v2:geekodoc-flat + urn:x-suse:rng:v2:geekodoc-flat - The following URIs are defined: - - urn:x-suse:rng:geekodoc5.rnc - urn:x-suse:rng:geekodoc5-flat.rnc - urn:x-suse:rng:geekodoc5.rng - urn:x-suse:rng:geekodoc5-flat.rng - -* Version 2 URIs - - These are the new URIs which can be used for old and new versions of GeekoDoc. - The new URIs distinguish between GeekoDoc versions. The general syntax is: - - urn:x-suse:FORMAT:VERSION:SCHEMA - - * FORMAT: can be "rnc" or "rng" - * VERSION: can be "v1" or "v2" - * SCHEMA: normal ("geekodoc") or flat ("geekodoc-flat") - - The following URIs are defined: - - urn:x-suse:rnc:v1:geekodoc - urn:x-suse:rnc:v1:geekodoc-flat - urn:x-suse:rng:v1:geekodoc - urn:x-suse:rng:v1:geekodoc-flat +* Old, unversioned URIs (do not use for new projects): + * Only available for GeekoDoc 1 + * General syntax: `urn:x-suse:rng:FILE` + * Includes the following URIs: + urn:x-suse:rng:geekodoc5.rnc + urn:x-suse:rng:geekodoc5-flat.rnc + urn:x-suse:rng:geekodoc5.rng + urn:x-suse:rng:geekodoc5-flat.rng ## Using GeekoDoc with DAPS @@ -68,11 +58,13 @@ with one of the URIs above: DOCBOOK5_RNG_URI="" +It is possible to add the previous line into a DC file. + ## Creating Flat GeekoDoc -Creating the flat GeekoDoc schema requires the `rnginline` tool at -https://github.com/h4l/rnginline/ +Creating the flat GeekoDoc schema requires the `rnginline` tool from +https://github.com/h4l/rnginline/. Use one of the following methods to install `rnginline`: @@ -80,17 +72,25 @@ Use one of the following methods to install `rnginline`: * Install it in a Python virtual environment -### Installing rnginline from RPM Package +### Installing rnginline from RPM Package on openSUSE The following procedure can be used for the latest openSUSE Leap release: -1. Add the repository: +1. Add the `devel:languages:python` repository: - ``` - $ sudo zypper ar https://download.opensuse.org/repositories/devel:/languages:/python/openSUSE_Leap_\$releasever/devel:languages:python.repo - ``` + * for openSUSE Leap: + + ``` + $ sudo zypper ar https://download.opensuse.org/repositories/devel:/languages:/python/openSUSE_Leap_\$releasever/devel:languages:python.repo + ``` + + * for openSUSE Tumbleweed: -2. Install it: + ``` + $ sudo zypper ar https://download.opensuse.org/repositories/devel:/languages:/python/openSUSE_Tumbleweed/devel:languages:python.repo + ``` + +2. Install the package: ``` $ sudo zypper in python3-rnginline @@ -102,6 +102,11 @@ The executable can be found in `/usr/bin/rnginline`. ### Installing rnginline using a Python Virtual Environment 1. Install the RPM packages `python3-devel`, `libxml2-devel`, and `libxslt-devel`. + On openSUSE, run: + + ``` + $ sudo zypper in python3-devel libxml2-devel libxslt-devel + ``` 2. Create a Python3 virtual environment: @@ -115,7 +120,7 @@ The executable can be found in `/usr/bin/rnginline`. $ source .env3/bin/activate ``` - => You should see a changed prompt (look for the "(.env3)" part). + You should see a changed prompt (look for the `(.env3)` part). 3. Install the `rnginline` library from PyPi: @@ -131,9 +136,9 @@ The executable can be found in `.env3/bin/rnginline`. 1. Update your GitHub repository. -2. Change the directory to `geekodoc/rng`. +2. Run `./build.sh`. -3. Run `make`. +3. Find the built schema in `dist/geekodoc/rng/`. ### Installing it on Debian/Ubuntu @@ -170,7 +175,11 @@ To install GeekoDoc on Debian or Ubuntu from scratch, do the following steps: $ xmlcatalog /etc/xml/catalog \ https://github.com/openSUSE/geekodoc/raw/master/geekodoc/rng/geekodoc5-flat.rnc \ - urn:x-suse:rng:geekodoc5.rng + urn:x-suse:rng:geekodoc5.rng \ + urn:x-suse:rnc:v1:geekodoc-flat \ + urn:x-suse:rng:v1:geekodoc-flat \ + urn:x-suse:rnc:v2:geekodoc-flat \ + urn:x-suse:rng:v2:geekodoc-flat You should get something like this: @@ -203,8 +212,7 @@ for OBS, use the following steps: $ git config tar.tar.bz2.command "bzip2 -c" -2. Create an archive: +2. Create an archive and save it in your OBS directory (`OBSDIR`): - $ git archive --format=tar.bz2 --prefix=geekodoc-2.0.0/ -o /tmp/geekodoc-2.0.01.tar.bz2 HEAD + $ git archive --format=tar.bz2 --prefix=geekodoc-2.0.1/ -o /geekodoc-2.0.1.tar.bz2 HEAD -3. Copy the archive into your OBS directory. diff --git a/geekodoc/rng/README.md b/geekodoc/rng/README.md index d36b3ab..43ef499 100644 --- a/geekodoc/rng/README.md +++ b/geekodoc/rng/README.md @@ -12,7 +12,7 @@ There are two incarnations of the SUSE schema: * `geekodoc-v1.rnc`, `geekodoc-v2.rnc` These are the main files where development is taking place. - GeekoDoc v1 depends on `docbookxi.rnc` (version 5.1) whereas for + GeekoDoc v1 depends on `docbookxi.rnc` (version 5.1) whereas GeekoDoc v2 it depends on `dbitsxi.rnc` (version 5.2). Don't use this in a production environment. diff --git a/tests/run-tests.sh b/tests/run-tests.sh index cef3686..69971fa 100755 --- a/tests/run-tests.sh +++ b/tests/run-tests.sh @@ -79,7 +79,7 @@ function validator() { function print_help { cat <