\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#193: Simple Syntax Help System}
\date{April 29, 2004}
\author{Donal K. Fellows}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#193}&\textbf{Simple Syntax Help System}\\\hline
Author&

Donal K. Fellows \tipmail{donal.k.fellows}{man.ac.uk}
\\
Created&Thursday, \(\text{29}^{\text{th}}\) April 2004\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.3 $\\
Keywords&Tcl\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a simple scheme to allow commands to provide basic syntax help for themselves. This information would allow for more advanced processing by programs doing interactive input of Tcl commands (by providing a mechanism for them to discover what possible completions of the current command fragment are available) and could be processed automatically by the \textbf{interp alias} and \textbf{namespace ensemble} mechanisms so that help could be automatically extended to commands defined through those mechanisms.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Currently, Tcl commands are only partially consistent in how they provide information about their own syntax; the only way of getting any syntax help is by providing invalid input to the command, but not all commands have invalid input sequences (e.g. \textbf{list}) and nor is there any way of knowing what those invalid sequences are (where they do exist) unless you know the command beforehand.

Such help would be useful in a number of situations, such as command expansion in something like tkcon. It would also provide a mechanism for supplying the sort of detailed information which the likes of [incr Tcl]'s ensembles can generate, but which the Tcl ensembles of \cite{tip112} do not do (for the reason that this would produce output significantly different in kind from existing core commands.)

Note that I do not want to provide extended help such as might be obtained from manual pages; this help system is designed to be mechanically queryable first.

\section{Proposed Change}

There are two main components

\subsection{Data Model}

Every command would supply help for itself by providing a callback to generate the information on demand; there will be a compatability callback installed by default that states that the command may take any number of unknown arguments.

The result of the callback will be a list of command call descriptions. Each description will be itself a list of terms that describe a particular way of calling the command, with one term per argument. Each term may in turn be one of:
\begin{itemize}
\item{}
\textit{Required literal} --- this might be something like a subcommand name.
\item{}
\textit{Optional literal} --- a good example of this are the \textbf{then} and \textbf{else} words in a call to \textbf{if}.
\item{}
\textit{Required varying} (with name for display to the user) --- a normal argument which may be whatever the caller wants it to be, subject to the higher level constraints implicit in the name.
\item{}
\textit{Optional varying} (with name for display to the user) --- a normal optional argument.
\item{}
\textit{All remaining arguments} --- this would be used in the default help outlined above, but would also be useful for modelling the \textit{args} parameter to a procedure.
\end{itemize}

[ToDo: say how these are expressed in C code]

[ToDo: talk about how aliases and ensembles can do help construction]

[ToDo: talk about how such information can be partially derived in procedures]

\subsection{Information Access}

There will be a new subcommand of \textbf{info} to provide access to this information at the Tcl level: \textbf{help}. The first argument to \textbf{info help} will be the name of a command; if no further arguments are supplied, the result will be a multi-line string with one invokation per line; the invokations will be just the string parts with the literal/varying information omitted and the optional/required information converted into surrounding question marks.

Otherwise, the second argument to \textbf{info help} will be one of:
\begin{description}
\item[get]
Two optional arguments; an index into the list of help ``lines'' (first) and an index within the line (second). If one index is supplied, returns the list of values (without lit/var or opt/req info) for the indexed line. If two indexes are supplied, returns the string form for the indexed word within the indexed line. If no indexes are supplied, or returns a list of every such value list when no index is supplied.
\item[literal]
Two required arguments; an index into the list of help ``lines'' and an index into the list of values for that line. Returns a boolean that is true when the indexed word within the indexed line is a literal.
\item[required]
Two required arguments; an index into the list of help ``lines'' and an index into the list of values for that line. Returns a boolean that is true when the indexed word within the indexed line is required.
\end{description}

[ToDo: could \textbf{info help} be used as a mechanism for procedures to set their own help up?]

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#112]{tip112}
Donal K. Fellows,
\emph{Ensembles are Namespaces are Commands},
on-line at \url{http://purl.org/tcl/tip/112.html}
\end{thebibliography}
\end{document}
