manual-tikz-graffoo.tex

\documentclass[11pt,a4paper,final,oneside,onecolumn]{article}

\usepackage[english]{babel}
%\usepackage[utf8]{inputenc}
%\usepackage[T1]{fontenc}
%\usepackage{amsmath}
%\usepackage{amsfonts}
%\usepackage{amssymb}
\usepackage{graphicx}
\usepackage{url}
\usepackage{xcolor}
\usepackage[colorlinks]{hyperref}
\usepackage{mwe}
\usepackage{caption}
\usepackage{subcaption}
\usepackage{tikz-graffoo}

\author{Eugeniu Costetchi}
\title{Graffoo TikZ library}
\date{06/05/2020}

\begin{document}
	\maketitle
	
	\tableofcontents
	
	\begin{abstract}
		TikZ-Graffoo is a TikZ extension to draw Graffoo diagrams. Graffoo is a tool for drawing OWL ontologies using a simple and well defined visual notation. This library implements the Graffoo visual notation. 
	\end{abstract}
	
	\section{Introduction}
	
	Graffoo, a Graphical Framework for OWL Ontologies\footnote{\url{https://essepuntato.it/graffoo/}}, is an open source tool that can be used to present the classes, properties and restrictions within OWL ontologies, or sub-sections of them, as clear and easy-to-understand diagrams.
	
	This library implements the Graffoo graphical notation\footnote{\url{https://essepuntato.it/graffoo/specification/}} as a set of TikZ styles and macros for increased usability. You can use it to draw OWL ontology fragments or RDF graphs in general. The basic components of Graffoo allow one to create classes, datatypes, annotation, data and object properties, individuals and ontologies.
	
	\section{Usage}
	Once you have downloaded and installed the \texttt{tikz-graffoo} package, using it is a piece of cake:
	
	\verb|\usepackage{tikz-graffoo}|
	
	Drawing Graffoo diagrams in TikZ can be done either (a) by using the node and path styles or (b) by using the macros provided by this package. The latter is recommended for ease and clarity, but the former may be chosen to gain higher control. 
	
	
	\subsection{Macros}
	
	The macros for drawing the basic Graffoo components are as follows. An example for each of these elements is depicted in Figure\ref{fig:macros-elements}.
	
	\begin{itemize}
		\item \textbf{generic entity}\\ \verb|\gEntity{TikZ parameters}{Id}{Content text}|
		
		\item \textbf{class}\\ \verb|\gClass{TikZ parameters}{Id}{Content text}|	
		
		\item \textbf{class restriction}\\ \verb|\gGlassRestriction{TikZ parameters}{Id}{Content text}|
		
		\item \textbf{datatype}\\ \verb|\gDatatype{TikZ parameters}{Id}{Content text}|
		\item \textbf{datatype restriction}\\ \verb|\gDatatypeRestriction{TikZ parameters}{Id}{Content text}|
		
		\item \textbf{instance}\\ \verb|\gInstance{TikZ parameters}{position}{Id}{Content text}| \\ The position parameter indicates where to situate the circle: \texttt{below}, \texttt{above}, \texttt{left} or \texttt{right} of the text.
		
		\item \textbf{literal value}\\ \verb|\gLiteral{TikZ parameters}{Id}{Content text}|
		
		\item \textbf{additional axioms}\\ \verb|\gAxiom{TikZ parameters}{Id}{Content text}|
		
		\item \textbf{prefix definitions}\\ \verb|\gPrefixes{TikZ parameters}{Id}{Content text}|
	\end{itemize}
	
	\begin{figure}[!ht]
		\centering
		\begin{tikzpicture}
		\gClass{}{class}{a class};
		
		\gGlassRestriction{right=3em of class}{class-restriction}{a class restriction};
		
		\gDatatype{right=3em of class-restriction}{datatype}{a datatype};
		
		\gDatatypeRestriction{below=2em of datatype}{datatype-restriction}{a datatype restriction};
		
		\gLiteral{below=2em of class}{literal}{\valueLang[en]{value}};
		
		\gInstance{below=2em of class-restriction}{left}{instance1}{an instance\\of a class};	
		\gPrefixes{below=6em of class-restriction}{prefixes1}{
			skos: \url{http://www.w3.org/2004/02/skos/core\#}\\
			dct: \url{http://purl.org/dc/terms/} 
		};
		\end{tikzpicture}
		\caption{Drawing main Graffoo elements using macros}
		\label{fig:macros-elements}
	\end{figure}
	
	The \LaTeX code for the Figure \ref{fig:macros-elements} is the following.
	
	%{\footnotesize
	\begin{verbatim}
	\begin{tikzpicture}
	\gClass{}{class}{a class};
	\gGlassRestriction{right=3em of class}
	{class-restriction}{a class restriction};
	
	\gDatatype{right=3em of class-restriction}
	{datatype}{a datatype};
	
	\gDatatypeRestriction{below=2em of datatype}
	{datatype-restriction}{a datatype restriction};
	
	\gLiteral{below=2em of class}
	{literal}{\valueLang[en]{value}};
	
	\gInstance{below=2em of class-restriction}
	{left}{instance1}{an instance\\of a class};	
	
	\gPrefixes{below=6em of class-restriction}
	{prefixes1}{
	skos: \url{http://www.w3.org/2004/02/skos/core\#}\\
	dct: \url{http://purl.org/dc/terms/}};
	\end{tikzpicture}
	\end{verbatim}
	%}
	
	
	The macros for drawing the basic Graffoo connectors are as follows. An example for each of these connectors is depicted in Figure\ref{fig:macros-connectors}.
	
	\begin{itemize}
		\item \textbf{generic predicate}\\ \verb|\gPredicate{subject node}{object node}{predicate}|
		
		\item \textbf{object property}\\ \verb|\gObjectProperty{subject node}{object node}{predicate}|
		
		\item \textbf{datatype property}\\ \verb|\gDataProperty{subject node}{object node}{predicate}|
		
		
		\item \textbf{annotation property}\\ \verb|\gAnnotationProperty{subject node}{object node}{predicate}|
		
		\item \textbf{simple link}\\ \verb|\gLink{subject node}{object node}|
	\end{itemize}
	
	\begin{figure}[!ht]
		\centering
		\begin{tikzpicture}
		\gEntity{below=2em of literal}{s1}{ subject };
		\gEntity{right=12em of s1}{o1}{ object };
		\gPredicate{s1}{o1}{predicate};
		
		\gClass{below=2em of s1}{s2}{ domain };
		\gClass{right=12em of s2}{o2}{ range };
		\gObjectProperty{s2}{o2}{object property};
		
		\gClass{below=2em of s2}{s3}{ domain };
		\gDatatype{right=12em of s3}{o3}{ range };
		\gDataProperty{s3}{o3}{data property};
		
		\gClass{below=2em of s3}{s4}{ domain };
		\gDatatype{right=12em of s4}{o4}{ range };
		\gAnnotationProperty{s4}{o4}{annotation property};
		
		\gEntity{below=2em of s4}{s5}{ entity };
		\gAxiom{right=7em of s5}{o5}{these are some additional axioms\\on two lines, best expressed in Machester Syntax };
		\gLink{s5}{o5};	
		\end{tikzpicture}
		\caption{Drawing main Graffoo connectors using macros}
		\label{fig:macros-connectors}
	\end{figure}
	
	The \LaTeX code for the Figure \ref{fig:macros-connectors} is the following.
	
	%{\footnotesize
	\begin{verbatim}
	\begin{tikzpicture}
	\gEntity{below=2em of literal}{s1}{ subject };
	\gEntity{right=12em of s1}{o1}{ object };
	\gPredicate{s1}{o1}{predicate};
	
	\gClass{below=2em of s1}{s2}{ domain };
	\gClass{right=12em of s2}{o2}{ range };
	\gObjectProperty{s2}{o2}{object property};
	
	\gClass{below=2em of s2}{s3}{ domain };
	\gDatatype{right=12em of s3}{o3}{ range };
	\gDataProperty{s3}{o3}{data property};
	
	\gClass{below=2em of s3}{s4}{ domain };
	\gDatatype{right=12em of s4}{o4}{ range };
	\gAnnotationProperty{s4}{o4}{annotation property};
	
	\gEntity{below=2em of s4}{s5}{ entity };
	\gAxiom{right=7em of s5}{o5}{these are some additional axioms\\
	on two lines, best expressed in Machester Syntax };
	\gLink{s5}{o5};	
	\end{tikzpicture}
	\end{verbatim}
	%}
	
	
	\subsection{Styles}
	
	By using TikZ styles provided by this library, the same effect can be achieved as in the case of employing the macros listed above. The styles corresponding to each Graffoo element that should be applied to TikZ nodes are as follows.
	
	\begin{itemize}
		\item \texttt{entity}
		\item \texttt{class}
		\item \texttt{class-restriction}
		\item \texttt{datatype}
		\item \texttt{datatype-restriction}
		\item \texttt{literal} or \texttt{value} (they are equivalent)
		\item \texttt{instance-r}, \texttt{instance-l}, \texttt{instance-a}, \texttt{instance-r}
		\item \texttt{axiom}
		\item \texttt{pref} (should be applied to a node split into two parts)	
	\end{itemize}
	
	The styles corresponding to each Graffoo property type that should be applied to TikZ paths are as follows.
	
	\begin{itemize}
		\item \texttt{predicate}
		\item \texttt{object-property}
		\item \texttt{data-property}
		\item \texttt{annotation-property}
		\item \texttt{link}	
	\end{itemize}
	
	An example of drawing the diagram content as in Figure \ref{fig:macros-elements} and \ref{fig:macros-connectors} using styles alone (no macros) is provided below. 
	
	\begin{verbatim}
	\begin{tikzpicture}
	\node[class] (class) {a class};
	
	\node[class-restriction, right=2em of class]
	(class-restriction) {a class restriction};
	
	\node[datatype, right=2em of class-restriction]
	(datatype) {a datatype};
	
	\node[datatype-restriction, below=2em of datatype]
	(datatype-restriction) {a datatype restriction};
	
	\node[literal, below=2em of class]
	(literal) { \valueLang[en]{value} };	
	
	\node[instance-l, below=2em of class-restriction]
	(instance1) { an instance\\ of a class};
	
	\node[entity, below=2em of literal]
	(s1) { subject entity };	
	\node[entity, right=12em of s1]
	(o1) { object entity };	
	\draw[predicate] (s1) -- (o1)
	node[midway,fill=white,] {property};
	
	\node[entity, below=2em of s1]
	(s2) { subject entity };
	\node[entity, right=12em of s2]
	(o2) { object entity };
	\draw[object-property] (s2) -- (o2)
	node[midway,fill=white,] {object\\property};
	
	\node[entity, below=2em of s2]
	(s3) { subject entity };
	\node[entity, right=12em of s3]
	(o3) { object entity };
	\draw[data-property] (s3) -- (o3)
	node[midway,fill=white,] {data\\property};
	
	\node[entity, below=2em of s3]
	(s4) { subject entity };
	\node[entity, right=12em of s4]
	(o4) { object entity };
	\draw[annotation-property] (s4) -- (o4)
	node[midway,fill=white,] {annotation\\property};
	
	\node[entity, below=2em of s4]
	(s5) { subject entity };
	\node[entity, right=12em of s5]
	(o5) { object entity };
	\draw[link] (s5) -- (o5);
	
	\node [pref, below=3em of s5.west, anchor=north west]
	(prefix) {\textbf{\sffamily Prefixes:}
	\nodepart{two} 
	skos: \url{http://www.w3.org/2004/02/skos/core#}\\ 
	dct: \url{http://purl.org/dc/terms/}};
	\end{tikzpicture}	
	\end{verbatim}
	
	\subsection{Helpers for literal values}
	
	Writing literal values using the Turtle or Manchester syntax is a little cumbersome. To make it easier we provide three macros. 
	
	\begin{itemize}
		\item \textbf{plain literal value}\\
		\verb|\valuePlain{value}| generates \valuePlain{value}
		\item \textbf{typed literal}\\
		\verb|\valueTyped[datatype]{value}| generates \valueTyped[datatype]{value}\\
		\verb|\valueTyped{value}| generates \valueTyped{value}
		\item \textbf{language tagged literal}\\
		\verb|\valueLang[lang]{value}| generates \valueLang[lang]{value}\\
		\verb|\valueLang{value}| generates \valueLang{value}
	\end{itemize}
	
	\section{License and contributions}
	\texttt{tikz-graffoo} may be distributed and/or modified under the conditions of the LaTeX Project
Public License version 1.3 or later. The Current Maintainer of this work is Eugeniu Costetchi (\url{costezki.eugen@gmail.com}), who welcomes contributions to the
package on \href{https://github.com/costezki/owl4latex}{GitHub}.
	
	The goal of this library is to provide a toolkit to draw quickly and efficiently beautiful OWL diagrams. Building such a library can be challenging for one pair of hands alone. If you have used this library yourself or have seen it used, we would greatly appreciate your opinion and feedback . Please open a Github issue or privately email the Current Maintainer with as much information as you can. 
	
	We also welcome technical feedback and bug reports in the form of GitHub Issues
	and pull requests.
\end{document}