---
# Important information to start with
## Reading conventions
This document follows the following reading conventions:
- **bold** is for emphasizing notes and reminders.
- `verbatim` is for representing code snippets and commands, keys and file names.
- `Ctrl` and `Cmd` represent the "Control" and "Command" keys, respectively.
The former is avaible on Windows and Gnu/Linux platforms and the last one
is available on Mac platform.
When we use that key in combination with other that needs to be pressed at
the same time, we use `+` and the other key, so `Ctrl + s` represent the
simultaneos pressing of the keys `Ctrl` and `s` at the same time.
Keyboard shorcuts that contain `Ctrl` on Windows and Gnu/Linux, can be
replaced by `Cmd` on Mac and to ease reading we don't repeat each shorcut
on each platform.
Sometimes we will put the keyboard shortcut in parenthesis, just after the action it
referst to, like in "Open the spotter (`Shift` + `Enter`)".
- When we refer to menus and submenus in the Graphical User Interface (GUI), we will
use `>` as an indicator of the menus hirarchy.
For example, writing `Update > Grafoscopio`, means to choose the `Update` menu
and then the `Grafoscopio` submenu in it.
- The PDF and HTML versions of this document include clickable links and words, that
are shown in blue, for example the following words are a clickable link to the
[Grafoscopio web page][grafoscopio-en].
[grafoscopio-en]: http://mutabit.com/grafoscopio/index.en.html
## Document and software versions
As convention, this manual has the same version of the software it documents.
So the version number you see on bottom left side of each page, corresponds
also to the Grafoscopio version.
Because we follow a [rolling-release][] model for Grafoscopio, it is possible
that the software and the documentation get out of sync.
Use the `Update` menu from the docking bar to get the latest software and
documentation, as will be explained later.
Grafoscopio is packaged with other companion software, that is installed
automatically with it. This is the info for that packages and theri versions
## On commons, copyright and copyfarleft
Grafoscopio is covered with the same MIT license as Pharo.
This document is covered by the P2P license.
Both are pretty liberal licenses that grant you a pletora of rights
but I think that documentation and software do not need to have
the same license, even in the case of Grafoscopio, where
*interactive documentation is closer to software*.
I (Offray Luna) think that a deeper discusion on licences and
the protection and expansion of knowledge as a commons is needed
and this licenses difference reflect that.
You can see a full copy of both licenses, MIT and P2P, included at the end
of this
# Grafoscopio for what and for whom?
Grafoscopio is moldable tool [@girba_scg:_2014] for literate computing
[@perez&granger-2015], intertwining prose, code and agile data visualizations [@bergel-2015],
in a tree-like interactive document metaphor, developed on the Pharo
live coding and computing integrated environment.
Because of the continuity and uniformity of the environment, Grafoscopio blurs
the distinction between code, data, document, application and IDE and tries to
blur the distinction between interactive documents authors and software developers
[@luna-2017].
Grafoscopio has been developed in the context of a PhD research in a hackerspace of
the Global South ([HackBo][hackbo] in Bogotá, Colombia), instead of a academic institution
of the Global North and, from this particular context, approaches concerns like reproducible research,
simple and self contained *pocket infrastructures* (that work off-line/on-line from
USB thumb drives and/or low resources machines [@luna2014]), citizen science and data activism [@luna-2014].
[hackbo]: http://hackbo.co/
As such, Grafoscopio is intended to be used by learners and researchers in several fields:
academia, journalism, activism, hackctivits and for anyone interested in open reproducible research
and data storytelling backed by data and visualizations.
This document assumes that you are such person.
We will introduce the general features of Grafoscopio and point to several online resources to complete
your panoramic view of the ecosystem and to deep your knowledge.
Grafoscopio includes introductory resources to learn Pharo and data visualization related technologies,
in the `Help > Tutorial (Spanish)`, and the [web page][grafoscopio-en] (see figure \ref{fig:web-page-en})
shows several examples of how to use them for specific projects:
Panama Papers as reproducible research; open community innovation in access to medicine information;
Twitter data selfies; specific domain visualizations for medicine information;
open, garage and citizen science and research.
*This manual was also wrote using Grafoscopio* and is also a sample of what you can do with this tool.
We hope to inspire you to create and publish your own projects.
This document, by not try to be comprenhensive, is a first invitation to know the
Grafoscopio environment and to deep your knowledge with the use of it and other
related resources.
You will see that some examples are pretty practical.
No prior knowledge of programming is supposed to follow this manual.
![Detail for the Grafoscopio [English web page][grafoscopio-en]](../../../Imagenes/grafoscopio-webpage-en.png){#fig:web-page-en}
**IMPORTANT NOTE:** Despite of being pretty usable, you will see that Grafoscopio is not totally finished,
and this shows in a few spots of the Graphical User Interface (GUI) that "point to the future", towards
funtionality still to be implemented.
It's an unusual approach, but I think that is important to convey some sense of possibility,
and work to be done in the GUI, instead of a fully polished "product" or a GUI that hides what is not ready.
This conviction comes from the workshops where we worked and evolved Grafoscopio,
while the workshop was happening(!),
thanks to the dynamic, moldable and continuous nature of the Pharo live coding environment.
Blurring the distinction between interactive documents authors and software developers, means to put
the whole environment at their dispossal, and to show the community that they can be part of this
future possibilities, and that's why we take this unusual approach to GUI.
Where the GUI is more a remainder for the future, I will point that using the **TBD** remark (for To Be Done).
## Place in the ecosystem
### Similar tools
Grafoscopio is similar to other tools and has been inspired by many
of them, while is trying to bring also new possibilities, by combining
different ideas, diverging from others, puting "parallel" ideas into
dialog and, hopefully, bringing new ones.
Here we talk about the similarities and differences with other tools.
- Like [jupyter][jupyter], or [zeppling][zeppling], [beaker][beaker] or [nteract][nteract],
Grafoscopio provides interactive notebook functionality, but it is focused only on
Pharo code right now, instead of being a "language neutral" notebook
(but this could be a feature for the future).
Grafoscopio is a multiplatform (Mac, Windows, Gnu/Linux) desktop application (like nteract, or electron beaker),
instead of a web one (like jupyter, zepelling or beaker), providing a simple, extensible, powerful, self-contained
and portable environment for interactive computing, (as said it can run from a USB thumb drive, modest computers
and anything in between and beyond).
- Grafoscopio organices documents in a tree like metaphor that is interactive
and programmable, like [Org Mode][org-mode], [Leo Editor][leo], [TeXmacs][texmacs] or [Pollen][pollen]
and share with them the idea that the "document is the program"[^book-program] (or a programable container
of small chunks of programs and scripts).
Also, the document author, can define custom tags that can be used to traverse the document tree
and produce multiple particular views from a single document.
- Like [Jupyter Lab][jupyterlab], Grafoscopio environment supports needs beyond the notebook.
Grafoscopio achieves this by leveraging the advantange of the extensible Pharo computing environment
and ecosystem, where it inhabits, with powerful tools for GUI, data processing and visualization, testing,
code repositories, among others.
- Grafoscopio uses the [Roassal agile visualization engine][roassal], to build interactive visualizations and
export them to the web.
Roassal provides similar functionality to other visualization engines and toolkits like [d3.js][d3js],
[RaphaelJS][raphaeljs], [Processing][processing] or [Flare][flare], but, by being part of the Pharo live coding
environment, it invites to a more explorative and dynamic building of visualizations in an agile way.
- At the moment, notebook sharing and collaboration and print (PDF) and web (HTML) publishing are supported,
but in the future we hope to provide advanced interactive notebook publishing features in a distributed p2p fashion
(see next section for the techologies that enable this).
[jupyter]: http://jupyter.org/
[jupyterlab]: http://jupyterlab.github.io/jupyterlab/
[zeppling]: http://zeppelin-project.org/
[beaker]: http://beakernotebook.com/
[nteract]: https://nteract.io/
[org-mode]: http://orgmode.org/
[leo]: http://leoeditor.com
[texmacs]: http://texmacs.org/
[pollen]: http://docs.racket-lang.org/pollen/
[roassal]: http://agilevisualization.com/
[d3js]: https://d3js.org/
[raphaeljs]: https://dmitrybaranovskiy.github.io/raphael/
[processing]: https://processing.org/
[flare]: http://flare.prefuse.org/
[^book-program]:
The idea of the "document is a program" is a paraphrasis of "the book is a program",
stated in the Pollen documentation, which is a short phrase to express a powerful idea
in several programs, like TeXmacs, Org Mode, Leo and, of course, Grafoscopio.
### Technologies behind
Grafoscopio tries to become a simple, understandable, moldable,
versatile and flexible tool thanks to the power of [Pharo][pharo]
environment and ecosystem and the combination with mature external
and internal frameworks and tools. It uses:
- Internal
- [GT Tools][gt-tools] and Spec for embeddable Moose playgrounds, GUI and interactive nodes.
- [Roassal][roassal] for data visualization.
- [STON][ston] for a light data storage and a human friendly notebooks format.
- [NeoJSON][neojson] for interacting with structured hierarchical [JSON][json] data.
- [Citezen][citezen]: for reading and exporting bibliographies to the [BibTeX][bibtex] format.
- [Fuel][fuel]: For medium data storage and objects serialization.
- External:
- [Fossil SCM][fossil] for collaboration and traceability of the documents history (including this very manual).
- [Pandoc][pandoc] for exporting to printing (PDF) and web (HTML) formats.
- [SQLite][sqlite] for storage and management of tabular data.
Despite of trying to provide a friendly, cohesive and empowering user experience (UX) by
integrating default external minimalist and/or self-contained tools into the data exploration
and document publishing workflow, other external tools could be integrated ([Git][git],
more data bases, including [NoSQL][nosql], other exporters and
[light markup languages][light-markup-languages] and so on).
[gt-tools]: http://gt.moosetechnology.org/
[ston]: https://github.com/svenvc/ston/blob/master/ston-paper.md
[fuel]: http://rmod.inria.fr/web/software/Fuel
[fossil]: http://fossil-scm.org/
[pandoc]: http://pandoc.org/
[sqlite]: http://sqlite.org/
[pharo]: http://pharo.org/
[neojson]: https://ci.inria.fr/pharo-contribution/job/EnterprisePharoBook/lastSuccessfulBuild/artifact/book-result/NeoJSON/NeoJSON.html
[json]: http://en.wikipedia.org/wiki/JavaScript_Object_Notation
[citezen]: http://people.untyped.org/damien.pollet/software/citezen/
[bibtex]: https://en.wikipedia.org/wiki/BibTeX
[nosql]: https://en.wikipedia.org/wiki/NoSQL
[git]: https://en.wikipedia.org/wiki/Git
[light-markup-languages]: https://en.wikipedia.org/wiki/Light_markup_language
# Installation instructions
If you want to install grafoscopio on Pharo 5, there are two ways of doing:
via the Pharo catalog or via running a script from the playground.
Both suppose that you have already installed Pharo for your platform
(Windows, Gnu/Linux or Mac) from its [download page][pharo-download],
and will be explained below, from the easiest one to the "not so easy".
Different install procedures suit different tastes and needs and bring alternatives,
so, if one doesn't work for you or your need/taste, you can try others, or just
leave it like that, if your chosen method worked.
[pharo-download]: http://pharo.org/download
## Install from the pharo catalog
To install Grafoscopio, from Internet in Pharo 5, follow this steps:
1. Open the spotter (`Shift` + `Enter`) and start to write the first letters of "Grafoscopio".
The spoter will show that it is available in the projects Catalog as shown in the figure \ref{fig:install-screen1}.
{#fig:install-screen1}
2. Click with the mouse or move with the keyboard to select the "Grafoscopio" package showed.
A install question as the following will be shown (see figure ). Select "Yes" to start the installation process.
{#fig:install-screen2 width="50%"}
3. While the installation is running, some progress bars with package names are going to be showed
(see figure \ref{fig:install-screen3}):
{#fig:install-screen3}
4. When the installation ends we will see two indicators (as shown in figure \ref{fig:install-screen4}).
- Messages in the lower left corner telling that installation is complete and documentation is installed.
- A tool bar in the upper side of the Pharo window, called the docking bar.
{#fig:install-screen4}
5. Once we have Grafoscopio installed, we save modifications to our computing environment, by making
click in any clean part of the GUI (not occupied by any window) to deploy the World Menu.
There we choose save, to `Save` the system with the same name, or `Save as` to save it with a new one
(see figure \ref{fig:install-screen5}).
{#fig:install-screen5 width="50%"}
## Install from a script
There are two ways of running scripts in the Pharo environment:
one by importing them from Internet and the other by writing them
manually.
If you want to run a Pharo script from its web address, open the spotter
(`Shift + Enter`) and paste the address and then press `Enter` to open
the interactive playground and finally press the `Do it and go` green play
button or its shorcut (`Ctrl + Shift + g`).
For example, if you want to run the first part of the install script, open the
spotter and paste this address <http://ws.stfx.eu/BMWZPUY38BSF>.
You will see a screenshot similar to figure \ref{fig:install-script-part1},
showing the web address you have pasted and the first lines of the script
below, marked in grey.
{#fig:install-script-part1}
Press `Enter` or select with the mouse the grey area.
You will see the interactive playground with the script loaded.
We will see more details about the playground later.
For the moment press the play button or the shorcut (`Ctrl + Shift + g`).
You will see that the playground has been executed.
An executed playground contains a new column with details of the object
resulting from that execution, as shown in figure \ref{fig:executed-playground}.
{#fig:executed-playground}
Now repeat the procedure, opening the spoter, pasting this url <http://ws.stfx.eu/CZ87ZZ2SXCEM>
and executing the second part of the installation script (showed in figure \ref{fig:install-script-part2}).
{#fig:install-script-part2}
You will see the progress bars and the ending of the installation process,
as described in the steps 4 to 5 of the previous section.
Is usual to run the previous two steps in a single playground, by executing parts of it.
Here we are going to show you how to do it, with the same installation example we
have done so far.
Open a playground (`Ctrl` + `o` + `w`) and write this:
~~~
"Start by loading the configuration of Grafoscopio"
Gofer new
url: 'http://smalltalkhub.com/mc/Pharo/MetaRepoForPharo50/main';
package: 'ConfigurationOfGrafoscopio';
load.
"After that load Grafoscopio"
ConfigurationOfGrafoscopio load.
~~~
Now select with the mouse the script lines until the first load, as shown in figure
and the press the `Ctrl + g` combination. Only the selected part of the script will be
executed (see figure ).
Now select the second part of the script, as shown in figure
# Using Grafoscopio
This section will show you how to use Grafoscopio from the GUI.
## The spotter
One of the first elements of the Pharo GUI that is an excellent companion
for Grafoscopio is the [Spotter][spotter], provided by the GT Toolkit.
It is a quick finder and laucher of system functionality, allowing you to
launch scripts, find functionality, browse objects and classes, among others.
To launch it press `Shift` + `Enter` in Pharo. You will see something like the
figure \ref{fig:spotter}:
{#fig:spotter}
You can learn more about the spotter in the [Pharo MOOC][mooc] [^mooc].
[spotter]: http://gtoolkit.org/#spotter
[mooc]: https://siemenbaader.github.io/PharoMooc-website/
[^mooc]:
MOOC stands for Massive Online Open Courseware.
The Pharo MOOC is excellent and a really good entry point for programmers
wating to learn more about Pharo and Live Coding.
It is also provides good complementary information if you come for other disciplines
and endeavors and want to complement your reproducible research, modelling,
data storytelling and visualization, with solid foundations of the Pharo environment.
## The docking bar
The docking bar is a fixed point in the graphical interface for quick access to certain
functionalities.
Is divided in three menus that are explained below.
### Launch menu
This menu allows the creation of new notebooks and the opening of recent ones.
Also it allows to launch playgrounds for writing code snippets and trascripts to
see logs of the system.
Here is an screenshot of this menu options and a more detailed explanation of the
options:
[][]
- "New notebook": Creates a new notebook.
- "Notebook from file...": opens a pre-existing notebook from a local file.
- "Notebook from internet...": opens a notebook from an URL and creates a local copy in the temporal folder.
- "Recent notebooks...": lists the notebooks that have been recently opened and/or saved.
- "Example notebooks...": (**TBD**) Lists a set of example notebooks (may be integrated in the ̀Help ̀ menu).
- "Roassal visualizations Gallery...": Opens a visualization browser grouped by categories. Useful as starting
point and inspirations for some projects.
- "Playground": Opens an interactive coding scripting environment, with single "pages". Playgrounds are also
embedable inside Grafoscopio notebooks.
- "Transcript:" opens an output window to see log of events or see print messages.
### Update menu
This menu updates functionality, documentation and settings for Grafoscopio.
Grafoscopio has a [rolling release][rolling-release] model, similar to the Arch Gnu/Linux distribution and
its derivates, so continuous updates in functionality and documentation, come after the version packaged with the default
installation.
The updates frequency increases with our [Data Week][dataweek] hackathon-workshop, seminars, and other community
events, so is good to go the update menu regularly.
This are the options in the Update menu:
- "Grafoscopio": Updates Grafoscopio to the latest development version from the repository.
- "Documentation": Updates companion documentation, that comes as native notebooks or in exported formats
(PDF now and HTML in the future).
- "Dataviz Package": Updates the Dataviz companion package, which contains Domain Specific Languages and
Visualizations that are introduced as Grafoscopio notebooks.
A companion notebook about this package is available on the Help menu, for more detailed information.
- "Notebooks places": Updates some globally shared references for notebooks, so they can be adapted to personal
preferences. This is useful for workshops, so participants can still store some notebooks in their preferred locations,
while sharing relative routes. Examples of this functionality can be found in the Dataviz package notebooks documentation.
- "All the system": Updates all of the above, except for the "Notebooks places", without going for any individual menu.
### Help menu
The Help menu contains mostly references to interactive notebooks that teach
or exemplify how to use Grafoscopio or the core technologies behind (Pharo tutorial,
Roassal, STON, etc).
They are installed with Grafoscopio in native format and some are in PDF.
We have followed a local first approach for the Grafoscopio development, which means that most of
the documentation is writen for the local context first and in Spanish.
The Grafoscopio Manual is the first English "formal" document (besides blog post and constant communication
with the international Pharo communities).
Because the GUI is in English now (it was in Spanish at the begining), we indicate when a Help document is
in Spanish.
In the future we would like to have multilingual documentation, with a bigger team and community to
work on this issues. And of course you're already invited to be part of it.
This are the options in the Help menu:
- "Tutorial (Spanish)": Opens a tutorial used for the [Data Week][dataweek] hackathon/workshop, that
advances in increasding difficulty, covering the Pharo introductory tutorial (Prof. Steph),
some simple scripts, reading of structured data (in JSON), building of a first package (Cinemania),
HTML templating and programatic generation (via Mustache) and basic web publishing (via Teapot).
For a detailed view of the contents, you're welcomed to explore the tutorial by yourself! :-).
- "Manual": Opens this manual.
- "Manual (PDF)": Opens this manual, exported as PDF.
- "About Grafoscopio": Opens the "About" window.
[dataweek]: http://mutabit.com/dataweek/
### Creating a new notebook
Once you have Grafoscopio installed, you will see a docking bar in the
at the top of your Pharo environment.
To create a new notebook you have several options:
- Choose `Launch > New notebook`, from the docking bar.
- Open a Playground (`Ctrl + o + w`) and write `GrafoscopioNotebook new openDefault`.
You will see a window like the shown here:
[][]
Next section will explain the functionality of the GUI showed on this window.
## The notebook GUI
The notebook GUI is composed of tree main parts, as showed below:
- The upper bar
- The document tree
- The node details
Each of these sections will be detailed below.
### The top bar
The top bar groups funtionality to save, export and edit the document tree and associate it to related assets, that
form projects.
This is the detailed information.
#### The notebook menu
Allows the creation new notebooks and their exportation to external formats.
These are the options of this menu:
- "Save": Saves the notebook to the filesystem. If no filename has been provided, asks for one.
- "Save as...": Saves the notebook to the filesyste under a new name.
- "Export as markdown": Exports the current notebook to [pandoc's markdown][markdown].
- Export as html" (**TBD**): Exports the current notebook to HTML format.
- "Export as pdf"
See the "Exporting" section for details about exporting and the pandoc prerrequisites to make it work.
#### The project menu (TBD)
A project is a Grafoscopio notebook with the related files to produce particular outputs
from it, including data files, HTML templates, other notebooks.
A project tracks the historical changes on such files, allows collaboration between collective
authors, exploring or unifying work variations (what is called branching and merging) and let
the profreaders or audience made suggestions (via ticketing).
Projects can be published on the web, providing reproducibility and increasing transparency.
Project functionality is provided in Grafoscopio thanks to the [Fossil SCM][fossil] (SCM stands for
Software Configuration Manager and sometimes is called Distributed Control Version System or DVCS),
a simple and self-contained software for asynchronous collaboration with a pretty small footprint, available
for major platforms.
Fossil is similar to [Git][git] or [GitHub][github], but it is simpler that the former and doesn't hides functionality under
closed source code software, like the later.
Despite of not being integrated yet, several projects have been done using the Grafoscopio + Fossil
combination.
For example, Grafoscopio uses Fossil as backend for its documentation and reporing issues.
[git]: https://en.wikipedia.org/wiki/Git
[github]: https://en.wikipedia.org/wiki/GitHub
#### The toolbar
The toolbar provides a series of icons to access frequently used functionality,
organized by groups.
In the future this functionality will be accessible also via keyboard shorcuts.
Here is a more detailed explanation of the icons functinoality in the toolbar.
##### Notebook saving and node cut, copy & paste
- [][./Images/icon-save.png]: Saves the current notebook.
- [][./Images/icon-cut.png]: Cuts the current node of the document tree.
- [][./Images/icon-copy.png]: Copies the current node of the document tree to the clipboard.
- [][./Images/icon-paste.png]: Pastes the current node of the document tree from the clipboard.
##### Node addition, deletion and movement
- [][./Images/icon-add.png]: Adds a new node to the tree after the currently selected one.
- [][./Images/icon-delete.png]: Removes the currently selected node.
- [][./Images/icon-up.png]: Moves the currently selected node one place upward, unless is the first node.
- [][./Images/icon-down.png]: Moves the currently selected node one place downward, unless is the last node.
- [][./Images/icon-up.png]: Promotes the currently selected node one place, to the same level of its parent.
- [][./Images/icon-up.png]: Demotes the currently selected node one place, making it child of the previous slibing.
##### Switching node body, visiting links and adding tags
There are two kinds of nodes in Grafoscopio now: text nodes and code nodes.
This could change in the future, providing special nodes as particular handers and viewers
of particular content (images, audio, video, and so on).
But with the simple combination of this two kinds of nodes, complete and complex interactive
documents can be created already, and complemented with the dynamic and inmersive Pharo ecosystem.
Text nodes are writen in pandoc's markdown, with support to embedding images, bibliographic
references and all the features provided by this markup language.
Code nodes are interactive playgrounds of Pharo code, allowing to dive into different objects,
and integrated with the Roassal agile visualization toolkit.
Literate computing, weaves code and text, emphasizing narrative and storytelling supported by data.
That's why default nodes are textual ones.
The [][] icon switches a node from text to code and viceversa.
The arrow icon [][] visits a node link, opening it in the web browser, if it is not empty
(see node details for more information about node links).
The add/remove tags icons [][] [][] will be used to define custom tags to mark nodes (**TBD**).
Custom tags can be used to define node traversal paths to create different outputs from a single notebook.
### The document tree
The document tree is the place where the whole document is shown
and provides a uniform metaphor to organize the work.
It is at the left of the Grafosocopio Notebook GUI.
This part will introduce the document tree and some vocabulary to be used with it.
The tree metaphor provides sequence and hierarchy to the document
and its parts and is composed by nodes.
Nodes have tree kinds of possible basic relationships: parent, child and sibling,
which are represented visually for the indentation level of the nodes.
We'll use this visual metaphor to introduce this relationships.
The nodes indented inmediately at the right of other are called the children of the
node at the left, and, converserly, the node at the left is said to be the parent of the
nodes at the right.
Nodes at the same indentation level are siblings, sharing the same parent.
If a node has children, it will show an arrow head at the left.
if the arrow is pointing right, the node is collapsed meaning is not showing
its children.
If the arrow is pointing down, the node is expanded, meaning that is shown them.
(see figure below).
Finally, If a node A is parent of a node B, which is parent of a node C, then A is said to be
an ancestor of C and C is said to be a sucessor of A.
### Node details
As we said, documents are composed by nodes organized in trees.
The node has tree parts: header, body and links.
We will explain the detailed composition of a node below.
#### Node header
The node header is a short text (one line) that summarizes the purpose or content of the node.
The header is shown in two places, in the document tree (for navigation) and at the top of the
node details, as a text field, for edition.
Once the node header has been edited a color mark will be shown near the upper right corner
of the text field box.
This is known as a dirty marker.
To update the header in the document tree press Ctrl + s ( in Windows or Linux) or Cmd + s (Mac).
#### Node body
The node body contains more extense information for the node and can
take several lines of text or code.
Node body is located inmediatly below the node header text input.
Node body is saved automatically with each keystroke, and takes advantage of the
build in persistance for all Pharo objects (called image persistance), but if you want
to update the notebook contents to the file system you will need to save
the notebook explicitely, by pressing the save button in the top bar or chosing the
save option in the ̀Notebook menu ̀.
#### Node links
Node links store links to web references.
Sometimes when you're making quick outlines, you need
to organice external web references and have an easy way to visit them.
That's the primary functionality for node links.
If a node contains a valid link URL in the node links, you can visit them, by
pressing the blue arrow icon [][], which will open the default web browser in
such link.
The node links behave in a similar way to headers and the modificacions are saved
explicitly by pressing Ctrl + s (Gnu/Linux, Windows) or Cmd + s (Mac).
In the future node links will behave in smarter ways, storing, for example, the history
of shared playgrounds for code nodes, paths to the file system to export subtrees of a
document, so, web browsing is just the begining.
### More on code nodes
Code nodes are at the core experience of the interactive documentation,
exploratory computing, reproducible research and literate computing.
Code nodes are full Pharo interactive playgrounds embedded inside the
Grafoscopio nodebook, with full functionality, including interactive inspectors,
to dive into the objects and graphical capabilities, thanks to Roassal.
We use extensively code nodes in our [Data Week][dataweek] workshops,
in conjunction with the integrated Monticello DVCS, to share code in agile
fashion and prototype ideas quickly.
Here is a more detailed view of how to use code nodes.
#### Executing
Once a node has been defined as code (by pressing the [][] button),
you will see a playground page inside the node body, with custom buttons
for its functionality, as seen below:
![][]
To execute a code node, make click on any part of the node body and press the
"Ctrl + shift + g" keyboard combination or click the "play" button in the playground page
(see image below).
![][]
To execute a part of the code node instead, put the cursor at the line you want to
execute or select the line(s) with the mouse and press "Ctrl + g".
#### Sharing
To share a code node, click the "play" button in the playground page
(see image below).
![][]
Once you accept to share your playround contents, a notification popup
will be shown, telling the url of your published playground and will be
automatically copied to the system's clipboard (see image below), so it can
be easily pasted in mails and other messages.
Playground publications hosting services is generously provided by Sven
Van Caekenberghe (also, he is the author of the superb STON format and
NeoJSON importers, used in Grafoscopio and the Dataviz companion package).
#### Importing
The previous topic show you how to share code nodes from the notebook to the web.
This one shows how to import them from the web to your notebooks.
For this, the only thing you need to do is to paste the web URL for published playground
in the node header and press enter.
The node will become a playground with the contents imported from the web.
We use this feature extensively for our workshops/hackathons and in fact was inspired
by them.
Usually we have a set of [etherpads][etherpad] to write quick notes collaboratively in
real time by the event participants and we put there the links of the shared playgrounds,
to be imported in Grafoscopio notebooks.
In the future the node links could show the history of the shared playgrounds and its transformations.
[etherpad]:
#### Diving on them
Code nodes are fully functional playgrounds, as we have said.
So you can use the full functionality of them to dive into the objects.
By executing the plauyground, you not only see the results, but also
a customized inspector (provided by the GT-Tools) that allows to
see the attributes of the object or query them.
Several customized tabs are shown according to the execution
in the playground and can be extended and adapted further.
Some of the most used tabs are:
- "Raw": Shows the attributes of the object resulting from the
playgrounds execution.
Those attributes are also objects, so you can dive into them.
Once you have selected an object, a faceted browsing will start
opening a new set of tabs zooming into this particular object.
The lower panel of the raw view, can be used to send messages to
the main object, or the objects that compose it.
- "Meta": Shows the objects hierarchy starting with the one resulting
from the playgrounds execution and ascending in the containing classes.
Is pretty useful to have a quick overview of which is the vocabulary of the
object, wich messages can be send and how they're organized (protocols)
and implemented.
To know more about playgrounds and how they can be used and extended
vistit the [GT-Tools page][gt-tools].
### Extending the markup: %keywords
### Exporting: markdown, LaTeX and pdf
Grafoscopio provides exportation capabilies to [pandoc's markdown][markdown] and from there,
can be used with [pandoc][pandoc], create beautiful documents for the printing and the web,
with templates and customized control over a lot of variables.
In fact, the PDF version of this document was created in this way, from a single Grafoscopio notebook.
For the moment, Grafoscopio's main author is focused on PDF output,
using [LaTeX][latex] as an intermediate format, because PDF is still the
king format for research and he is finishing writing his dissertation using LaTeX
to create a final PDF document, so the exported markdown is "LaTeX flavored".
In the future, HTML will be supported also and more fine grained markdown export will be available.
[latex]: https://en.wikipedia.org/wiki/LaTeX
To export a document, choose the appropiate option from the [Notebook menu][notebook-menu].
Exporting to markdown will save the document in the same location as the current one, but with ̀.markdown ̀
extension and exporting as PDF will run the proper pandoc command on this document for such conversion
(provided that pandoc is installed on your system at the usual location, if is not, it will send you an error message).
If you want to export a document with a different name, you wil need first to save the native document with such new name.
# API documentation
Because Grafoscopio inhabits a full live coding environment,
it follows the custom of making the API documentation available
inside a dynamic environment, instead in some static web page.
To open the Grafoscopio package inside the system browser,
and see the messages organized by protocols execute:
~~~
"Browser the notebook API"
GrafoscopioNotebook browse.
"Browse the document tree API"
GrafoscopioNode browse.
~~~
# Tests
The core functionality of Grafoscopio is tested.
If you want to see and run the tests, just open the tests package by
executing
~~~
GrafoscopioNodeTest browse
~~~
# Examples
There is a dedicated complementary package, called `Dataviz`, with examples,
that was build with educative purposes, for a recurrent local workshop called
the Data Week, where we invite a diverse community in gender, professions,
educational and life backgrounds.
Also we have a Spanish introductory tutorial, that is directed towards beginers.
To see such examples please load the Dataviz introductory documentation by
executing the code
~~~
"This opens the Spanish tutorial"
GrafoscopioNotebook new openTutorial
~~~
~~~
GrafoscopioDocumentation openDataVizIntro
~~~
# Community Guidelines
## Seek support
Grafoscopio has a small and new born community.
You can reach it by following the contact links
in the Grafoscopio page in
[Spanish](http://mutabit.com/grafoscopio/)
or in [English](http://mutabit.com/grafoscopio/index.en.html).
Also you can discuss issues related with Grafoscopio in the
[Pharo users community](http://pharo.org/community)
mailing list .
We follow such list and try to be active participants there
and bridge the local Spanish community with the international
one.
## Report issues or problems with the software
To report issues of problems please visit our [ticket section][grafoscopio-tickets]
Fossil repository.
Before creating a new ticket, please be sure to visit the
[current tickets][current-tickets], to see if your issue/problem has been
not reported before.
[grafoscopio-tickets]: http://mutabit.com/repos.fossil/grafoscopio/ticket
[current-tickets]: http://mutabit.com/repos.fossil/grafoscopio/rptview?rn=1
## Contribute to the software
As we said, Grafoscopio want to help in blurring the distinction
between software developer and interactive document author,
si we're pretty open to several ways of contributions: from simple
bug reports, as explained above, to the creation of interactive
documentation, domain specific languages (DSL) and visualizations,
or software functionality.
Contributions usually take part on our recurrent Data Week
hackathon/workshop and there you will learn how to use and adapt
the software, starting by the basics, creating DSL and crafting
visualizations and integrating them into interactive notebooks.
You will also learn how to use Fossil and how to commit to our
shared repositories.
We're creating a tutorial (in Spanish) with all these themes covered,
as memories for us and others to remember and learn from.
If you don't have the chance to assist to one of our Data Weeks or
use the resulting notebooks, you can also ask for permisions in
the respository using any of the contact ways, listed above.
We are a small, new born and friendly community with low traffic
mail communication and can discuss about contributions on an
individual case by case approach, so your words, bugfix and suggestions
will be listened and taking into account and integrated when it makes
sense.
Welcome again to our community :-).
# Licenses
## Grafoscopio Software License
The Grafoscopio software is covered under MIT License
Copyright (c) 2014-2016 Offray Vladimir Luna Cárdenas
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
## This Document License
THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS COPYFARLEFT PUBLIC LICENSE (“LICENSE”). THE WORK IS PROTECTED BY COPYRIGHT AND ALL OTHER APPLICABLE LAWS. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED IN THIS LICENSE, YOU AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN AS CONSIDERATION FOR ACCEPTING THE TERMS AND CONDITIONS OF THIS LICENSE AND FOR AGREEING TO BE BOUND BY THE TERMS AND CONDITIONS OF THIS LICENSE.
### Definitions
a. **“Adaptation”** means a work based upon the Work, or upon the Work and other pre-existing works, such as a translation, adaptation, derivative work, arrangement of music or other alterations of a literary or artistic work, or phonogram or performance and includes cinematographic adaptations or any other form in which the Work may be recast, transformed, or adapted including in any form recognizably derived from the original, except that a work that constitutes a Collection will not be considered an Adaptation for the purpose of this License. For the avoidance of doubt, where the Work is a musical work, performance or phonogram, the synchronization of the Work in timed-relation with a moving image (“synching”) will be considered an Adaptation for the purpose of this License.
b. **“Collection”** means a collection of literary or artistic works, such as encyclopedias and anthologies, or performances, phonograms or broadcasts, or other works or subject matter other than works listed in Section 1(f) below, which, by reason of the selection and arrangement of their contents, constitute intellectual creations, in which the Work is included in its entirety in unmodified form along with one or more other contributions, each constituting separate and independent works in themselves, which together are assembled into a collective whole. A work that constitutes a Collection will not be considered an Adaptation (as defined above) for the purposes of this License.
c. **“Distribute”** means to make available to the public the original and copies of the Work or Adaptation, as appropriate, through sale, gift or any other transfer of possession or ownership.
d. **“Licensor”** means the individual, individuals, entity or entities that offer(s) the Work under the terms of this License.
e. **“Original Author”** means, in the case of a literary or artistic work, the individual, individuals, entity or entities who created the Work or if no individual or entity can be identified, the publisher; and in addition (i) in the case of a performance the actors, singers, musicians, dancers, and other persons who act, sing, deliver, declaim, play in, interpret or otherwise perform literary or artistic works or expressions of folklore; (ii) in the case of a phonogram the producer being the person or legal entity who first fixes the sounds of a performance or other sounds; and, (iii) in the case of broadcasts, the organization that transmits the broadcast.
f. **“Work”** means the literary and/or artistic work offered under the terms of this License including without limitation any production in the literary, scientific and artistic domain, whatever may be the mode or form of its expression including digital form, such as a book, pamphlet and other writing; a lecture, address, sermon or other work of the same nature; a dramatic or dramatico-musical work; a choreographic work or entertainment in dumb show; a musical composition with or without words; a cinematographic work to which are assimilated works expressed by a process analogous to cinematography; a work of drawing, painting, architecture, sculpture, engraving or lithography; a photographic work to which are assimilated works expressed by a process analogous to photography; a work of applied art; an illustration, map, plan, sketch or three-dimensional work relative to geography, topography, architecture or science; a performance; a broadcast; a phonogram; a compilation of data to the extent it is protected as a copyrightable work; or a work performed by a variety or circus performer to the extent it is not otherwise considered a literary or artistic work.
g. **“You”** means an individual or entity exercising rights under this License who has not previously violated the terms of this License with respect to the Work, or who has received express permission from the Licensor to exercise rights under this License despite a previous violation.
h. **“Publicly Perform”** means to perform public recitations of the Work and to communicate to the public those public recitations, by any means or process, including by wire or wireless means or public digital performances; to make available to the public Works in such a way that members of the public may access these Works from a place and at a place individually chosen by them; to perform the Work to the public by any means or process and the communication to the public of the performances of the Work, including by public digital performance; to broadcast and rebroadcast the Work by any means including signs, sounds or images.
i. **“Reproduce”** means to make copies of the Work by any means including without limitation by sound or visual recordings and the right of fixation and reproducing fixations of the Work, including storage of a protected performance or phonogram in digital form or other electronic medium.
### Fair dealing rights
Nothing in this License is intended to reduce, limit, or restrict any uses free from copyright or rights arising from limitations or exceptions that are provided for in connection with the copyright protection under copyright law or other applicable laws.
### License Grant
Subject to the terms and conditions of this License, Licensor hereby grants You a worldwide, royalty-free, non-exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as stated below:
a. to Reproduce the Work, to incorporate the Work into one or more Collections, and to Reproduce the Work as incorporated in the Collections;
b. to create and Reproduce Adaptations provided that any such Adaptation, including any translation in any medium, takes reasonable steps to clearly label, demarcate or otherwise identify that changes were made to the original Work. For example, a translation could be marked “The original work was translated from English to Spanish,” or a modification could indicate “The original work has been modified.”;
c. to Distribute and Publicly Perform the Work including as incorporated in Collections; and,
d. to Distribute and Publicly Perform Adaptations. The above rights may be exercised in all media and formats whether now known or hereafter devised. The above rights include the right to make such modifications as are technically necessary to exercise the rights in other media and formats. Subject to Section 8(f), all rights not expressly granted by Licensor are hereby reserved, including but not limited to the rights set forth in Section 4(f).
### Restrictions
The license granted in Section 3 above is expressly made subject to and limited by the following restrictions:
a. You may Distribute or Publicly Perform the Work only under the terms of this License. You must include a copy of, or the Uniform Resource Identifier (URI) for, this License with every copy of the Work You Distribute or Publicly Perform. You may not offer or impose any terms on the Work that restrict the terms of this License or the ability of the recipient of the Work to exercise the rights granted to that recipient under the terms of the License. You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties with every copy of the Work You Distribute or Publicly Perform. When You Distribute or Publicly Perform the Work, You may not impose any effective technological measures on the Work that restrict the ability of a recipient of the Work from You to exercise the rights granted to that recipient under the terms of the License. This Section 4(a) applies to the Work as incorporated in a Collection, but this does not require the Collection apart from the Work itself to be made subject to the terms of this License. If You create a Collection, upon notice from any Licensor You must, to the extent practicable, remove from the Collection any credit as required by Section 4(d), as requested. If You create an Adaptation, upon notice from any Licensor You must, to the extent practicable, remove from the Adaptation any credit as required by Section 4(d), as requested.
b. Subject to the exception in Section 4(c), you may not exercise any of the rights granted to You in Section 3 above in any manner that is primarily intended for or directed toward commercial advantage or private monetary compensation. The exchange of the Work for other copyrighted works by means of digital file-sharing or otherwise shall not be considered to be intended for or directed toward commercial advantage or private monetary compensation, provided there is no payment of any monetary compensation in connection with the exchange of copyrighted works.
c. **You may exercise the rights granted in Section 3 for commercial purposes only if**:
i. **You are a worker-owned business or worker-owned collective; and**
ii. **all financial gain, surplus, profits and benefits produced by the business or collective are distributed among the worker-owners**
d. Any use by a business that is privately owned and managed, and that seeks to generate profit from the labor of employees paid by salary or other wages, is not permitted under this license.
e. If You Distribute, or Publicly Perform the Work or any Adaptations or Collections, You must, unless a request has been made pursuant to Section 4(a), keep intact all copyright notices for the Work and provide, reasonable to the medium or means You are utilizing: (i) the name of the Original Author (or pseudonym, if applicable) if supplied, and/or if the Original Author and/or Licensor designate another party or parties (e.g., a sponsor institute, publishing entity, journal) for attribution (“Attribution Parties”) in Licensor’s copyright notice, terms of service or by other reasonable means, the name of such party or parties; (ii) the title of the Work if supplied; (iii) to the extent reasonably practicable, the URI, if any, that Licensor specifies to be associated with the Work, unless such URI does not refer to the copyright notice or licensing information for the Work; and, (iv) consistent with Section 3(b), in the case of an Adaptation, a credit identifying the use of the Work in the Adaptation (e.g., “French translation of the Work by Original Author,” or “Screenplay based on original Work by Original Author”). The credit required by this Section 4(d) may be implemented in any reasonable manner; provided, however, that in the case of a Adaptation or Collection, at a minimum such credit will appear, if a credit for all contributing authors of the Adaptation or Collection appears, then as part of these credits and in a manner at least as prominent as the credits for the other contributing authors. For the avoidance of doubt, You may only use the credit required by this Section for the purpose of attribution in the manner set out above and, by exercising Your rights under this License, You may not implicitly or explicitly assert or imply any connection with, sponsorship or endorsement by the Original Author, Licensor and/or Attribution Parties, as appropriate, of You or Your use of the Work, without the separate, express prior written permission of the Original Author, Licensor and/or Attribution Parties.
f. For the avoidance of doubt:
i. Non-waivable Compulsory License Schemes. In those jurisdictions in which the right to collect royalties through any statutory or compulsory licensing scheme cannot be waived, the Licensor reserves the exclusive right to collect such royalties for any exercise by You of the rights granted under this License;
ii. Waivable Compulsory License Schemes. In those jurisdictions in which the right to collect royalties through any statutory or compulsory licensing scheme can be waived, the Licensor reserves the exclusive right to collect such royalties for any exercise by You of the rights granted under this License if Your exercise of such rights is for a purpose or use which is otherwise than noncommercial as permitted under Section 4(b) and otherwise waives the right to collect royalties through any statutory or compulsory licensing scheme; and,
iii.Voluntary License Schemes. The Licensor reserves the right to collect royalties, whether individually or, in the event that the Licensor is a member of a collecting society that administers voluntary licensing schemes, via that society, from any exercise by You of the rights granted under this License that is for a purpose or use which is otherwise than noncommercial as permitted under Section 4(b).
g. Except as otherwise agreed in writing by the Licensor or as may be otherwise permitted by applicable law, if You Reproduce, Distribute or Publicly Perform the Work either by itself or as part of any Adaptations or Collections, You must not distort, mutilate, modify or take other derogatory action in relation to the Work which would be prejudicial to the Original Author’s honor or reputation. Licensor agrees that in those jurisdictions (e.g. Japan), in which any exercise of the right granted in Section 3(b) of this License (the right to make Adaptations) would be deemed to be a distortion, mutilation, modification or other derogatory action prejudicial to the Original Author’s honor and reputation, the Licensor will waive or not assert, as appropriate, this Section, to the fullest extent permitted by the applicable national law, to enable You to reasonably exercise Your right under Section 3(b) of this License (right to make Adaptations) but not otherwise.
### Representations, Warranties and Disclaimer
UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.
### Limitation on liability
EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
### Termination
a. This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License. Individuals or entities who have received Adaptations or Collections from You under this License, however, will not have their licenses terminated provided such individuals or entities remain in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License.
b. Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the applicable copyright in the Work). Notwithstanding the above, Licensor reserves the right to release the Work under different license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of this License), and this License will continue in full force and effect unless terminated as stated above.
### Miscellaneous
a. Each time You Distribute or Publicly Perform the Work or a Collection, the Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted to You under this License.
b. Each time You Distribute or Publicly Perform an Adaptation, Licensor offers to the recipient a license to the original Work on the same terms and conditions as the license granted to You under this License.
c. If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties to this agreement, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.
d. No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent.
e. This License constitutes the entire agreement between the parties with respect to the Work licensed here. There are no understandings, agreements or representations with respect to the Work not specified here. Licensor shall not be bound by any additional provisions that may appear in any communication from You. This License may not be modified without the mutual written agreement of the Licensor and You.
f. The rights granted under, and the subject matter referenced, in this License were drafted utilizing the terminology of the Berne Convention for the Protection of Literary and Artistic Works (as amended on September 28, 1979), the Rome Convention of 1961, the WIPO Copyright Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 and the Universal Copyright Convention (as revised on July 24, 1971). These rights and subject matter take effect in the relevant jurisdiction in which the License terms are sought to be enforced according to the corresponding provisions of the implementation of those treaty provisions in the applicable national law. If the standard suite of rights granted under applicable copyright law includes additional rights not granted under this License, such additional rights are deemed to be included in the License; this License is not intended to restrict the license of any rights under applicable law.
# Bibliography
bibliography.bib