Creating Documents with Editable and Runnable Examples
The Ciao Prolog Playground provides several easy ways for creating documents with editable and runnable examples. This includes:- Creating Active Logic Documents: notebooks containing embedded runnable Prolog code examples, that can be edited, queried, etc.
- Embedding links to runnable examples and notebooks in arbitrary documents.
Creating notebooks: Active Logic Documents (ALDs)
The playground allows easily generating Active Logic Documents (ALDs): notebooks containing embedded runnable Prolog code examples, that can be edited, queried, etc.
- Click on this link to open it.
- Click on the pencil button on the top right to edit the document in the playground.
- See the playground usage page for other functionality available.
- In particular, clicking the Share! button will copy into the clipboard a link that can be used to open the document. This link can be sent by email, embedded in notes, etc.
ALD notebooks are very useful for developing tutorials, exercises, slides, manuals, etc. and in general any kind of document with runnable Prolog examples. The source for these documents is in (LPdoc) markdown and they can be easily shared, as shown in the example above. The documents and the embedded code run locally on the user's browser, without the need for a server. This provides many advantages such as scalability to any number of users, privacy, efficiency, etc.
This functionality is provided by an integration of LPdoc with the playground. The Editable and runnable examples and Documentation markdown language chapters of the LPdoc manual provides a description of the markdown syntax and other commands that can be used in ALDs.
Adding links to runnable examples and notebooks to arbitrary documents
Links to the playground that auto-upload examples or notebooks can be easily included in any document (slides, manuals, books, web sites, tutorials, articles, spreadsheets, class exercises, 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). And, this link (also obtained as described above) opens the following notebook:
\title A member look-alike
```ciao_runnable
:- module(_,_).
is_in_list(X,[X|_]).
is_in_list(X,[_|T]) :-
is_in_list(X,T).
```
Load (press **?**) and try for example:
```prolog_runnable
?- is_in_list(X,[1,2,3]).
``` For links to arbitrary size files you can also embed a link to the full source code using # as follows: https://ciao-lang.org/playground/#<URL>. E.g., for GitHub, https://ciao-lang.org/playground/#<GITHUBURL>, such as in this link.
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}
{\bf running it!}
\ \\
And this is an example of a
% URL also obtained from playground
\href{https://ciao-lang.org/playground/?code=%5Ctitle%20A%20member%20look-alike%0A%0A%60%60%60ciao_runnable%0A%3A-%20module(_%2C_).%0A%0Ais_in_list(X%2C%5BX%7C_%5D).%0Ais_in_list(X%2C%5B_%7CT%5D)%20%3A-%0A%20%20%20%20%20%20is_in_list(X%2CT).%0A%60%60%60%0ALoad%20(press%20**%3F**)%20and%20try%20for%20example%3A%0A%0A%60%60%60ciao_runnable%0A%3F-%20is_in_list(X%2C%5B1%2C2%2C3%5D).%0A%60%60%60%0A&ext=.md}
{\bf link to a simple notebook.}
\end{document}
and this the pdf output generated.
These are a few more examples in LaTeX. In this case we use the prologrun.sty style file provided in the playground examples directory:
\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
\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}
\end{enumerate}
\end{document}
and this the pdf output generated.
Word
And this is a simple example in Word (note: image below not clickable, open the pdf below instead):
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.