Think about creating a list of tutorials of increasing complexity

[gassmoeller]

Maybe similar to the deal.II steps.

[ljhwang]

I will make a first draft for discussion. I will need help in implementing the .dot file into the documentation.

[ljhwang]

Attached is a strawman visualization for this project and roughly follows the same principles as the deal.ii project. Green and orange are cookbooks; blue are geophysical setups; yellow benchmarks as defined in the manual. White are needed .prms; files prepended with "f" are .prms in the "future" folder and have not been written up in the manual. Not all benchmarks are in the manual as well.

Hexagons are basic techniques with the arrows suggested of flow and ordering.

aspect.pdf.

[bangerth]

Nice!

[ljhwang]

The .dot file was renamed so this would upload.

aspect_dot.txt

[jdannberg]

@bangerth, I remember you wanted to make a pull request for this? It would be great if we could get this done before the CGU tutorial so that people would know where to start from. Let us know if you need help with this.

[bangerth]

Attached here is a version of @ljhwang 's original file except that it has some syntax errors cleaned up and actually compiled (but these are only small modifications -- credit still goes to @ljhwang!):
graph.dot.txt
The file obviously needs to be updated for the current set of cookbooks.

But before I go there, the question to me is rather how exactly we will use this. In deal.II, the tutorial graph is used in an HTML page that allows us to embed links so you can click on a tutorial box and get redirected to the correct page. It also allows for tooltips.

But here we are talking about a graph that's going to be embedded into a PDF file. We can run the graph through dot and get either a png or an svg that we can then embed into the PDF file, but:

• There are no tooltips. So we somehow need to embed the long description of what a cookbook is doing in the text that's shown in the graphic.
• We still need to get the links to work so that clicking (in a PDF reader) on a box links to the correct section.

I don't think this is easily possible by embedding a png or svg into the latex pdf output, not the least because I don't know how latex encodes the links in the pdf file. There is apparently a graphviz latex package out there, but (i) it essentially just takes a piece of input from the .tex file, puts it into a .dot file, and calls dot on it -- so that has to be installed to compile the manual. I think we need a different solution.

Looking around a bit, what we want to do can probably be done using tikz. Examples of graphs are shown here:

• http://www.texample.net/tikz/examples/tag/graphs/
• https://tex.stackexchange.com/questions/57152/how-to-draw-graphs-in-latex
• https://stackoverflow.com/questions/2985507/how-to-draw-a-graph-in-latex

For example, here is a little (poorly laid out graph) in latex that contains links:

\documentclass{article}
\usepackage[colorlinks,linkcolor=blue,urlcolor=blue,citecolor=blue,baseurl=../]{hyperref}
\usepackage{tikz}

\begin{document}

\section{Section 1}
\label{sec:1}

\begin{tikzpicture}
  [->,
    scale=1.5,auto=left,
    basic/.style={circle,
      top color = white,
      bottom color = blue!20,
      draw,
      blue,
      text=blue,
      minimum width =1 cm},
    cookbook/.style={rectangle,
      top color = white,
      bottom color = blue!20,
      draw,
      blue,
      text=blue,
      minimum width =1 cm}]
  
  \node[basic] (n6) at (1,10) {Cookbook $6/\pi$};
  \node[cookbook] (n4) at (4,8)  {Link to Section~\ref{sec:2}};
  \node[basic] (n5) at (8,9)  {Cookbook $5/\pi$};
  \node[basic] (n1) at (11,8) {Cookbook $1/\pi$};

  \path (n6) edge node{} (n4);
  \path (n6) edge (n5);
  \path (n6) edge (n1);
  \path (n1) edge (n4);
  
\end{tikzpicture}

\section{Section 2}
\label{sec:2}

\end{document}

I don't think it would be very difficult to convert @ljhwang's dot input to this form. The bigger question is how to relate the information about a cookbook into a box. Maybe just take the section heading instead of an abbreviation?

[bangerth]

Here is an example of the thing I have in mind:

\documentclass{article}
\usepackage[colorlinks,linkcolor=blue,urlcolor=blue,citecolor=blue,baseurl=../]{hyperref}
\usepackage{tikz}

\begin{document}

\section{Section 1}
\label{sec:1}

\begin{tikzpicture}
  [->,
    scale=1.5,auto=left,
    basic/.style={circle,
      top color = white,
      bottom color = blue!20,
      draw,
      blue,
      text=blue,
      minimum width =1 cm},
    cookbook/.style={rectangle,
      top color = white,
      bottom color = blue!20,
      draw,
      blue,
      text=blue,
      minimum width =1 cm}]
  
  \node[cookbook]  (2dBox)                            {Convection in a 2D Box};
  \node[cookbook]  (2dAnnulus) [below left of=2dBox]  {\begin{minipage}{2cm}Simple convection in a quarter of a 2d annulus\end{minipage}};
  \node[cookbook]  (MD04)      [below right of=2dBox] {\begin{minipage}{2cm}Reproducing rheology of Morency and Doin, 2004\end{minipage}};
  \node[cookbook]  (vanKeken)  [below of=MD04]        {\begin{minipage}{2cm}The van Keken thermochemical composition benchmark\end{minipage}};
  \node[cookbook]  (SolCx)     [below right of=vanKeken] {The SolCx Stokes benchmark};
  \node[cookbook]  (SolKz)     [below left of=vanKeken] {The SolKz Stokes benchmark};

  \path (2dBox) edge (2dAnnulus);
  \path (2dBox) edge (MD04);
  \path (MD04) edge (vanKeken);
  \path (vanKeken) edge (SolCx);
  \path (vanKeken) edge (SolKz);
  
\end{tikzpicture}

\end{document}

The problem is that the layout is seriously terrible:
x.pdf
I think I can come up with a way to make individual boxes look nice in a way that shows both the section heading and the section number (linked to) with some minipage and macro tricks without too much hassle. I don't quite know what to make of the layout question -- this will require more work.

For now, what do people think about the general direction?

[tjhei]

For now, what do people think about the general direction?

I think we should discuss at the hackathon. But a couple of comments:

1. Having to manually layout the boxes or having to write an algorithm that does it sounds like a bad idea.
2. We have been debating pdf manual vs html manual vs doxygen and I think we need to come up with a solution (and what goes where) first. If we decide to improve doxygen and promote it more, maybe having the plugin graph interactive within doxygen only is an okay solution (and would be easy...).

[tjhei]

graphviz should be able to have links: https://graphviz.gitlab.io/_pages/doc/info/output.html#d:ps2

[tjhei]

here is a working example using dot2tex and a tikz figure. Only tooltips don't work...

https://www.dropbox.com/s/dfjyzdhtfgcqptx/test.pdf?dl=0