readme: Clean up, fix nearly all markdownlint complaints

README.md

@@ -1,7 +1,7 @@
+# SolveSpace
+
 <img src="res/freedesktop/solvespace-scalable.svg" width="70" height="70" alt="SolveSpace Logo" align="left">
 
-SolveSpace
-==========
 [![Build Status](https://github.com/solvespace/solvespace/workflows/CD/badge.svg)](https://github.com/solvespace/solvespace/actions)
 [![solvespace](https://snapcraft.io/solvespace/badge.svg)](https://snapcraft.io/solvespace)
 [![solvespace](https://snapcraft.io/solvespace/trending.svg?name=0)](https://snapcraft.io/solvespace)
@@ -11,8 +11,7 @@ This repository contains the source code of [SolveSpace][], a parametric
 
 [solvespace]: https://solvespace.com
 
-Community
+## Community
----------
 
 The official SolveSpace [website][sswebsite] has [tutorials][sstutorial],
 [reference manual][ssref] and a [forum][ssforum]; there is also an official
@@ -24,14 +23,13 @@ IRC channel [#solvespace at web.libera.chat][ssirc].
 [ssforum]: http://solvespace.com/forum.pl
 [ssirc]: https://web.libera.chat/#solvespace
 
-Installation
+## Installation
-------------
 
 ### Via official binary packages
 
-_Official_ release binary packages for macOS (>=10.6 64-bit) and Windows (>=Vista 32-bit) are
+_Official_ release binary packages for macOS (>=10.6 64-bit) and Windows
-available via [GitHub releases][rel]. These packages are automatically built by
+(>=Vista 32-bit) are available via [GitHub releases][rel]. These packages are
-the SolveSpace maintainers for each stable release.
+automatically built by the SolveSpace maintainers for each stable release.
 
 [rel]: https://github.com/solvespace/solvespace/releases
 
@@ -39,25 +37,28 @@ the SolveSpace maintainers for each stable release.
 
 Official releases can be installed from the `stable` channel.
 
-Builds from master are automatically released to the `edge` channel in the Snap Store. Those packages contain the latest improvements, but receive less testing than release builds.
+Builds from master are automatically released to the `edge` channel in the Snap
+Store. Those packages contain the latest improvements, but receive less testing
+than release builds.
 
 [![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-black.svg)](https://snapcraft.io/solvespace)
 
 Or install from a terminal:
 
-```
+```sh
 # for the latest stable release:
 snap install solvespace
+
 # for the bleeding edge builds from master:
 snap install solvespace --edge
 ```
 
 ### Via third-party binary packages
 
-_Third-party_ nightly binary packages for Debian and Ubuntu are available
+_Third-party_ nightly binary packages for Debian and Ubuntu are available via
-via [notesalexp.org][notesalexp]. These packages are automatically built from non-released
+[notesalexp.org][notesalexp]. These packages are automatically built from
-source code. The SolveSpace maintainers do not control the contents of these packages
+non-released source code. The SolveSpace maintainers do not control the contents
-and cannot guarantee their functionality.
+of these packages and cannot guarantee their functionality.
 
 [notesalexp]: https://notesalexp.org/packages/en/source/solvespace/
 
@@ -66,123 +67,147 @@ and cannot guarantee their functionality.
 > :warning: **Edge builds might be unstable or contain severe bugs!**
 > They are intended for experienced users to test new features or verify bugfixes.
 
-Cutting edge builds from the latest master commit are available as zip archives from the
+Cutting edge builds from the latest master commit are available as zip archives
-following links:
+from the following links:
 
 - [macOS](https://nightly.link/solvespace/solvespace/workflows/cd/master/macos.zip)
 - [Windows](https://nightly.link/solvespace/solvespace/workflows/cd/master/windows.zip)
 - [Windows with OpenMP enabled](https://nightly.link/solvespace/solvespace/workflows/cd/master/windows-openmp.zip)
 
-Extract the downloaded archive and install or execute the contained file as is appropriate for your platform.
+Extract the downloaded archive and install or execute the contained file as is
+appropriate for your platform.
 
 ### Via source code
 
 See below.
 
-Building on Linux
+## Building on Linux
------------------
 
 ### Building for Linux
 
-You will need the usual build tools, CMake, zlib, libpng, cairo, freetype.
+You will need the usual build tools, CMake, zlib, libpng, cairo, freetype. To
-To build the GUI, you will need fontconfig, gtkmm 3.0 (version 3.16 or later), pangomm 1.4,
+build the GUI, you will need fontconfig, gtkmm 3.0 (version 3.16 or later),
-OpenGL and OpenGL GLU, and optionally, the Space Navigator client library.
+pangomm 1.4, OpenGL and OpenGL GLU, and optionally, the Space Navigator client
-On a Debian derivative (e.g. Ubuntu) these can be installed with:
+library. On a Debian derivative (e.g. Ubuntu) these can be installed with:
 
-    sudo apt install git build-essential cmake zlib1g-dev libpng-dev \
+```sh
+sudo apt install git build-essential cmake zlib1g-dev libpng-dev \
             libcairo2-dev libfreetype6-dev libjson-c-dev \
             libfontconfig1-dev libgtkmm-3.0-dev libpangomm-1.4-dev \
             libgl-dev libglu-dev libspnav-dev
+```
 
-On a Redhat derivative (e.g. Fedora) the dependencies can be installed with:
+On a RedHat derivative (e.g. Fedora) the dependencies can be installed with:
 
-    sudo dnf install git gcc-c++ cmake zlib-devel libpng-devel \
+```sh
+sudo dnf install git gcc-c++ cmake zlib-devel libpng-devel \
             cairo-devel freetype-devel json-c-devel \
             fontconfig-devel gtkmm30-devel pangomm-devel \
             mesa-libGL-devel mesa-libGLU-devel libspnav-devel
+```
 
 Before building, check out the project and the necessary submodules:
 
-    git clone https://github.com/solvespace/solvespace
+```sh
-    cd solvespace
+git clone https://github.com/solvespace/solvespace
-    git submodule update --init extlib/libdxfrw extlib/mimalloc
+cd solvespace
+git submodule update --init extlib/libdxfrw extlib/mimalloc
+```
 
 After that, build SolveSpace as following:
 
-    mkdir build
+```sh
-    cd build
+mkdir build
-    cmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_OPENMP=ON
+cd build
-    make
+cmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_OPENMP=ON
-    sudo make install
+make
 
-Link Time Optimization is supported by adding -DENABLE_LTO=ON to cmake at the
+# Optionally
+sudo make install
+```
+
+Link Time Optimization is supported by adding `-DENABLE_LTO=ON` to cmake at the
 expense of longer build time.
 
-The graphical interface is built as `build/bin/solvespace`, and the command-line interface
+The graphical interface is built as `build/bin/solvespace`, and the command-line
-is built as `build/bin/solvespace-cli`. It is possible to build only the command-line interface by passing the `-DENABLE_GUI=OFF` flag to the cmake invocation.
+interface is built as `build/bin/solvespace-cli`. It is possible to build only
+the command-line interface by passing the `-DENABLE_GUI=OFF` flag to the cmake
+invocation.
 
 ### Building for Windows
 
-Ubuntu will require 20.04 or above. Cross-compiling with WSL is also confirmed to work.
+Ubuntu will require 20.04 or above. Cross-compiling with WSL is also confirmed
+to work.
 
-You will need the usual build tools, CMake, and a Windows cross-compiler. On a Debian derivative (e.g. Ubuntu) these can be installed with:
+You will need the usual build tools, CMake, and a Windows cross-compiler. On a
+Debian derivative (e.g. Ubuntu) these can be installed with:
 
-    apt-get install git build-essential cmake mingw-w64
+```sh
+apt-get install git build-essential cmake mingw-w64
+```
 
 Before building, check out the project and the necessary submodules:
 
-    git clone https://github.com/solvespace/solvespace
+```sh
-    cd solvespace
+git clone https://github.com/solvespace/solvespace
-    git submodule update --init
+cd solvespace
+git submodule update --init
+```
 
 Build 64-bit SolveSpace with the following:
 
-    mkdir build
+```sh
-    cd build
+mkdir build
-    cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchain-mingw64.cmake \
+cd build
+cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchain-mingw64.cmake \
             -DCMAKE_BUILD_TYPE=Release
-    make
+make
+```
 
-The graphical interface is built as `build/bin/solvespace.exe`, and the command-line interface
+The graphical interface is built as `build/bin/solvespace.exe`, and the
-is built as `build/bin/solvespace-cli.exe`.
+command-line interface is built as `build/bin/solvespace-cli.exe`.
 
 Space Navigator support will not be available.
 
-If using Ubuntu to cross-compile, Ubuntu 17.10 or newer (or, alternatively, MinGW from the Ubuntu
+## Building on macOS
-17.10 repositories) is required.
-
-Building on macOS
------------------
 
 You will need git, XCode tools and CMake. Git and CMake can be installed
 via [Homebrew][]:
 
-    brew install git cmake
+```sh
+brew install git cmake
+```
 
 XCode has to be installed via AppStore or [the Apple website][appledeveloper];
 it requires a free Apple ID.
 
 Before building, check out the project and the necessary submodules:
 
-    git clone https://github.com/solvespace/solvespace
+```sh
-    cd solvespace
+git clone https://github.com/solvespace/solvespace
-    git submodule update --init
+cd solvespace
+git submodule update --init
+```
 
 After that, build SolveSpace as following:
 
-    mkdir build
+```sh
-    cd build
+mkdir build
-    cmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_OPENMP=ON
+cd build
-    make
+cmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_OPENMP=ON
+make
+```
 
-Link Time Optimization is supported by adding -DENABLE_LTO=ON to cmake at the
+Link Time Optimization is supported by adding `-DENABLE_LTO=ON` to cmake at the
 expense of longer build time.
 
 Alternatively, generate an XCode project, open it, and build the "Release" scheme:
 
-    mkdir build
+```sh
-    cd build
+mkdir build
-    cmake .. -G Xcode
+cd build
+cmake .. -G Xcode
+```
 
 The application is built in `build/bin/SolveSpace.app`, the graphical interface executable
 is `build/bin/SolveSpace.app/Contents/MacOS/SolveSpace`, and the command-line interface executable
@@ -191,26 +216,32 @@ is `build/bin/SolveSpace.app/Contents/MacOS/solvespace-cli`.
 [homebrew]: https://brew.sh/
 [appledeveloper]: https://developer.apple.com/download/
 
-Building on OpenBSD
+## Building on OpenBSD
--------------------
 
 You will need git, cmake, libexecinfo, libpng, gtk3mm and pangomm.
 These can be installed from the ports tree:
 
-    pkg_add -U git cmake libexecinfo png json-c gtk3mm pangomm
+```sh
+pkg_add -U git cmake libexecinfo png json-c gtk3mm pangomm
+```
 
 Before building, check out the project and the necessary submodules:
 
-    git clone https://github.com/solvespace/solvespace
+```sh
-    cd solvespace
+git clone https://github.com/solvespace/solvespace
-    git submodule update --init extlib/libdxfrw extlib/mimalloc
+cd solvespace
+git submodule update --init extlib/libdxfrw extlib/mimalloc
+```
 
 After that, build SolveSpace as following:
 
-    mkdir build
+```sh
-    cd build
+mkdir build
-    cmake .. -DCMAKE_BUILD_TYPE=Release
+cd build
-    make
+cmake .. -DCMAKE_BUILD_TYPE=Release
+make
+sudo make install
+```
 
 Unfortunately, on OpenBSD, the produced executables are not filesystem location independent
 and must be installed before use. By default, the graphical interface is installed to
@@ -218,8 +249,7 @@ and must be installed before use. By default, the graphical interface is install
 `/usr/local/bin/solvespace-cli`. It is possible to build only the command-line interface
 by passing the `-DENABLE_GUI=OFF` flag to the cmake invocation.
 
-Building on Windows
+## Building on Windows
--------------------
 
 You will need [git][gitwin], [cmake][cmakewin] and a C++ compiler
 (either Visual C++ or MinGW). If using Visual C++, Visual Studio 2015
@@ -234,17 +264,19 @@ Visual C++ and build it.
 
 ### Building with Visual Studio in a command prompt
 
-First, ensure that git and cl (the Visual C++ compiler driver) are in your
+First, ensure that `git` and `cl` (the Visual C++ compiler driver) are in your
 `%PATH%`; the latter is usually done by invoking `vcvarsall.bat` from your
 Visual Studio install. Then, run the following in cmd or PowerShell:
 
-    git clone https://github.com/solvespace/solvespace
+```bat
-    cd solvespace
+git clone https://github.com/solvespace/solvespace
-    git submodule update --init
+cd solvespace
-    mkdir build
+git submodule update --init
-    cd build
+mkdir build
-    cmake .. -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release
+cd build
-    nmake
+cmake .. -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release
+nmake
+```
 
 ### Building with MinGW
 
@@ -254,25 +286,25 @@ Space Navigator support will be disabled.
 First, ensure that git and gcc are in your `$PATH`. Then, run the following
 in bash:
 
-    git clone https://github.com/solvespace/solvespace
+```sh
-    cd solvespace
+git clone https://github.com/solvespace/solvespace
-    git submodule update --init
+cd solvespace
-    mkdir build
+git submodule update --init
-    cd build
+mkdir build
-    cmake .. -DCMAKE_BUILD_TYPE=Release
+cd build
-    make
+cmake .. -DCMAKE_BUILD_TYPE=Release
+make
+```
 
 [gitwin]: https://git-scm.com/download/win
 [cmakewin]: http://www.cmake.org/download/#latest
 [mingw]: http://www.mingw.org/
 
-Contributing
+## Contributing
-------------
 
 See the [guide for contributors](CONTRIBUTING.md) for the best way to file issues, contribute code,
 and debug SolveSpace.
 
-License
+## License
--------
 
 SolveSpace is distributed under the terms of the [GPL v3](COPYING.txt) or later.