improve documentation on special GAP syntax

oscar-system · Jul 20, 2023 · bdd2a0b · bdd2a0b
1 parent a30cb13
commit bdd2a0b
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 12 deletions.
diff --git a/docs/src/basics.md b/docs/src/basics.md
@@ -7,18 +7,24 @@ DocTestSetup = :(using GAP)
 
 ## Accessing GAP from Julia
 
-Any global GAP variable and function can be access from Julia via the
-[`GAP.Globals`](@ref) object; for example `GAP.Globals.Binomial(5,3)`.
-
-The [`GAP.prompt`](@ref) command can be used to switch to a GAP session that
-works like a regular GAP, except that leaving it (via `quit;` or by pressing
-Ctrl-D) returns one to a Julia prompt. From the GAP prompt, one can access
-Julia variables via the `Julia` object, for example `Julia.binomial(5,3)`. For
-more details on how to access Julia from GAP, please consult
-[the manual of the GAP package JuliaInterface](../assets/html/JuliaInterface/chap0_mj.html).
-
-Alternatively, one can start GAP in the traditional way, by executing a shell
-script. Such a script can be created in a location of your choice via [`GAP.create_gap_sh`](@ref).
+- Any global GAP variable and function can be accessed from Julia via the
+  [`GAP.Globals`](@ref) object; for example `GAP.Globals.Binomial(5,3)`.
+  See [Convenience adapters](@ref) for dealing with GAP syntax beyond
+  simple function calls.
+
+- The [`GAP.prompt`](@ref) command can be used to switch to a GAP session that
+  works like a regular GAP, except that leaving it (via `quit;` or by pressing
+  Ctrl-D) returns one to a Julia prompt. From the GAP prompt, one can access
+  Julia variables via the `Julia` object, for example `Julia.binomial(5,3)`.
+  For more details on how to access Julia from GAP, please consult
+  [the manual of the GAP package JuliaInterface](../assets/html/JuliaInterface/chap0_mj.html).
+
+- Alternatively, one can start GAP in the traditional way,
+  by executing a shell script.
+  Such a script can be created in a location of your choice
+  via [`GAP.create_gap_sh`](@ref).
+  Note that one cannot switch from such a GAP session to the underlying
+  Julia session and back.
 
 ```@docs
 Globals

diff --git a/docs/src/other.md b/docs/src/other.md
@@ -20,6 +20,24 @@ DocTestSetup = :(using GAP)
 This section describes how one can manipulate GAP objects from the Julia side,
 using Julia syntax features.
 
+In particular, the following is available on the Julia side
+in order to support special GAP syntax beyond function calls with arguments.
+
+- Access list/matrix entries via [`getindex`](@ref).
+
+- Access record components via [`getproperty`](@ref).
+
+- Access entries of a positional object via [`getbangindex`](@ref),
+  equivalent to GAP's `![]` operator.
+
+- Access components of a component object via [`getbangproperty`](@ref),
+  equivalent to GAP's `!.` operator.
+
+- Check for bound record components via [`hasproperty`](@ref).
+
+- Call functions with global options via [`call_gap_func`](@ref)
+  or using Julia's keyword argument syntax.
+
 ```@docs
 call_gap_func
 call_with_catch