path: root/README.rst
diff options
authorPhilipp Gesang <>2014-03-02 12:22:34 +0100
committerPhilipp Gesang <>2018-12-02 21:09:41 +0100
commit02a44bc281416e9979c8bc507e01ffb7f1a17962 (patch)
tree7aa56033efdef5e0182e88b0a2eb0af3b91bccd0 /README.rst
parent87b50c45f54979eaa905a32c73ba331ff335281c (diff)
update README
Diffstat (limited to 'README.rst')
1 files changed, 88 insertions, 27 deletions
diff --git a/README.rst b/README.rst
index 571b8ae..8b4f6d5 100644
--- a/README.rst
+++ b/README.rst
@@ -11,52 +11,112 @@ understand |TeX| directives. Don’t worry, |rstcontext| does.
-With ConTeXt Standalone
+The stable version -- with ConTeXt Standalone
An up to date version of the module is installed along with the ConTeXt
distribution (*Standalone*, formerly known as *The Minimals*).
The module should be working out of the box if you installed from the
-official source_ and provided the parameter ``--modules=all``.
+official source_ and specified the parameter ``--modules=all``.
.. _source:
-Firstly, get the module source from BitBucket_ (see the *downloads*
-In order to install |rstcontext|, copy everything in the ``mod/``
-subdirectory into your local |CONTEXT| tree and update the filename
-database, i.e. ::
+The development version -- from the Mercurial repository
+The module package is built using omake_ which you can install via your
+distribution’s package manager or through OPAM_.
- cp -r mod/* ~/context/tex/texmf-local/
+ opam install omake
+Now retrieve the repository using Mercurial:
+ hg clone
+You should end up with a directory ``context-rst`` containing the
+bare source code.
+In order to build the manual, you already need |rstcontext| installed
+-- a minor inconvenience that may vanish in a future release.
+Assuming you have downloaded the module as part of your distribution
+-- see the previous section for details --, you can now build the
+package using these commands:
+ cd context-rst
+ omake tds
+This will build the manual and package a zipball in the ``build/``
+subdirectory that you can extract directly into your Context TEXMF.
+If you are curious about the repository then issue
+ omake usage
+to print a list of available targets.
+.. _omake:
+.. _OPAM:
+Manual installation from the packaged zipballs
+The source repository can be downloaded as a ``.zip`` archive from
+BitBucket_ (see the *downloads* section).
+This zipball extracts into a TDS_ compliant directory tree that can be
+extracted directly into the Context TEXMF.
+For example, if your Context distribution is located in ``~/context``,
+then unzip the archive into your local TEXMF like so:
+ cd ~/context/tex/texmf-local/
+ unzip /path/to/
context --generate
-if the |CONTEXT| minimal distribution happens to be installed at
+The zipballs are usually provided only for the releases that are
+uploaded to CTAN and the Context Garden.
+.. _TDS:
-As rstConTeXt was developed on *texlua*, you may expect it to run best
-with this interpreter. For now the script accepts two command line
-arguments: the input file and the output file. The following will
-demonstrate the main usage in a separate directory: ::
+As |rstcontext| was developed on *texlua*, you may expect it to run
+best with this Lua interpreter. For now the script accepts two command
+line arguments: the input file and the output file. The following
+snippet will demonstrate the main usage in a separate directory.
+Assuming the contents of the TDS zipball were extracted to the current
+directory you can build the documentation manually like so:
+ mkdir tmp; cd tmp
+ mtxrun --script rst --if=../doc/context/third/rst/documentation.rst --of=doc.tex
+ context ../doc/context/third/rst/manual.tex
+Alternatively, if you downloaded the Mercurial repository, simply issue
mkdir tmp; cd tmp
- mtxrun --script rst --if=../mod/doc/context/third/rst/documentation.rst --of=doc.tex
- context ../mod/doc/context/third/rst/manual.tex
+ mtxrun --script rst --if=../doc/documentation.rst --of=doc.tex
+ context ../doc/manual.tex
+If |rstcontext| is currently not installed in your Context tree, then
+you can just link the required file to the ``tmp`` directory:
+ ln -s ../src/* .
+Now the documentation should build regardless.
This should have gotten you the manual converted to a file ``doc.tex``
-which was subsequently run through |CONTEXT| to generate the final
-``manual.pdf``. You will find extended instructions on how to build the
-manual with some cosmetic improvements in the section *Usage* of the
-manual itself.
+which was subsequently included by ``manual.tex`` which was run through
+|CONTEXT| to typeset the final ``manual.pdf``. You will find extended
+instructions on how to build the manual with some cosmetic improvements
+in the section *Usage* of the manual itself.
-There is also a small module ``t-rst.mkiv`` which permits direct
-typesetting of reST markup with |CONTEXT| MkIV. For usage examples see
-the files ``hybridtest.tex`` and ``moduletest.tex`` in the ``doc``
+Also Part of the package is a small module ``t-rst.mkiv`` which permits
+direct typesetting of reStructuredText markup in |CONTEXT| MkIV source
+files. For usage examples see the files ``hybridtest.tex`` and
+``moduletest.tex`` in the ``doc`` subdirectory.
@@ -81,3 +141,4 @@ dot ``com``.
.. _Contact:
.. _BitBucket:
.. _maintainer: Contact_