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.
Valid GeekoDoc documents are also valid DocBook 5 documents.
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.
In general, we recommend using GeekoDoc 2 for all new projects.
-
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
-
New, versioned URIs:
-
Available for GeekoDoc 1 and GeekoDoc 2
-
General syntax:
urn:x-suse:FORMAT:VERSION:SCHEMA
-
FORMAT: can be
rnc
orrng
-
VERSION: can be
v1
orv2
-
SCHEMA:
geekodoc-flat
-
-
Includes the following URIs:
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
-
-
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
-
To use GeekoDoc for validating your XML documents with DAPS, add the
following line in your ~/.config/daps/dapsrc
and replace <URI>
with
one of the URIs above:
DOCBOOK5_RNG_URI="<URI>"
It is possible to add the previous line into a DC file.
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
The following procedure can be used for the latest openSUSE Leap release:
-
Add the
devel:languages:python
repository:-
for openSUSE Leap:
sudo zypper ar https://download.opensuse.org/repositories/devel:/languages:/python/openSUSE_Leap_\$releasever/devel:languages:python.repo
-
for openSUSE Tumbleweed:
sudo zypper ar https://download.opensuse.org/repositories/devel:/languages:/python/openSUSE_Tumbleweed/devel:languages:python.repo
-
-
Install the package:
sudo zypper in python3-rnginline
The executable can be found in /usr/bin/rnginline
.
-
Install the RPM packages
python3-devel
,libxml2-devel
, andlibxslt-devel
. On openSUSE, run:sudo zypper in python3-devel libxml2-devel libxslt-devel
-
Create a Python3 virtual environment:
python3 -m venv .env3
-
Activate the virtual environment:
source .env3/bin/activate
You should see a changed prompt (look for the
(.env3)
part). -
Install the
rnginline
library from PyPi:pip install rnginline
The executable can be found in .env3/bin/rnginline
.
-
Update your GitHub repository.
-
Run
./build.sh
. -
Find the built schema in
dist/geekodoc/rng/
.
To install GeekoDoc on Debian or Ubuntu from scratch, do the following steps:
-
Copy the XML catalog file to the standard location:
cp -v catalog.d/geekodoc.xml /etc/xml/geekodoc.xml
-
Adapt the paths in the catalog file:
sed -i 's#"\.\./#"/usr/share/xml/#' /etc/xml/geekodoc.xml
-
Create the target directory and copy the schema files:
mkdir -p /usr/share/xml/rng cp -v geekodoc/rng/*-flat.rn? /usr/share/xml/rng
-
Adapt the main XML catalog:
sudo xmlcatalog --noout --add delegateSystem \ https://github.com/openSUSE/geekodoc/ /etc/xml/geekodoc.xml /etc/xml/catalog sudo xmlcatalog --noout --add delegateURI "urn:x-suse:rng:" \ /etc/xml/geekodoc.xml /etc/xml/catalog sudo xmlcatalog --noout --add delegateSystem "urn:x-suse:rng:" \ /etc/xml/geekodoc.xml /etc/xml/catalog
-
Test the installation:
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: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:
/usr/share/xml/geekodoc/rng/geekodoc5-flat.rnc No entry for SYSTEM urn:x-suse:rng:geekodoc5.rng /usr/share/xml/geekodoc/rng/geekodoc5-flat.rng
To work with RELAX NG and vim, you need a .vim
file. This file is
generated from the flat RNG schema.
To extract all relevant information for Vim, use the rng2vim
tool from
https://github.com/jhradilek/rng2vim.
rng2vim geekodoc5-flat.rng geekodoc
The file geekodoc.vim
can be used with vim.
If you develop on GeekoDoc and would like to create an archive file for OBS, use the following steps:
-
Configure first the
bzip
command (this has to be done only once):git config tar.tar.bz2.command "bzip2 -c"
-
Create an archive and save it in your OBS directory (
OBSDIR
):git archive --format=tar.bz2 --prefix=geekodoc-2.0.1/ -o <OBSDIR>/geekodoc-2.0.1.tar.bz2 HEAD