Menu ▾ ▴

#116 Add SSCCE links to manual

Next Release
open
nobody
None
5
2018-07-03
2018-07-03
Kalle Richter
No

I'm aware that the following is a huge pile of work, however I hope that you devs don't close it immediately because of that. It's intended to make this awesome software easier to use for beginners and trained users which tend to forget or can't keep up with the latest major changes:

It'd be nice to have a link to a Short, Self Contained, Correct (Compilable), Example for every code sample so that if you click on a link to a code sample like

\begin{tikzpicture}
\draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid(1.4,1.4);
\draw (-1.5,0) -- (1.5,0);
\draw (0,-1.5) -- (0,1.5);
\draw (0,0) circle[radius=1cm];
\draw (3mm,0mm) arc[start angle=0,end angle=30,radius=3mm];
\end{tikzpicture}

on page xy you're redirected to the plain text file https://sourceforge.net/p/pgf/wiki/samples/001.tex which contains a SSCCE which can be directly passed to the compiler.

The manual describes what the user needs to do in a satisfying way, starting with

\documentclass{article}% say
\usepackage{tikz}
\begin{document}
We are working on
\begin{tikzpicture}
\draw (-1.5,0) -- (1.5,0);
\draw (0,-1.5) -- (0,1.5);
\end{tikzpicture}.
\end{document}

However, it's sometimes hard to follow all the packages which have been introduced and settings which have been changed over the course of the chapter where the snippet is shown (which can be dozens of pages long). The plain text links would avoid this and reduce the number of mistakes can make while using the snippet almost to zero.

This would also improve the incapacity of most PDF viewers to copy code accurate, i.e. without introducing unwanted linebreaks and replacing spaces with linebreaks, even though that's not PGF's job.

If you think that's a good idea regardless of the effort, then you might want to keep those SSCCEs coming piece by piece, maybe through merge requests. I can provide some, however, I often find myself trying to get the snippets to compile for hours which is the main reason why I'm suggesting this.

The SSCCEs could be provided for LaTeX, TeX, ConTeX and LuaLaTeX.

Discussion