docs: add manpage to explain terms

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,7 +7,7 @@
 | License        | GNU AGPL-v3
 
 **Checklist:**
-- [ ] I have updated the manpage
+- [ ] I have updated the manpages
 
 <!--
     Replace this notice by a short README for your feature/bugfix.

.github/workflows/e2e.yml

@@ -18,11 +18,17 @@ jobs:
       run: |
         sudo apt install ruby
         sudo gem install ronn
-        pip install -U setuptools pip
-        cd manpage && ronn kosmorro.1.md && cd ..
+        pip install -U setuptools pip requests wheel Babel
 
     - name: E2E tests
       run: |
         export ENVIRONMENT="CI"
         bash .scripts/tests-e2e.sh
 
+    - name: manpage (section 1)
+      run: |
+        man -P $(which cat) kosmorro
+
+    - name: manpage (section 7)
+      run: |
+        man -P $(which cat) 7 kosmorro

.github/workflows/release.yml

@@ -29,8 +29,5 @@ jobs:
         POEDITOR_API_ACCESS: ${{ secrets.POEDITOR_API_ACCESS }}
         POEDITOR_PROJECT_ID: 306433
       run: |
-        cd manpage && ronn kosmorro.1.md && cd ..
-
-        python .scripts/build/getlangs.py
-        python setup.py compile_catalog sdist bdist_wheel
+        make POEDITOR_API_ACCESS="${POEDITOR_API_ACCESS}" POEDITOR_PROJECT_ID="306433" build
         twine upload dist/*

.scripts/tests-e2e.sh

@@ -73,7 +73,7 @@ echo "==== RUNNING E2E TESTS ===="
 echo
 
 # Create the package and install it
-assertSuccess "$PYTHON_BIN setup.py sdist"
+assertSuccess "make build"
 assertSuccess "$PIP_BIN install dist/kosmorro-$VERSION.tar.gz" "CI"
 
 assertSuccess kosmorro

Makefile

@@ -1,3 +1,14 @@
+build:
+	ronn --roff manpage/kosmorro.1.md
+	ronn --roff manpage/kosmorro.7.md
+
+	if [ "$$POEDITOR_API_ACCESS" != "" ]; then \
+		python3 .scripts/build/getlangs.py; \
+		python3 setup.py compile_catalog; \
+	fi
+
+	python3 setup.py sdist bdist_wheel
+
 env:
 	@if [[ "$$RELEASE_NUMBER" == "" ]]; \
 		then echo "Missing environment variable: RELEASE_NUMBER."; \
@@ -27,9 +38,9 @@ finish-release: env
 	git add CHANGELOG.md kosmorrolib/version.py kosmorrolib/locales/messages.pot
 	git commit -m "build: bump version $$RELEASE_NUMBER"
 	git tag "v$$RELEASE_NUMBER"
-    git checkout features
-    git merge master
-    git checkout master
+	git checkout features
+	git merge master
+	git checkout master
 
 	@echo
 	@echo -e "\e[1mVersion \e[36m$$RELEASE_NUMBER\e[39m successfully tagged!"

manpage/README.md

@@ -0,0 +1,34 @@
+# Kosmorro's manpages
+
+This folder contains Kosmorro's manpages.
+
+Two sections are available:
+
+- Section 1: contains the details about the command line usage.
+- Section 7: contains the vocabulary used in Kosmorro along with their definitions.
+
+## How to use it
+
+To open the manpage from section 1, open a terminal and invoke:
+
+```bash
+man kosmorro
+```
+
+If you want to open the vocabulary:
+
+```bash
+man 7 kosmorro
+````
+
+## `man` complains there's "No manual entry for kosmorro"
+
+Sometimes, especially on Mac, `man` needs to be informed about where the manpages are stored by Python 3. Invoke the following command to do this:
+
+```bash
+echo 'export MANPATH=/usr/local/man:$MANPATH' >> $HOME/.bashrc
+```
+
+And open a new terminal.
+
+NB: if you are not using Bash, change `.bashrc` with the correct file.

manpage/kosmorro.7.md

@@ -0,0 +1,63 @@
+# kosmorro(7) -- a program that computes the ephemerides
+
+## DESCRIPTION
+
+This manual explains the different terms that one can find when using **kosmorro**(1).
+The terms are given in an alphabetically order.
+
+## TERMS
+
+### Conjunction
+
+From the point of view of the Earth, two asters are said in conjunction when they are close together.
+It is, of course, an illusion caused by the position of the Earth combined with the two other objects' ones.
+
+### Elongation
+
+The elongation is the angle of visual separation between a planet and the Sun, as seen from the point of view of the Earth.
+For the inferior planets, the time when the elongation is maximal is propice to their observation, because it is the moment when they are the most visible.
+
+### Occultation
+
+An occultation is a special kind of conjunction where the closer aster to the Earth hides, at least partially, another one.
+
+### Opposition
+
+An aster is said in opposition when it is positionned at the exact opposite of the Sun, from the point of view of the Earth, i.e. when their angle is equal to 180 degrees.
+For all the superior planets, it is the best moment to observe them, because they will be at the smallest distance to the Earth. Plus, they will appear full.  
+For instance, Mars is in opposition when the angle Mars-Earth-Sun is equal to 180 degrees.
+
+### Planet
+
+A planet is an aster that orbits around a star, is not a star itself, is massive enough to maintain it nearly round, and has cleaned its orbit from other massive objects.
+
+**Inferior planet**
+
+A planet is said "inferior" if its orbit radius is smaller than the planet of reference.  
+For instance, the inferior planets from the point of view of the Earth are Mercury and Venus.
+
+The term should not be confused with "inner planet".
+
+**Inner planet**
+
+The "inner planet" term refers to the planets orbiting below the orbit of the asteroid belt between Mars and Jupiter.
+
+**Outer planet**
+
+The "outer planet" term refers to the planets orbiting beyond the orbit of the asteroid belt between Mars and Jupiter.
+
+**Superior planet**
+
+A planet is said "superior" if its orbit radius is higher than the planet of reference.  
+For instance, the superior planets from the point of view of the Earth are Mars, Jupiter, Saturn, Uranus and Neptune.
+
+The term should not be confused with "outer planet".
+
+## AUTHOR
+
+Written by Jérôme Deuchnord.
+
+## COPYRIGHT
+
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+

setup.py

@@ -39,7 +39,8 @@ setup(
     scripts=['kosmorro'],
     include_package_data=True,
     data_files=[
-        ('man/man1', ['manpage/kosmorro.1'])
+        ('man/man1', ['manpage/kosmorro.1']),
+        ('man/man7', ['manpage/kosmorro.7'])
     ],
     install_requires=['skyfield>=1.17.0,<2.0.0', 'tabulate', 'numpy>=1.17.0,<2.0.0', 'termcolor', 'python-dateutil'],
     classifiers=[