# Technical Documentation: Stellarium/stellarium

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/Stellarium/stellarium)

### Overview (README.md)

# Stellarium
[](https://github.com/Stellarium/stellarium/releases/latest)
[](https://github.com/Stellarium/stellarium/releases/latest)
[](https://github.com/Stellarium/stellarium/releases)
[](https://opencollective.com/stellarium)
[](https://github.com/Stellarium/stellarium/actions/workflows/ci.yml)
[](https://ci.appveyor.com/project/alex-w/stellarium)
[](https://coveralls.io/github/Stellarium/stellarium)
[](https://www.codefactor.io/repository/github/stellarium/stellarium)
[](https://score.getplumber.io/github.com/Stellarium/stellarium)

[](https://doi.org/10.1558/jsa.17822)
[](https://doi.org/10.5281/zenodo.8377210)
[](https://ascl.net/2603.001)

Stellarium is a free open source planetarium for your computer. It shows a realistic sky
in 3D, just like what you see with the naked eye, binoculars or a telescope.

If you are new to Stellarium, go to [www.stellarium.org](https://www.stellarium.org) for loads of additional information.

## Installation Instructions & Quick Start

Please refer to the [User Guide, Getting Started section](https://github.com/Stellarium/stellarium/releases/download/v26.3/stellarium_user_guide-26.3-1.pdf).

## Get & build the code

See instructions to [building Stellarium from source code](BUILDING.md).

## Full References and Credits

See the [full credit file](CREDITS.md).

## Contributing to Stellarium

See the [contributing guideline](CONTRIBUTING.md).

## Contributors

This project exists thanks to all the people who contribute! List of contributors [on Github](https://github.com/Stellarium/stellarium/graphs/contributors) (code contributors) and [on Open Collective page](https://opencollective.com/stellarium#contributors) (financial contributors).

## Our backers & sponsors

Thank you to all [our backers and sponsors](BACKERS.md)!  Become a [backer](https://opencollective.com/stellarium#backer) or [sponsor](https://opencollective.com/stellarium#sponsor).

## Code Signing
Windows packages of this program uses free code signing provided by [SignPath.io](https://signpath.io?utm_source=foundation&utm_medium=github&utm_campaign=stellarium), and a free code signing certificate by the [SignPath Foundation](https://signpath.org?utm_source=foundation&utm_medium=github&utm_campaign=stellarium)

## SAST Tools
[PVS-Studio](https://pvs-studio.com/pvs-studio/?utm_source=website&utm_medium=github&utm_campaign=open_source) - static analyzer for C, C++, C#, and Java code.

---

### Guide README (`guide/README.md`)

# README for Stellarium User Guide

Georg Zotti, December 28, 2017

Stellarium's user guide (SUG) for versions 0.15 and later has been re-assembled from the Stellarium wiki by Alexander Wolf and Georg Zotti and greatly extended into what they thought was a complete and optimal format: hyperlinked PDF, created by PDFLaTeX. LaTeX is intimidating to the uninitiated, but the best system in the world for those who are. By V0.17 it had almost 350 pages and came as 28MB PDF file. 

During moving the project to Github some demand has been expressed for again providing an online version of the manual, i.e., HTML. Other developers discussed even leaving LaTeX, but the guide editors resist moving. We decided to widen our typesetting capabilities further by trying to make the PDF smaller, and to make also an HTML version using `htlatex` or something similar. 

The interesting part is now getting all tools right to create the documents. Of course `make` is applied by using a Makefile. But regarding variants in TeX Systems, our multi-platform universe provides many options.

## Installation of tools
### Windows

The classic TeX environment on Windows is MikTeX, a very complete TeX environment with its own package management system. Install it with the option to download missing packages as required. 

Alternatively, to be inline with the other Systems, consider TeXlive also for Windows (https://www.tug.org/texlive/windows.html). 

Windows is still the most common desktop platform in 2019, like it or not. However, its command shell is an embarrassing relic of the DOS era and a far cry from tools available on the tiniest Linux system. 
The shortcomings of the command line have brought several Options for Linux-affine working:

* GNUWin32 tools
* Cygwin
* MinGW
* Windows Subsystem for Linux (WSL): Ubuntu for Windows 10. Consider installing Version 18.04 LTS.

In addition, the GIT Version Control System brings its own MinGW-based git shell. 

The GNUWin32 project provides many important tools to fill in the gaps. From GnuWin32, we need to install make and uname. We also need to install GhostScript. Make sure the relevant programs are found in PATH. Also install Clink from http://mridgers.github.io/clink.

Cygwin and Ubuntu can bring their own optional TeXLive installations, which may however be a bit outdated. If you have problems with the following setup, consider installing current TeXlive (see below). But if you have already MikTeX installed, you can use it from the MinGW/git, cygwin or Ubuntu bash shell and save the diskspace (up to a few gigabytes) for a TeX Installation. However, while cygwin and MinGW based shells will find executables in the Windows PATH called without the .exe extension, WSL/Ubuntu's shell needs the .exe in the called filenames. 

The Makefile is able to detect all these setups on Windows. You can check with 

```
make diag
```

whether your System is properly identified. Note that it does not check whether the programs are installed! If Ubuntu's TeXlive is not installed, we only *assume* that MiKTeX has been installed and the programs available in PATH.

### Linux

These instructions are based on Ubuntu and TeXlive (https://www.tug.org/texlive/quickinstall.html). Find out and add the changes required for your System.

On Ubuntu 22.04 and later the following should work: 

```
sudo apt-get install texlive-base texlive-bibtex-extra texlive-latex-recommended \
texlive-latex-extra texlive-pictures texlive-fonts-recommended texlive-fonts-extra biber make
```


### macOS

It is assumed that some system similar to TeXlive is available for macOS. See https://www.tug.org/mactex/




## Building the PDF Guide

if you run `make` or `make help`, you will see some instructions. 

With a completely configured system, all that should be required is

```
make SUG
```

* `make SUG` creates guide.pdf (full resolution) and a compressed version, SUG.pdf, which needs only about 33% of the size. 

You will find guide.pdf (full resolution) and the compressed version, SUG.pdf.


## Building the HTML Guide

Because of differences in the toolchains we must clean the stuff created with the PDF version.

```
make clean
make html
make clean
```

* `make html` creates the online version in a subdirectory. 
* `make clean` removes intermediate files. PDF and HTML directory will remain.
* `make distclean` deletes all created files, also the PDF and HTML files.

## htlatex and TeX4ht
The workhorse for HTML creation from TeX-based sources is very flexible, but needs some configuration. I am not familiar yet with it, and it seems there is no good online tutorial for NOOBs. I will add my observations here as the project will continue.


### Aim for the HTML Version

The Stellarium Online Guide currently is a set of HTML pages cut at the chapter level. It could become a classical frameset: a narrow box on the left side with table of contents, and the content area on the right, maybe with a separate area for footnotes. Each chapter should become a page to facilitate fast loading. Colored boxes should be available, largely as they appear in the PDF Version. Hyperlinks to external sites should open a new tab or window, internal links should of course just load the other page.


### State
From what we know already: 

`htlatex` does not create HTML from the TeX files, but it creates a classical DVI file which is then further processed by the HTML creation process `ht4lt`. Therefore it seems useful to make sure a classical dvi file can be created. I added a dvi target for this. 

### Detect the processor

We must discern pdflatex from Latex and htlatex. 

```
\ifpdf
    stuff that is processed by pdflatex only
\else
    stuff for htlatex or latex
\fi
```

To encapsulate htlatex-only and pdflatex-only material, we defined code at the beginning of guide.tex and can now use (together with pdftex's built-in pdfoutput)

```
\ifhtlatex
\documentclass[12pt,fleqn,dvipdfmx]{book} % Default font size and left-justified equations
\else
\ifx\pdfoutput\undefined
  \documentclass[12pt,fleqn,dvipdfmx]{book} % Standard LaTeX
\else
  \documentclass[12pt,fleqn]{book} % runs with PDFLaTeX
\fi
\fi
```



### Updating TeXlive

Ubuntu in Windows 10 Comes with TeXlive2013. Some online fora indicate we should use TeXlive's own package Manager.

```
sudo apt-get install xzdec
tlmgr init-usertree
tlmgr update --self

```



However, now Biber complains with a Version clash about outdated biblatex. Biber and biblatex need to match! See https://sourceforge.net/projects/biblatex-biber/files/biblatex-biber/current/documentation/biber.pdf/download

--> Time to install Texlive 2017 on Ubuntu, so  `apt-get remove texlive-full biber`.

In case you are on Cygwin: Install fontconfig, ghostscript, libXaw7 and ncurses from the Cygwin package Manager, then you can join Ubuntuists in the next step.

I.e., download from http://tug.org/texlive/acquire-netinstall.html and run 

```
tar zxvf install-tl-DATE.tar.gz
cd install-tl-DATE
sudo ./install-tl
```

This brings you into a simple text-based menu System. The full Installation takes about 5GB. Press [I] to start. If you are on a slow line, go to sleep. (And hope your Windows does not decide to reboot for an update as soon as you look away! I really despise this "feature"!)

Then also fix PATHs in `~.profile`:

```
export PATH=/usr/local/texlive/2017/bin/x86_64-linux:$PATH
export MANPATH=/usr/local/texlive/2017/texmf-dist/doc/man:$MANPATH
export INFOPATH=/usr/local/texlive/2017/texmf-dist/doc/info:$INFOPATH
```

To install some new package, e.g. titling, from TUG:

```
tlmgr install titling
```

To update, 

```
(sudo apt-get install xzdec)
tlmgr update --self
tlmgr update --all
```


## Why biblatex&biber, and not the classic bibtex?

biblatex&biber is much more flexible. See 
https://tex.stackexchange.com/questions/25701/bibtex-vs-biber-and-biblatex-vs-natbib/25702
However, both packages need to be updated in sync.

## Finally a guide for beginners!

I hope we can follow https://github.com/michal-h21/helpers4ht/wiki/tex4ht-tutorial

Some more info also at https://www.12000.org/my_notes/faq/LATEX/html_and_latex.htm

OK, we need more tools: tidy can cleanup HTML.

```
sudo apt-get install tidy
```


## Increase Memory of your LaTeX system
Edit /usr/local/texlive/2017/texmf.cnf and add these lines:

```
buf_size=90000000
pool_size=9000000
main_memory=8000000
stack_size = 15000       % simultaneous input sources
```

Then call

```
sudo fmtutil-sys --all
```

## Forbidden things

Very odd: It seems section labels must not contain the name ":config". Or we have far too many labels. This seems to be a problem in the chapters with many tables. I had to reduce the number of valid labels.  Else: stack size exceeded. 

# Help Wanted!

If you have some experience with tex4ht to create a pleasing online version of Stellarium's User Guide, please feel free to contribute your TeXnical wisdom. Discuss with the team what kind of format is most useful. Apparently a frameset is possible but requires some extra work in the configuration. (And it is pretty 90ies-ish. But what's wrong with that? Do something better then.) "The LaTeX Web Companion" will be your best friend, it is surprising how little in-depth information is available online.

Some info is in 

* https://tex.stackexchange.com/questions/317686/trouble-building-a-site-with-frames-using-tex4ht and also 
* http://cvr.cc/?p=504.

---

### Doc CMakeLists (`doc/CMakeLists.txt`)

# to generate manual page:
# pod2man --section=1 -r ${VERSION} --center=" " stellarium.pod stellarium.1

IF(UNIX AND NOT WIN32 AND NOT MACOS AND NOT ANDROID)
     ADD_CUSTOM_TARGET(ManPages ALL
          DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/stellarium.1
     )

     CONFIGURE_FILE(
          ${PROJECT_SOURCE_DIR}/cmake/stellarium.pod.cmake
          ${CMAKE_CURRENT_BINARY_DIR}/stellarium.pod
     )

     ADD_CUSTOM_COMMAND(
          OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/stellarium.1 
          COMMAND pod2man
          ARGS -s 1 -r ${VERSION} -center=" " ${CMAKE_CURRENT_BINARY_DIR}/stellarium.pod ${CMAKE_CURRENT_BINARY_DIR}/stellarium.1
     )

     # default directory for manual page
     IF(${CMAKE_SYSTEM_NAME} MATCHES "(DragonFly|NetBSD|OpenBSD)")
          SET(STELLARIUM_MANDIR "man")
     ELSE()
          SET(STELLARIUM_MANDIR "share/man")
     ENDIF()

     IF(CMAKE_INSTALL_MANDIR)
          # use custom directory for manual page
          INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/stellarium.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
     ELSE()
          # use default directory for manual page
          INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/stellarium.1 DESTINATION ${STELLARIUM_MANDIR}/man1)
     ENDIF()
ENDIF()

---

### Guide Images Stellarium Telescope Protocol (`guide/Images/Stellarium_telescope_protocol.txt`)

/*
Author and Copyright of this file and of the stellarium telescope library:
Johannes Gajdosik, 2006
*/

Stellarium Telescope Protocol version 1.0

The Stellarium Telescope Protocol works on top of TCP/IP.
The client is the stellarium program (or any similar program),
the server is called "telescope server" and controls the telescope.
Depending on the implementation the server may handle one or many
simultaneous clients. The reference server implementation accepts
an unlimited number of simultaneous clients.

The protocol is message based: both server and client may
spontaneousely send messages as often as they want.
When the server looses control of the telescope he should
actively close the connection to all clients.

The first two bytes of any message describes the total
length of that message in bytes (including the first 2 bytes).

The next 2 bytes of any message describe the type of this message.

The byte order for all kind of integers is always
"least significiant byte first".

-----------------------
server->client:
MessageCurrentPosition (type = 0):

LENGTH (2 bytes,integer): length of the message
TYPE   (2 bytes,integer): 0
TIME   (8 bytes,integer): current time on the server computer in microseconds
           since 1970.01.01 UT. Currently unused.
RA     (4 bytes,unsigned integer): right ascension of the telescope (J2000)
           a value of 0x100000000 = 0x0 means 24h=0h,
           a value of 0x80000000 means 12h
DEC    (4 bytes,signed integer): declination of the telescope (J2000)
           a value of -0x40000000 means -90degrees,
           a value of 0x0 means 0degrees,
           a value of 0x40000000 means 90degrees
STATUS (4 bytes,signed integer): status of the telescope, currently unused.
           status=0 means ok, status<0 means some error


---------------------

client->server:
MessageGoto (type =0)
LENGTH (2 bytes,integer): length of the message
TYPE   (2 bytes,integer): 0
TIME   (8 bytes,integer): current time on the client computer in microseconds
                  since 1970.01.01 UT. Currently unused.
RA     (4 bytes,unsigned integer): right ascension of the telescope (J2000)
           a value of 0x100000000 = 0x0 means 24h=0h,
           a value of 0x80000000 means 12h
DEC    (4 bytes,signed integer): declination of the telescope (J2000)
           a value of -0x40000000 means -90degrees,
           a value of 0x0 means 0degrees,
           a value of 0x40000000 means 90degrees

---

--- METRICS ---
- Files Extracted: 4
- Estimated Token Budget: ~3946 tokens
- Canonical Reference: https://codewiki.google/github.com/Stellarium/stellarium