Glitches in documentation

[Waldek Hebisch]

I have noticed few glitches in documentation. One trouble is
'/\' and '\/' operators. They (a least in some places) show
wrongly in HyperDoc. I added a hack to TeX parser in api2.spad,
so that backslash in '/\' is treated as part of text. But this
is potentially fragile, as somebody may wish to use division
sign immediately followed by a TeX macro. I do not think that
such thing happens in docstrings, but clearly could happen in
more general TeX source. So probably we should transform
'/\' in docstrings to a TeX macro, so that no hacks are needed
later.

Second trouble is abbreviation 'w.r.t.' which appears in
several docstrings. This is currently transformed to '\spad'
(probably by preprocessing in 'src/intep/c-doc.boot').
In HyperDoc this does not cause visible trouble, but in
HTML output '\spad' is shown quite differently than normal
text. We could mark such things with '\spadignore'.
Alternatively we could expand the abbreviation and write
'with respect to' which actually shorter than
'\spadignore{w.r.t.}'. Potentially there may be more
abbreviations.

Third glitch is '\spadvar' macro used in some docstrings.
Things like '\spadvar{x}' seem to be transformed to
'\spadvar{\spad{x}}' which is redundant, but does not
cause trouble in HyperDoc. I am not sure if we really
want to have '\spadvar' (and not '\spad'), but if we keep
'\spadvar' we should have proper handling. Currently
'api2.spad' treat '\spadvar' as identity which seem to give
right result, but is not entirely OK (in particular this
would fail to mark 'x' if preprocessing just keeps '\spadvar').
'api.spad' just puts 'spadvar{x}' in the output (with 'x'
marked due to '\spad'). Anyway, it seems to me that we
should either keep '\spadvar{x}' as is in preprocessing step
and correctly mark it later, or replace it in docstrings
by '\spad'.

--
Waldek Hebisch