Re: [Axiom-developer] Re: Request for wh-sandbox and build-improvements

[Martin Rubey]

Waldek Hebisch <address@hidden> writes:

> Martin Rubey wrote:
> > 2) and install *.spad.pamphlet instead of *.spad into
> >    target/i686-pc-linux/src/algebra/
> >  
> >    That this didn't happen in the first place is *really* strange in my
> >    opinion.
>
> I suspect that even people advocating literate progammining do not consider
> _unprocessed_ pamphlets as human readable (to say the truth current Axiom
> sources contain many examples of using noweb for obfuscation).

Well, meanwhile I *do* prefer the pamphlet files, since several of them contain
a lot more information than the spad files.  Furthermore, I guess it might
encourage people to add documentation notes, even if they would only be for
themselves.

Since item 1) was the request to install "document", in whatever form, it is
easy to generate dvi or spad files.

So really, I beg that you adapt the change.

> > 3) apart of that, install the SPADEDIT script into target/i686-pc-linux/lib/
> > 
> >    I'll have to modify it a tiny little bit if you agree on (2).  In
> >    particular, it may make sense to make it obey an environment variable, 
> > say,
> >    AXIOMEDITOR, that contains the name of an editor to be called with two
> >    arguments, namely line-number and filename.
> > 
> >    However, I believe that any script is better than no script, because many
> >    people will not have write access to the target/i686-pc-linux/lib/
> >    directory, so they cannot use the HyperDoc functionality.
> > 
> > 
> > Well, I do not insist on (3). But (1) and (2) would be important to me.
>
> Hmm, 2 is easy to do.  But I wonder why you consider it important
> (I personally do not care very much one way or another because I
> typically have the whole build tree at hand).

There are two reasons:

* because of the hierarchy in our department, I maintain the "up to date"
  version of axiom, which currently is wh-sandbox.  I cannot place the build
  tree on the network file system, because of quota restrictions.  Thus,
  everytime I recompile, I would have to move the pamphlet files myself, move
  document and SPADEDIT into place.  It's simply a nuisance.  Another nuisance
  is having to manually make the aldor compatibility files.  It takes me about
  an hour every time I have to do it, since I tend to forget little things
  (eg., make 3.81beta does not work), and some bits change (eg., out of source
  build is preferred now).

* In my opinion, documenting the algebra is one of the most important goals of
  the project.  It is superb that I can ask you some things about Risch etc.,
  but most people I know do not want to ask "silly questions", and, maybe even
  more importantly, what are we going to do when you become broker on wall
  street?

  I consider installing the spad files as a very effective way to loose
  information and motivation to collect information.
 
> Concering 3: you solve nicely part of the problem (that is finding correct
> place in source files).  When I first saw you script I had doubts because
> user may have quite different preferences for editor/viewer and passing line
> numbers to editors can be quite compicated (I am affraid that there are still
> editors with no support for passing line numbers).  But now I think that the
> only way to "solve" problem of correct way to invoke editor is to make it
> user responsibility.

Great! We agree!

> More precisely, I think that user should have possibility to effectively
> replace SPADEDIT by own program.  Of course, most user will benefit from
> finding the correct place, so IMHO correct way is to provide in SPADEDIT
> escape to user code.  Your AXIOMEDITOR variable (or maybe call it
> SPADEDIT_ACTION) could do this if you pass to it just file name and line
> number (as two separate arguments).  In such case we probably should provide
> a few example editors -- that is shell functions which call say emacs, vi,
> maybe kdvi.

Yes. Furthermore, I'd default it to some editor or pager which is usually
installed. (mabe "less"?) Note that SPADEDIT is also called via )edit, so it is
also a MS Windows question.  I should also rename $number to $line.

emacs +$line $spadname
emacsclient +$line $spadname
xemacs +$line $spadname
gnuclient +$line $spadname
vi +$line $spadname
less +$line $spadname


kwrite --line $line $spadname
kate --line $line $spadname


any windows guis out there ;-) ?


Below you find the appropriate SPADEDIT, in case you are (which I hope)
implementing my request 1).



For kdvi, the case is a little more complicated, but not too much: most
importantly, we would need to find the right file number in the spad.tex file,
and the latter would have to be latex'ed with --src-specials enabled.  Then one
can say

kdvi file:mantepse.spad.dvi#src:34mantepse.spad.tex

But really, I'd leave this as a future project.


Martin

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass{article}
\usepackage{axiom}
\begin{document}
\title{SPADEDIT}
\author{Martin Rubey}
\maketitle
\begin{abstract}
  \verb|SPADEDIT| is a shell script that handles features to display or edit
  source files.
\end{abstract}

The script described here is called (at least) in two different situations:
\begin{itemize}
\item it is called by HyperDoc, when the user clicks on a link like
  \verb|INT.spad|. In this case it receives two arguments, namely 
  \begin{enumerate}
  \item the file in which HyperDoc believes the constructur is defined, which
    is currently of the form \verb|$AXIOM/../../src/algebra/INT.spad|, i.e.,
    the path to the source directory, then the abreviation of the constructor,
    and finally \verb|.spad| appended,

  \item the long name of the constructor.
  \end{enumerate} 

\item it is called from the interpreter, when the usser issues \verb|)edit|. In
  this case it receives exactly one argument, even if it \verb|)edit| had  no
  or several arguments supplied. 

  \begin{itemize}
  \item if several arguments were supplied, only the first is passed to
    \verb|SPADEDIT| and all the others are ignored.
  \item if no arguments were supplied, \verb|SPADEDIT| receives the last
    argument it received, or \verb|NIL| if so far \verb|)edit| was always
    called with no arguments. Furthermore, if the argument of \verb|)edit|
    starts with a dot, it is also not passed to \verb|SPADEDIT|.
  \end{itemize}
\end{itemize}

<<*>>=
#! /bin/bash

if [ $# -eq 1 ]; then
@

Thus, we were called by \verb|)edit| and can simply call the text editor of our
choice:

<<*>>=
 gnuclient $1 &

else
@

We are now in the case where we were called by HyperDoc. Since filenames
supplied by HyperDoc do not correspond to the filenames in the current Axiom
distribution as of [[patch-50]], we have to find the right file ourselves. We
simply ask grep the directory containing the source files to return file and
line number within that file. Note that, if only spad files are installed, we
should replace \verb|.spad.pamphlet| by \verb|.spad|.

<<*>>=
  f=$(basename $1 .spad)
  h=$(grep -n ")abb.* $f " $AXIOM/src/algebra/*.spad.pamphlet)
@

Note that we rather extract the abbreviation of the domain, instead of using
the full name. The reason is best explained by example. Consider the following
two lines in \verb|integer.spad|:

\begin{verbatim}
)abbrev package INTSLPE IntegerSolveLinearPolynomialEquation
\end{verbatim}

and

\begin{verbatim}
)abbrev domain INT Integer
\end{verbatim}

Note that the abreviated domain name is nicely delimited by two spaces, while
we do not know what follows the long domain name. There might be spaces and a
carriage return, maybe even comments are allowed\dots.

We assume that grep produces only one result. There is no way in Axiom to deal
with several domains having the same name anyway.

The next step is to obtain the name of the source file:
<<*>>=
  spadname=${h%%:*}
@

Since pamphlets are currently not installed, and {\LaTeX} is not called with
\verb|source-specials| enabled, displaying \verb|dvi| doesn't really work yet.

<<NOTYET *>>=
  name=$(basename $spadname)
  dviname=$AXIOM/doc/src/algebra/$name.dvi
@

Finally, we obtain the line number.

<<*>>=
  lineaux=${h#*:}
  line=${lineaux%:*}
@

Now we have everything to call our favorite editor:

<<*>>=
  gnuclient +$line $spadname
@

If \verb|dvi|'s were compiled with \verb|-source-specials|, we could also call
a \verb|dvi| viewer, for example

\begin{verbatim}
  kdvi file:$dviname#src:$line$name.tex
\end{verbatim}

but that doesn't work yet.  Furthermore, we would have to find the line number
in the \verb|.spad.tex| file.

<<*>>=  
fi
@

\end{document}