Creating Documents with Editable and Runnable Examples
The Ciao Prolog Playground provides an easy way to embed editable and runnable short code snippets in manuals, tutorials, slides, exercises, etc., and in general any kind of document. The following sections show how to embed runnable and editable snippets in LPdoc documentation, Google Docs, Jupyter notebooks, Word, Powerpoint, LaTeX, Pages, Keynote, Org mode, web site generators, etc., etc.Editable and runnable examples using LPdoc
LPdoc offers seamless integration with the playground, allowing runnable and editable code blocks in LPdoc generated documentation. You can consult Editable and Runnable Examples in the LPdoc manual for more information and examples.
Adding runnable examples to arbitrary documents
Links to the playground that auto-upload examples can be easily included in any document (slides, manual, book, web site, tutorial, article, spreadsheet, etc.) provided the tool used for editing allows including links to URLs. This includes Google Docs, Jupyter notebooks, Word, Powerpoint, LaTeX, Pages, Keynote, HTML, Org mode, web site generators, etc., etc.
The URL to be included in the link can easily be obtained as follows:
- Paste or upload the example program into the playground editor.
- Click the Share! button. This will copy into the clipboard a link to an instance of the playground with the program included.
- Go to the document with the example and insert the link in the document as a URL.
The examples are stored in the documents themselves (URI-encoded) and do not need to be uploaded to (or edited in) any server.
Now, if one clicks on this link, the playground will be opened with the example program loaded.
For example, this link (obtained as described above) opens the playground and loads into its editor the following program:
% Try: ?- is_in_list(X,[1,2,3]).
is_in_list(X,[X|_]).
is_in_list(X,[_|T]) :-
is_in_list(X,T). We show below some examples of this embedding for different source formats.
LaTeX
This is a simple example in LaTeX:
\documentclass{article}
\usepackage{hyperref}
\begin{document}
\noindent
This is a classic example of a Prolog program, which appends two lists:
\begin{verbatim}
app([],X,X).
app([X|Y],Z,[X|W]) :- app(Y,Z,W).
\end{verbatim}
\noindent
Try now
% URL obtained from playground
\href{https://ciao-lang.org/playground/?code=app(%5B%5D%2CX%2CX).%0Aapp(%5BX%7CY%5D%2CZ%2C%5BX%7CW%5D)%20%3A-%0A%20%20%20%20%20app(Y%2CZ%2CW).%0A}
{running it!}
\end{document}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End:
and this the pdf output generated.
These are a few more examples in LaTeX:
\documentclass{article}
\usepackage{cmbright}
\usepackage{graphicx}
\usepackage[ciao]{prologrun}
\begin{document}
\vspace*{-5mm}
\thispagestyle{empty}
\noindent
These are examples of several ways to list (Ciao)Prolog code in a
LaTeX document including a link for loading and running the
example on the \href{https://ciao-lang.org/playground}{Ciao
playground}. The link is obtained by pasting the program into the
Ciao playground and using the
% \mbox{} \hfill
\includegraphics[scale=.4,trim=0 12 0 0]{ShareLight.png} button to
create the link (containing the program) and copy it into the
clipboard, from which it can be pasted into the LaTeX
document. This file uses the \texttt{prologrun.sty} style file provided with the playground.\\ [-3mm]
\begin{enumerate}
\item Using a
\href{https://ciao-lang.org/playground/?code=app(%5B%5D%2CX%2CX).%0Aapp(%5BX%7CY%5D%2CZ%2C%5BX%7CW%5D)%20%3A-%0A%20%20%20%20%20app(Y%2CZ%2CW).%0A}
{simple link}\ .
\ \\
This is generated by:
\begin{lstlisting}[language=TeX,basicstyle=\small\ttfamily]
\href{https://ciao-lang.org/playground/...}{simple link}
\end{lstlisting}
\bigskip
\item Using the \texttt{runlink} macro:
\runlink{https://ciao-lang.org/playground/?code=app(%5B%5D%2CX%2CX).%0Aapp(%5BX%7CY%5D%2CZ%2C%5BX%7CW%5D)%20%3A-%0A%20%20%20%20%20app(Y%2CZ%2CW).%0A}
\ \\
This is generated by:
\begin{lstlisting}[language=TeX,basicstyle=\small\ttfamily]
\runlink{https://ciao-lang.org/playground/...}
\end{lstlisting}
\bigskip
\item Using the \texttt{runlink} macro before a standard code area:
\hfill \runlink{https://ciao-lang.org/playground/?code=app(%5B%5D%2CX%2CX).%0Aapp(%5BX%7CY%5D%2CZ%2C%5BX%7CW%5D)%20%3A-%0A%20%20%20%20%20app(Y%2CZ%2CW).%0A}
\begin{prolog}
append([],X,X).
append([X|Y],Z,[X|W]) :-
append(Y,Z,W).
\end{prolog}
\ \\
This is generated by:
\begin{lstlisting}[language=TeX,basicstyle=\small\ttfamily]
\hfill \runlink{https://ciao-lang.org/playground/...}
\begin{prolog}
append([],X,X).
append([X|Y],Z,[X|W]) :-
append(Y,Z,W).
\end{prolog}
\end{lstlisting}
\bigskip
\item Declaring the link first and using a \texttt{prologrun} code area:
\codelink{https://ciao-lang.org/playground/?code=app(%5B%5D%2CX%2CX).%0Aapp(%5BX%7CY%5D%2CZ%2C%5BX%7CW%5D)%20%3A-%0A%20%20%20%20%20app(Y%2CZ%2CW).%0A}
\begin{prologrun}
append([],X,X).
append([X|Y],Z,[X|W]) :-
append(Y,Z,W).
\end{prologrun}
\ \\
This is generated by:
\begin{lstlisting}[language=TeX,basicstyle=\small\ttfamily]
\codelink{https://ciao-lang.org/playground/...}
\begin{prologrun}
append([],X,X).
append([X|Y],Z,[X|W]) :-
append(Y,Z,W).
\end{prologrun}
\end{lstlisting}
% \ \\
% \item This is with a more bespoke macro (\texttt{prologrunalt}), with
% extra argument to pass the URL, but the URL needs to be escaped:
% \begin{prologrunalt}[] % The [] is needed!
% {https://ciao-lang.org/playground/?code=app(%5B%5D%2CX%2CX).%0Aapp(%5BX%7CY%5D%2CZ%2C%5BX%7CW%5D)%20%3A-%0A%20%20%20%20%20app(Y%2CZ%2CW).%0A}
% append([],X,X).
% append([X|Y],Z,[X|W]) :-
% append(Y,Z,W).
% \end{prologrunalt}
\end{enumerate}
\end{document}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End:
and this the pdf output generated.
Word
And this is a simple example in Word (note: image below not clickable):
This is the word file, here exported to pdf.
Org
Another example, in Emacs Org mode:
#+OPTIONS: toc:nil num:0 * The append example This is a classic example of a Prolog program, which appends two lists: #+BEGIN_SRC ciao app([],X,X). app([X|Y],Z,[X|W]) :- app(Y,Z,W). #+END_SRC Try now [[https://ciao-lang.org/playground/?code=app(%5B%5D%2CX%2CX).%0Aapp(%5BX%7CY%5D%2CZ%2C%5BX%7CW%5D)%20%3A-%0A%20%20%20%20%20app(Y%2CZ%2CW).%0A][running it!]]
And this is the result exported to pdf.