Improve README

* Replace Travis batch to GitHub Action * Amend some missing information * Improve wording * Add some backtick markup * Add grammar/typo fixes Co-authored-by: Stefan Knorr <[email protected]>
openSUSE · Aug 27, 2021 · 17de5d4 · 17de5d4
1 parent 0f67ab8
commit 17de5d4
Show file tree

Hide file tree

Showing 3 changed files with 70 additions and 62 deletions.
diff --git 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,29 +58,39 @@ with one of the URIs above:
 
     DOCBOOK5_RNG_URI="<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`:
 
 * Install from an RPM package
 * 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 <OBSDIR>/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
@@ -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
@@ -79,7 +79,7 @@ function validator() {
 
 function print_help {
     cat <<EOF_helptext
-Run all the test cases using GeekoDoc schema v1 and v2
+Run test cases for GeekoDoc schema v1 and v2
 
 Usage:
    ${PROG} [-h|--help] [OPTIONS]