1<?xml version="1.0" encoding="UTF-8"?>
2
3<!-- This is an automatically generated file. -->
4<Chapter Label="Intro">
5<Heading>Introduction</Heading>
6
7<Section>
8<Heading>GAP Jupyter Kernel</Heading>
9
10This package provides a so-called <E>kernel</E> for the
11<URL Text="Jupyter">https://jupyter.org</URL> interactive document system.
12
13This kernel is implemented in &GAP;.
14
15</Section>
16
17
18<Section>
19<Heading>Installation</Heading>
20
21This package requires &Jupyter; to be installed on your system, which
22on most Python installations can be achieved by issuing the following command.
23<Log>
24> pip install --user notebook
25</Log>
26Further instructions can be found at  <URL>https://jupyter.org/install</URL>.
27This package requires the &GAP; packages &IO;, &uuid;, &ZeroMQInterface;,
28&crypting;, and &json;, all of which are distributed with &GAP;, and some of which
29require compilation.
30To compile &ZeroMQInterface; you need to install &ZeroMQ;, for details please refer to the
31<URL Text="ZeroMQInterface manual">https://gap-packages.github.io/ZeroMQInterface/doc/chap0.html</URL>.
32
33&JupyterKernel; itself does not contain any kernel code that needs to be compiled.
34
35It is necessary to register &JupyterKernel; with your &Jupyter; installation.
36
37Registering the GAP jupyter kernel system-wide works as follows:
38<Log>
39> python setup.py install
40</Log>
41
42or registering for your user only
43
44<Log>
45> python setup.py install --user
46</Log>
47
48If &GAP; is not in your PATH, then you have to set the environment variable
49<C>JUPYTER_GAP_EXECUTABLE</C> to point to your GAP executable for &Jupyter; to
50be able to execute &GAP;, and the script <C>jupyter-kernel-gap</C> that is
51distributed with this package in the directory <C>bin/</C> needs to be in
52your path.
53
54To start &Jupyter; run:
55<Log>
56> jupyter notebook
57</Log>
58Then &JupyterKernel; should show up in your &Jupyter; installation as "GAP 4".
59
60</Section>
61
62<Section>
63<Heading>How it works</Heading>
64
65<Subsection>
66  <Heading>Kernel Startup</Heading>
67
68  This section gives a short explanation how the process of executing &GAP; as a
69  kernel by &Jupyter; works to help with debugging issues.
70
71  &Jupyter; registers kernels using json files in various directories. You can
72  list which kernel specifications are installed by executing the following
73  command
74
75  <Log>
76    > jupyter kernelspec list
77    Available kernels:
78    python2        /usr/local/lib/python2.7/site-packages/ipykernel/resources
79    gap-4          /usr/local/share/jupyter/kernels/gap-4
80  </Log>
81
82  If there is no line containing the <C>gap-4</C> kernel, something went
83  wrong with <C>setup.py</C>. You can try to manually install the file
84  <C>kernel.json</C> which is in the <C>etc</C> directory of the &JupyterKernel;
85  package by copying it. Better yet, you should report this issue on the issue
86  tracker giving wich operating system you are using, your version of &Jupyter;
87  and &GAP;, and which commands you tried to execute.
88
89  What happens when &Jupyter; wants to start a &GAP; kernel is that it tries
90  to execute the small script <C>jupyter-kernel-gap</C> (which is distributed with
91  the &JupyterKernel; package), which in turn executes &GAP;, loading the package
92  and then running the kernel. This script currently has to be in your <C>PATH</C>
93  environment variable, too.
94</Subsection>
95
96<Subsection>
97  <Heading>Kernel operation</Heading>
98
99  The communication between the &Jupyter; frontend and &GAP; happens through ZeroMQ streams
100  as documented
101  <URL  Text="here">http://jupyter-client.readthedocs.io/en/latest/messaging.html</URL>,
102  encoded as <C>JSON</C> dicts.
103
104  After entering code into a cell and instructing &Jupyter; to execute that code,
105  the jupyter frontend sends the code to the &GAP; session where it is executed by
106  using the &GAP; function <C>READ_ALL_COMMANDS</C>, resulting values of the
107  execution are rendered using <C>ViewString</C> and sent back to the &Jupyter;
108  frontend.
109
110  In principle, rich rendering of content, as exemplified in the function
111  <C>JUPYTER_DotSplash</C> is possible.
112
113  Tab-completion is handled by the &GAP; function <C>JUPYTER_completion</C>, and
114  inspection is handled by <C>JUPYTER_Inspect</C>.
115
116  Changing these functions, one can change the behaviour of Tab-completion and
117  inspection to improve user experience.
118</Subsection>
119</Section>
120
121<Section Label="Code Highlighting and Indentation">
122  <Heading>Code Highlighting and Indentation</Heading>
123
124  &JupyterKernel; provides a &GAP; mode with code highlighting and indentation.
125  This mode is installed as a notebook extension and registers 'text/x-gap' as
126  a MIME type.
127
128</Section>
129
130<Section Label="Known Limitations and Caveats">
131  <Heading>Known Limitations and Caveats</Heading>
132
133  Currently the support of the &GAP; system for alternative frontends is
134  a work in progress. In particular, certain outputs that are
135  printed by &GAP; cannot be captured by the &Jupyter; frontend and will
136  not show up.
137
138  If you happen to notice problems of this kind, feel free to report them
139  on the <URL Text="issue tracker">https://github.com/gap-packages/JupyterKernel/issues</URL>.
140  or suggest a solution via a pull-request.
141</Section>
142
143<Section Label="feedback">
144<Heading>Feedback</Heading>
145
146For bug reports, feature requests and suggestions, please use our
147<URL Text="issue tracker">https://github.com/gap-packages/JupyterKernel/issues</URL>.
148
149</Section>
150
151
152</Chapter>
153