From 8bda2e1286c10720af562dba5084b9c8a8803a8a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Deuchnord?= <jerome@deuchnord.fr>
Date: Wed, 13 May 2020 21:36:20 +0200
Subject: [PATCH] docs: add manpage to explain terms

---
 .github/PULL_REQUEST_TEMPLATE.md |  2 +-
 .github/workflows/e2e.yml        | 10 ++++-
 .github/workflows/release.yml    |  5 +--
 .scripts/tests-e2e.sh            |  2 +-
 Makefile                         | 17 +++++++--
 manpage/README.md                | 34 +++++++++++++++++
 manpage/kosmorro.7.md            | 63 ++++++++++++++++++++++++++++++++
 setup.py                         |  3 +-
 8 files changed, 124 insertions(+), 12 deletions(-)
 create mode 100644 manpage/README.md
 create mode 100644 manpage/kosmorro.7.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 4180741..7e915b9 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.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.
diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
index 9259105..c08708b 100644
--- a/.github/workflows/e2e.yml
+++ b/.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
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index d7bfd02..87e16c0 100644
--- a/.github/workflows/release.yml
+++ b/.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/*
diff --git a/.scripts/tests-e2e.sh b/.scripts/tests-e2e.sh
index 1f9d149..1185670 100755
--- a/.scripts/tests-e2e.sh
+++ b/.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
diff --git a/Makefile b/Makefile
index b5bd283..00398ba 100644
--- a/Makefile
+++ b/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!"
diff --git a/manpage/README.md b/manpage/README.md
new file mode 100644
index 0000000..854abf0
--- /dev/null
+++ b/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.
diff --git a/manpage/kosmorro.7.md b/manpage/kosmorro.7.md
new file mode 100644
index 0000000..20fecef
--- /dev/null
+++ b/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.
+
diff --git a/setup.py b/setup.py
index 4d0f97e..232dd8f 100644
--- a/setup.py
+++ b/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=[