Improve documentation a bit

docs/src/other.md

@@ -23,21 +23,25 @@ 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).
+- Call functions with global options via [`call_gap_func`](@ref)
+  or using Julia's keyword argument syntax. For example,
+  `Cyc(1.41421356 : bits:=20)` in GAP translates to
+  `GAP.Globals.Cyc(GAP.Obj(1.41421356); bits=20)` in Julia.
+
+- Access list/matrix entries via [`getindex`](@ref) and [`setindex!`](@ref)
+  respectively the corresponding Julia syntax (described there).
 
-- Access record components via [`getproperty`](@ref).
+- Access record components via [`getproperty`](@ref) and [`setproperty!`](@ref)
+  respectively the corresponding Julia syntax (described there).
+
+- Check for bound record components via [`hasproperty`](@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

src/ccalls.jl

@@ -119,11 +119,12 @@ Note that screen outputs caused by evaluating `cmd` are not shown
 by `evalstr`; use [`evalstr_ex`](@ref) for accessing both the outputs
 and the return values of the command(s).
 
-Note also that using `evalstr` is often not the best way to create
-GAP objects or to call GAP functions.
-(In fact, it is likely that something is missing from GAP.jl
-if `evalstr` is the only way to formulate some lines of code.)
-Alternatively, use `GAP.GapObj` or `GAP.Obj` for constructing GAP objects
+In general we recommend to avoid using `evalstr`, but it sometimes can
+be a useful escape hatch to access GAP functionality that is otherwise
+impossible to difficult to reach. But in most typical scenarios it
+should not be necessary to use it at all.
+
+Instead, use `GAP.GapObj` or `GAP.Obj` for constructing GAP objects
 that correspond to given Julia objects,
 and call GAP functions directly in the Julia session.
 For example, executing `GAP.evalstr( "x:= []; Add( x, 2 )" )`