diff --git a/Makefile b/Makefile index 3c5ccb5..7d1e213 100644 --- a/Makefile +++ b/Makefile @@ -44,7 +44,7 @@ install_DATA = \ install.scm doc_DATA = \ - doc/man.pdf + doc/man.pdf doc/html/*.html doc/html/*.css DATA = $(scheme_DATA) $(install_DATA) $(doc_DATA) diff --git a/doc/.tex2page.hdir b/doc/.tex2page.hdir new file mode 100644 index 0000000..724f4d4 --- /dev/null +++ b/doc/.tex2page.hdir @@ -0,0 +1 @@ +html \ No newline at end of file diff --git a/doc/man.tex b/doc/man.tex index f54a6d2..00b4506 100644 --- a/doc/man.tex +++ b/doc/man.tex @@ -1,6 +1,6 @@ % -*- latex -*- -% This is the reference manual for the Scheme Untergrund Networking Package. +% This is the reference manual for Commander S. \documentclass[twoside]{report} \usepackage{code,boxedminipage,makeidx,palatino,ct, @@ -19,18 +19,14 @@ \input{pdfcond} \ifpdf \usepackage[pdftex,hyperindex, - pdftitle={commander s manual, release 0.1}, + pdftitle={Commander S Manual, release 0.2}, pdfauthor={Martin Gasbichler and Eric Knauel} colorlinks=true,linkcolor=blue,pagecolor=blue,urlcolor=blue, pdfstartview=FitH,pdfview=FitH]{hyperref} \usepackage{thumbpdf} \usepackage{tocbibind} \else -\usepackage[dvipdfm,hyperindex,hypertex, - pdftitle={commander s manual, release 0.1}, - pdfauthor={Martin Gasbichler and Eric Knauel} - colorlinks=true,linkcolor=blue,pagecolor=blue,urlcolor=blue, - pdfstartview=FitH,pdfview=FitH]{hyperref} +\usepackage[dvipdfm,hyperindex,hypertex]{hyperref} \fi \endtexonly @@ -47,18 +43,17 @@ \frontmatter \title{Commander S Manual} -\subtitle{For Commander S release 0.1} +\subtitle{For Commander S release 0.2} \author{Martin Gasbichler, Eric Knauel} -\date{October 2005} +\date{June 2006} \mainmatter \maketitle -\tableofcontents - \include{overview} +\bibliographystyle{plain} +\bibliography{abbrevs,papers,books,collections,misc,theses} \backmatter -\printindex \end{document} diff --git a/doc/mantitle.sty b/doc/mantitle.sty new file mode 100644 index 0000000..b17f5b5 --- /dev/null +++ b/doc/mantitle.sty @@ -0,0 +1,76 @@ +% This is the title page style stolen from the Texinfo design, +% and expressed as a LaTeX style option. It is useful for manuals. +% +% Note that I play some *really* revolting games here to override +% the vertical and horizontal margins temporarily for the title page. +% The layout assumes you have 8.5" x 11" paper. You'd have to redo this +% for A4 or another size. +% -Olin 7/94 + + +% Fonts for title page: +\DeclareFixedFont{\titlefont}% + {\encodingdefault}{\familydefault}{bx}{\shapedefault}{20.5pt} +\DeclareFixedFont{\authorfnt}% + {\encodingdefault}{\familydefault}{bx}{\shapedefault}{14.4pt} +\DeclareFixedFont{\subtitlefnt}% + {\encodingdefault}{\familydefault}{m}{\shapedefault}{11} + +%\def\authorrm{\normalfont\selectfont\fontseries{bx}\fontsize{14.4}{14.4}} +%\def\subtitlefnt{\normalfont\selectfont\fontsize{11}{11}} + +\newskip\titlepagetopglue \titlepagetopglue = 2.5in + + +\newlength{\widewidth} +\setlength{\widewidth}{6.5in} +\newlength{\negwidemargin} +\setlength{\negwidemargin}{-\oddsidemargin} % Reset the margin +\addtolength{\negwidemargin}{-1in} % to edge of page +\addtolength{\negwidemargin}{1in} % Then move right one inch. + +%\def\wideline#1{\hbox to 0pt{\hspace\negwidemargin\hbox to\widewidth{#1}}} +\def\wideline#1{\hbox{\makebox[0pt][l]{\hspace\negwidemargin\hbox to\widewidth{#1}}}} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\def\maketitle{\begin{titlepage} + \thispagestyle{empty} + \let\footnotesize\small \let\footnoterule\relax + \null + \parindent=0pt + \def\subtitlefont{\normalbaselineskip = 13pt \normalbaselines \subtitlefnt}% + \def\authorfont{\normalbaselineskip = 16pt \normalbaselines \authorfnt}% +% + % Leave some space at the very top of the page. + \vspace*{-1in}\vspace*{-\topmargin}\vspace*{-\headheight}\vspace*{-\headsep} + \vglue\titlepagetopglue +% + \wideline{\titlefont \@title \hfill} % title +% \vskip4pt + \vskip -0.3\baselineskip + \wideline{\leaders\hrule height 4pt\hfill} + \wideline{\hfill\subtitlefont\begin{tabular}[t]{@{}r@{}}\@subtitle% + \\\@date% + \end{tabular}} % subtitle +% + % author + \vskip 0pt plus 1filll + \wideline{\authorfont \begin{tabular}[t]{@{}c@{}}\@author + \end{tabular}\hfill} +% +% \vskip4pt + \vskip -0.3\baselineskip + \wideline{\leaders\hrule height 2pt\hfill} + + % This weirdness puts the bottom line 2.75 in from the bottom of + % an 11in page. + \vskip \textheight \vskip \headsep \vskip \headheight + \vskip \topmargin \vskip 1in \vskip -11in \vskip 2.75in + + \gdef\@author{}\gdef\@title{}\gdef\@subtitle{}\let\maketitle\relax + \end{titlepage} + \setcounter{page}{2} + } + +\def\subtitle#1{\gdef\@subtitle{#1}} +\def\@subtitle{} diff --git a/doc/overview.tex b/doc/overview.tex index d5b5ad3..7244841 100644 --- a/doc/overview.tex +++ b/doc/overview.tex @@ -1,16 +1,72 @@ - \chapter{Overview} \label{cha:overview} -Commander S is a visual shell written in Scheme. +Commander S is a visual shell written in Scheme. The following +paragraph is the abstract of the paper ``Commander S --- The shell as a +browser''\cite{GasbichlerKnauel2005}: +\begin{quote} + Commander~S is a new approach to interactive Unix shells based on + interpretation of command output and cursor-oriented terminal + programs. The user can easily refer to the output of previous + commands when composing new command lines or use interactive viewers + to further explore the command results. Commander~S is extensible + by plug-ins for parsing command output and for viewing command + results interactively. The included job control avoids garbling of + the terminal by informing the user in a separate widget and running + background processes in separate terminals. Commander~S is also an + interactive front-end to scsh, the Scheme Shell, and it closely + integrates Scheme evaluation with command execution. The paper also + shows how Commander~S employs techniques from object-oriented + programming, concurrent programming, and functional programming + techniques. +\end{quote} +We recommend reading this paper to learn more about the ideas behind +Commander~S because this manual is very incomplete. If you want to +extend it, please send us patches! + + +\section{Installation} +\label{sec:installation} + +See the README file for information about installing Commander~S. + +\section{Builtin commands} +\label{sec:builtin-commands} + +Commander~S knows how to parse the output of the following commands +and will display the output in the result buffer: +\begin{description} +\item[ls] +\item[ps] +\item[printenv] +\item[fs] +\item[pwd] +\item[setenv] +\item[cd] +\item[jobs] +\end{description} + +For the following commands, special command line completers exist: +\begin{description} +\item[latex] +\item[xdvi] +\item[ftp] +\end{description} + +For the values returned by the following scsh procedures, Commander~S +possesses special viewers that allow an interactive inspection in the +result buffer: \texttt{user-info}, \texttt{group-info}, +\texttt{host-info}, \texttt{protocol-info}, \texttt{service-info}. All +other Scheme values \section{Key bindings} \label{sec:key-bindings} -Most of the key bindings are not configurable yet. +Most of the key bindings are not configurable yet. See +Section~\ref{sec:cust-comm-s} to learn how to configure the rest. -\subsection{General keybindings} +\subsection{Keybindings for the command buffer} \label{sec:general-keybindings} \begin{description} @@ -20,48 +76,114 @@ Most of the key bindings are not configurable yet. \item[Repaint] \texttt{[F2]} \item[Switch between command buffer and result buffer] \texttt{[Ctrl-x o]} -\item[Paste the selection] \texttt{[Ctrl-x p]} -\item[Paste the selection as focus object] \texttt{[Ctrl-x P]} -\item[Next item of result histroy] \texttt{[page up]} -\item[Previous item of result histroy] \texttt{[page down]} \item[Complete command or argument] \texttt{[TAB]} \end{description} -Line editing facilities: + +\subsection{Key bindings for the result buffer} +\label{sec:key-bindings-result} + + +\begin{description} +\item[Paste the selection to the command buffer] \texttt{[Ctrl-x p]} +\item[Paste the selection as focus object] \texttt{[Ctrl-x P]} +\item[Next item of result histroy] \texttt{[page up]} +\item[Previous item of result histroy] \texttt{[page down]} +\end{description} + +\subsection{Line editing} +\label{sec:line-editing} + +The following line editing keys are available in all text input fields +(e.g. the command buffer): \begin{description} \item[Moving to the start of the line] \texttt{[Ctrl-a]} \item[Moving to the end of the line] \texttt{[Ctrl-e]} \item[Moving the cursor to the left] \texttt{[Left arrow]} +\item[Moving the cursor to the right] \texttt{[Right arrow]} \end{description} -Select list facilities: + +\subsection{Select list} +\label{sec:select-list} + +The following key bindings are available in all \textit{select lists}, +which are input widgets with multiple rows: \begin{description} -\item[Mark/unmark item] \texttt{[m]} -\item[Enter item] \texttt{[RET]} +\item[Mark item] \texttt{[m]}, \texttt{(config 'select-list + 'select-list-mark-key)} +\item[Unmark item] \texttt{[u]}, \texttt{(config 'select-list + 'select-list-unmark-key)} +\item[Move up] \texttt{up arrow}, \texttt{(config 'select-list + 'select-list-move-up-key)} +\item[Move down] \texttt{down arrow}, \texttt{(config 'select-list 'select-list-move-down-key)} +\end{description} + +\subsection{Select line} +\label{sec:select-line} + +\textit{Select lines} are input widgets with a single row and multiple +columns. One column is always marked. The following key bindings are +available in all select lines: + +\begin{description} +\item[Move column marker right] \texttt{right arrow} +\item[Move column marker left] \texttt{left arrow} +\end{description} + +\subsection{Key bindings for completion window} +\label{sec:key-bind-compl} + +The completion window is displayed if several choices to complete the +user input exist. It contains a select list (see +Section~\ref{sec:select-list}) without the possibility to mark items. + +\begin{description} +\item[Exit completion window without selecting a completion] \texttt{ESC} +\item[Select completion] \texttt{RET} \end{description} \subsection{Key bindings for process object viewer} \label{sec:key-bindings-process} +The \texttt{ps} command creates a list of process objects. Besides the +select list key bindings from Section~\ref{sec:select-list} and the +select line key bindings from Section~\ref{sec:select-line}, the +following key bindings are active in the result viewer for this list: + \begin{description} \item[Filter processes] \texttt{[f]}, \texttt{(ps . filter-key)} -\item[Sort processes in increasing order] \texttt{[S]}, \texttt{(ps . sort-up-key)} +\item[Sort processes in increasing order] \texttt{[S]}, \texttt{(ps + . sort-up-key)}. Sorts according to marked column. \item[Sort processes in decreasing order] \texttt{[s]}, \texttt{(ps - . sort-down-key)} -\item[Select columns] \texttt{[c]}, \texttt{(ps . columns-key)} + . sort-down-key)}. Sorts according to marked column. +\item[Select columns] \texttt{[c]}, \texttt{(ps + . columns-key)}. Displays a select list where the user can mark + and unmark the columns to be displayed. \item[Kill process] \texttt{[k]}, \texttt{(ps . kill-key)} -\item[Re-run \texttt{ps}] \texttt{[g]}, \texttt{(ps . refresh-key)} +\item[Re-run \texttt{ps}] \texttt{[g]}, \texttt{(ps + . refresh-key)}. Re-runs the \texttt{ps} command. +\item[Select next process] \texttt{down arrow} +\item[Select previous process] \texttt{up arrow} \end{description} \subsection{Key bindings for file system object viewer} \label{sec:key-bindings-file} +The \texttt{ls} command creates a list of file system objects. Besides +the key bindings for select lists (Section~\ref{sec:select-list}) and +select lines (Section~\ref{sec:select-line}) the following key +bindings are active in the result viewer for this list: -\subsection{Key bindings for Scheme value inspector} -\label{sec:key-bindings-scheme} - -Very similar to the Scheme~48 standard bindings. +\begin{description} +\item[Sort files in increasing order] \texttt{[S]}, \texttt{(ps + . sort-up-key)}. Sorts according to selected column. +\item[Sort files in decreasing order] \texttt{[s]}, \texttt{(ps + . sort-down-key)}. Sorts according to selected column. +\item[Display directory] \texttt{RET}. Opens a new viewer for the + selected directory. +\end{description} \section{Customizing Commander S} \label{sec:cust-comm-s} @@ -71,9 +193,43 @@ should contain an alist mapping configuration options to values. For example: % \begin{verbatim} -(((main . switch-command-buffer-mode-key) . 262)) +(((main . switch-command-buffer-mode-key) . key-home) + ((main . show-shell-key) . key-select)) \end{verbatim} + + +\section{Scheme commands} +\label{sec:scheme-commands} + +Commander~S offers a subset of the commands provides by the command +processor of Scheme~48 (or scsh). See Chapter~3 of the Scheme~48 +manual for a detailed description of the following commands available +in Commander~S: + +\begin{description} +\item[\texttt{in}] +\item[\texttt{open}] +\item[\texttt{user}] +\item[\texttt{inspect}] The inspection happens in the result window + and the user can use the arrow keys in addition to the \texttt{u} + and \texttt{d} keys known from Scheme~48 to browse the value. There + is currently no focus object in Commander~S. +\item[\texttt{reload-package}] +\item[\texttt{exit}] +\end{description} + + +\section{Contributing} +\label{sec:contributing} + +We highly appreciate any kind of contribution to the Commander~S +project. To that end, we have set up a darcs repository at +\url{http://www-pu.informatik.uni-tuebingen.de/users/gasbichl/darcs/commander-s}. +Please send patches via e-mail to +\url{mailto:gasbichl@informatik.uni-tuebingen.de}. + + % Local Variables: % TeX-master: "man" % End: diff --git a/install.scm b/install.scm index dd3ff75..c2f311d 100755 --- a/install.scm +++ b/install.scm @@ -34,6 +34,10 @@ END )) (define-program "commander-s" (0 2) ((install-lib-version (1 3))) + ;; Install documentation + (install-file "doc/man.pdf" 'doc "pdf") + (install-directory-contents "doc/html" 'doc "html") + (install-directory-contents "scheme" 'scheme) (install-file "commander-s" 'bin))))