ch_plugins.tex

\chapter{Plugins: An Introduction}
\label{ch:Plugins}

Starting with version 0.10.3, Stellarium's packages have included a steadily growing number of
optional extensions called plug-ins: Angle Measure, Compass Marks, Oculars, Telescope Control, Text
User Interface, Satellites, Solar System Editor, Historical Novae and
Supernovae, Quasars, Pulsars, Exoplanets, Observability analysis, ArchaeoLines, Scenery3D,
RemoteControl, Navigation Stars and RemoteSync. All
these plug-ins are ``built-in'' in the standard Stellarium distribution
and don't need to be downloaded separately.

%% TODO: Are there still downloadable plugins?

\section{Enabling plugins}
\label{sec:Plugins:EnablingPlugins}

%\begin{figure}[h]
%\centering\includegraphics{sat_howto_01.jpg}
%\end{figure}

To enable a plugin:

\begin{enumerate}
\item Open the \textbf{Configuration dialog} (press \key{F2} or use
  the left tool bar button \guibutton[0.35]{0.1}{btd_config.png})
\item Select the \textbf{Plugins} tab
\item Select the plugin you want to enable from the list
\item Check the \textbf{Load at startup} option
\item Restart Stellarium
\end{enumerate}

\noindent If the plugin has configuration options, the
\textbf{configuration} button will be enabled when the plugin has been
loaded and clicking it will open the plugin's configuration
dialog. When you only just activated loading of a plugin, you must
restart Stellarium to access the plugin's configuration dialog.  The
plugin's configuration dialog \newFeature{0.21.2} is also available by
right-clicking on the respective plugin's main button in the bottom
button bar.

\section{Data for plugins}
\label{sec:Plugins:DataForPlugins}

Some plugins contain files with different data, e.g., catalogs. JSON is a
typical format for those files, and you can edit its contents manually. Of
course, each plugin has a specific format of data for its own catalogs, and
you should read the documentation for the plugin before editing its catalog.

You can read some common instructions for editing catalogs of plugins
below. In this example we use file name \file{catalog.json} for
identification of the catalog for a typical plugin.

You can modify the \file{catalog.json} files manually using a text
editor. \textbf{If you are using Windows, it is strongly recommended to
use an advanced text editor such as
Notepad++\footnote{\url{https://notepad-plus-plus.org/}} to avoid problems with
end-of-line characters.} (It will also color the JSON code and make it
easier to read.)

\textbf{Warning}: Before editing your \file{catalog.json} file, make a
backup copy. Leaving out the smallest detail (such as a comma or
forgetting to close a curly bracket) may prevent Stellarium from
starting.

As stated in section~\ref{sec:FilesAndDirectories}, the path to the
directory\footnote{This is a hidden folder, so in order to find it you
  may need to change your computer's settings to display hidden files
  and folders.} which contains \file{catalog.json} file is something
like:

\begin{description}
\item[Windows]
  C:\textbackslash Users\textbackslash\textbf{UserName}\textbackslash AppData\textbackslash Roaming\textbackslash Stellarium\textbackslash modules\textbackslash \textit{PluginName}
\item[Mac OS X]
  \textbf{HomeDirectory}/Library/Application Support/Stellarium/modules/\textit{PluginName}
\item[Linux and UNIX-like OS]
  \textasciitilde{}/.stellarium/modules/\textit{PluginName}
\end{description}



%%% Local Variables:
%%% mode: latex
%%% TeX-master: "guide"
%%% End: