summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.rst115
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.
=======================================================================
Installation
=======================================================================
-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: http://wiki.contextgarden.net/ConTeXt_Standalone#Installing_third_party_modules
-Manually
-********
-Firstly, get the module source from BitBucket_ (see the *downloads*
-section).
-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 https://bitbucket.org/phg/context-rst
+
+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: http://omake.metaprl.org/index.html
+.. _OPAM: http://opam.ocamlpro.com/
+
+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/zipball.zip
context --generate
-if the |CONTEXT| minimal distribution happens to be installed at
-``~/context/``.
+The zipballs are usually provided only for the releases that are
+uploaded to CTAN and the Context Garden.
+
+.. _TDS: http://tug.org/tds/tds.html
=======================================================================
Usage
=======================================================================
-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``
-subdirectory.
+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.
=======================================================================
License
@@ -81,3 +141,4 @@ dot ``com``.
.. _Contact: phg42.2a@gmail.com
.. _BitBucket: http://bitbucket.org/phg/context-rst
.. _maintainer: Contact_
+