1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
=======================================================================
General Advice
=======================================================================
Read the section *Features Not Implemented* in the manual first.
*Note*: if you happen to read this on BitBucket_, the error messages
some lines below just mean that *their* implementation doesn’t
understand |TeX| directives. Don’t worry, |rstcontext| does.
=======================================================================
Installation
=======================================================================
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 specified the parameter ``--modules=all``.
.. _source: http://wiki.contextgarden.net/ConTeXt_Standalone#Installing_third_party_modules
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_.
::
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
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 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=../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 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.
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
=======================================================================
|rstcontext| is free software and may be redistributed under the terms
of the 2-clause BSD license. You should have recieved a copy of this
license in a file named “COPYING” in the source tree. If there is no
such file then please contact the maintainer_ (Contact_).
=======================================================================
Contact
=======================================================================
|rstcontext| was written by Philipp Gesang, ``phg42.2a`` at ``gmail``
dot ``com``.
.. |rstcontext| ctx:: {{\em rst}\kern.5pt\CONTEXT}
.. |TeX| ctx:: {\TEX}
.. |CONTEXT| ctx:: {\CONTEXT}
.. _Contact: phg42.2a@gmail.com
.. _BitBucket: http://bitbucket.org/phg/context-rst
.. _maintainer: Contact_
|
