diff options
| -rw-r--r-- | README.rst | 115 |
1 files changed, 88 insertions, 27 deletions
@@ -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_ + |