Update and rename README.rst to README.md

README.rst → README.md

@@ -1,43 +1,36 @@
-|Kerbalism|
+![KerbalismBanner]
 
-Welcome to Kerbalism
-====================
-Hundreds of Kerbals were killed in the making of this mod.
-----------------------------------------------------------
+## Welcome to Kerbalism
 
-|build|
+#### Hundreds of Kerbals were killed in the making of this mod.
+
+![build]
+
+## INTRODUCTION
 
-INTRODUCTION
-------------
 Go beyond the routine of orbital mechanics and experience the full set of engineering challenges that space has to
 offer. This mod extends KSP by simulating the crew, components, resources and environment in a more complex way.
 All mechanics can be configured to some degree, or even disabled if you don't like some of them. A big part of the
 mod is fully data-driven, so that you can create your own customized game play with only a text editor and a
 minimal amount of espresso. Or simply use the set of rules already included, or the ones shared by other users.
 What follows is a summary description of the capabilities of the mod, and for a more detailed documentation the user
-is invited to read the `Kerbalism documentation`_.
+is invited to read the **[Github wiki]**.
 
-----------
+## ARCHITECTURE
 
-ARCHITECTURE
-------------
 Contrary to popular belief, the observable universe is not a sphere of a 3km radius centered around the active vessel.
 All mechanics are simulated for loaded and unloaded vessels alike, without exception. Acceptable performance was
 obtained by a mix of smart approximations and common sense. The computational complexity is by and large independent
 from the number of vessels.
 
-----------
+## RESOURCES
 
-RESOURCES
----------
 This isn't your classic post-facto resource simulation. Consumption and production work for all vessels, all the time,
 and is coherent irregardless of warp speed or storage capacity. Complex chains of transformations just work. Enjoy
 designing missions without the luxury of stopping the flow of time. No suspension of disbelief required.
 
-----------
+## ENVIRONMENT
 
-ENVIRONMENT
------------
 The environment of space is modeled in a simple yet effective way. Temperature is calculated using the direct solar
 flux, the indirect solar flux bouncing off from celestial bodies, and the radiative infrared cooling of their surfaces.
 The simulation of the latter is especially interesting, and contrary to popular models it is able to reproduce
@@ -46,27 +39,21 @@ hierarchy of 3D zones, modeled and rendered using signed distance fields. These
 belts, magnetosphere and even the heliopause. Solar weather is represented by Coronal Mass Ejection events, that
 happen sporadically, increase radiation and cause communication blackouts.
 
-----------
+## HABITAT
 
-HABITAT
--------
 The habitats of vessels are modeled in terms of internal volume, external surface, and a set of dedicated pseudo
 resources. These elements are then used to calculate such things as: living space per-capita, the pressure, CO2 and humidity
 levels of the internal atmosphere, and radiation shielding. Individual habitats can be enabled or disabled, in the
 editor and in flight, to reconfigure the internal space and everything associated with it during the mission.
 Inflatable habitats are driven directly by the part pressure.
 
-----------
+## BIOLOGICAL NEEDS
 
-BIOLOGICAL NEEDS
-----------------
 Your crew need a constant intake of Food, Water and Oxygen. Failure to provide for these needs will result in
 unceremonious death. Configurable supply containers are provided.
 
-----------
+## PSYCHOLOGICAL NEEDS
 
-PSYCHOLOGICAL NEEDS
--------------------
 The era of tin can interplanetary travel is over. Your crew need some living space, however minimal. Failure to provide
 enough living space will result in unforeseen events in the vessel, the kind that happen when operators lose
 concentration. While not fatal directly, they often lead to fatal consequences later on. Some basic comforts can be
@@ -75,63 +62,49 @@ call back home, or gravity rings to generate artificial gravity. Finally, recent
 pressurized environment is vastly superior to living in a suit. So bring some Nitrogen to compensate for leaks and keep
 the internal atmosphere at an acceptable pressure.
 
-----------
+## ENVIRONMENTAL HAZARDS
 
-ENVIRONMENTAL HAZARDS
----------------------
 Your crew evolved in particular conditions of temperature, and at a very low level of radiation. You should reproduce
 these conditions wherever your crew go, no matter the external temperature or radiation at that point. Or else death
 ensues. The vessel habitat can be climatized at the expense of ElectricCharge. Environment radiation can be shielded by
 applying material layers to the hull, with obvious longevity vs mass trade off.
 
-----------
+## ECLSS
 
-ECLSS
------
 A set of ECLSS components is available for installation in any pod. The scrubber for example, that must be used to keep
 the level of CO2 in the internal atmosphere below a threshold. Or the pressure control system, that can be used to
 maintain a comfortable atmospheric pressure inside the vessel. In general, if you ever heard of some kind of apparatus
 used by space agencies to keep the crew alive, you will find it in this mod.
 
-----------
+## GREENHOUSE
 
-GREENHOUSE
-----------
 No life-support like mod would be complete without a greenhouse of some kind. The one included in this mod has a
 relatively complete set of input resources and by-products, in addition to some more unique characteristics like a lamp
 that adapts consumption to natural lighting, emergency harvesting, pressure requirements and radiation tolerance.
 
-----------
+## ISRU
 
-ISRU
-----
 The stock ISRU converters can host a set of reality-inspired chemical processes. The emerging chains provide a flexible
 and at the same time challenging system to keep your crew alive. The stock ISRU harvesters functionality has been
 replaced with an equivalent one that is easier to plan against, as it is now vital for long-term manned missions. The
 means to harvest from atmospheres and oceans is also present, given the importance of atmospheric resources in this regard.
 A planetary resource distribution that mimics the real solar system completes the package.
 
-----------
+## RELIABILITY
 
-RELIABILITY
------------
 Components don't last forever in the real world. This is modeled by a simple system that can trigger failures on
 arbitrary modules. Manufacturing quality can be chosen in the editor, per-component, and improve the MTBF but also
 requires extra cost and mass. The crew can inspect and repair malfunctioned components. Redundancy now becomes a key aspect
 of the design phase.
 
-----------
+## SIGNAL
 
-SIGNAL
-------
 Transmission rates are realistic, and scale with distance to the point that it may take a long time to transmit data from
 the outer solar system. Data transmission happens transparently in loaded and unloaded vessels. The resulting
 communication system is simple, yet it also results in more realistic vessel and mission designs.
 
-----------
+## SCIENCE
 
-SCIENCE
--------
 Experiments don't return their science output instantly, they require some time to run. Some complete in minutes, others
 will take months. Not to worry, experiments can run on vessels in the background, you don't have to keep that vessel loaded.
 There are two differnt kinds of experiments: sensor readings and samples. Sensor readings are just plain
@@ -142,149 +115,105 @@ transparently to loaded and unloaded vessels alike, and can't be cheated to crea
 method is used to bridge existing stock and third-party experiments to the new science system, that works for most
 experiments without requiring ad-hoc support.
 
-----------
+## AUTOMATION
 
-AUTOMATION
-----------
 Components can be automated using a minimalist scripting system, with a graphical editor. Scripts are triggered
 manually or by environmental conditions. You can create a script to turn on all the lights as soon as the Sun is not
 visible anymore, or retract all solar panels as soon as you enter an atmosphere etc.
 
-----------
+## USER INTERFACE
 
-USER INTERFACE
---------------
 The UI provided by this mod took more than 5 minutes to write. A planner UI is available in the editor, to help the
 user design around all the new mechanics introduced. The planner analysis include resource estimates, habitat
 informations, redundancy analysis, connectivity simulation, multi-environment radiation details and more. To monitor
 the status of vessels, the monitor UI is also provided. This looks like a simple list of vessels at first, but just
 click on it to discover an ingenuous little organizer that allow to watch vessel telemetry, control components, create
 scripts, manage your science data including transmission and analysis, and configure the alerts per-vessel.
 
-----------
+## MODULES EMULATION
 
-MODULES EMULATION
------------------
 Most stock modules and some third-party ones are emulated for what concerns the mechanics introduced by the mod. The
 level of support depends on the specific module, and may include: simulation of resource consumption and production in
 unloaded vessels, fixing of timewarp issues in loaded vessels, the ability to disable the module after malfunctions,
 and also the means to start and stop the module in an automation script.
 
+# Downloads and installation
 
-----------
-
-SUPPORTED MODS
---------------
-Most mods work together with Kerbalism, others don't. Such is life. For a complete list of supported mods have a
-look inside the `Support folder`_. Some of the interactions deserve a special mention though:
-
-**SCANsat:**
-
-- sensors consume EC in the background and their EC cost is evaluated by the planner
-- sensors are shut down and restarted in background depending on EC availability
-
-**RemoteTech:**
-
-- antenna EC cost is evaluated by the planner
-- failures will disable the antenna
-
-**DeepFreeze:**
-
-- all rules are suspended for hibernated Kerbals
-- the vessel info window shows frozen Kerbals with a different color
-
-**NearFuture:**
-
-- curved solar panels, reactors, fission generators and RTGs produce EC in background and are evaluated by the planner
-
-**PlanetaryBaseSystem:**
-
-- the converters will work in the background and are evaluated by the planner
-
-**OrbitalScience:**
-
-- experiments data size has been tweaked for background data transmission
-
-**OPM/RSS/NewHorizons:**
-
-- custom radiation definitions for these planet packs are provided
-
-
-----------
-
-CONTRIBUTIONS
--------------
-This project wouldn't have been possible without the contributions of an awesome community of people, too many to
-mention individually. Thanks guys.
-
-And special thanks to the artists that provided all the parts:
+**Download on [Github releases].** Since version 3.0, two packages are available :
+- **Kerbalism** is the core plugin, always required.
+- **KerbalismConfig** is the default configuration pack.\
+  It can be be replaced by other packs distributed elsewhere.
 
-- mehka: Gravity ring
-- Nazari1382: Geiger counter, small supply container
-- tygoo7: Medium and big supply containers, radial pressurized container
-- zzz: Greenhouse, active shield
+**Requirements**
 
+- Multiple KSP versions are supported, see which ones on the releases page.
+- [Module Manager](https://github.com/sarbian/ModuleManager/releases) : must be installed in GameData
+- [CommunityResourcePack](https://github.com/BobPalmer/CommunityResourcePack/releases) : must be installed in GameData
 
-----------
+**Third-party configuration packs**
 
-FAQs
-----
-There is a help file on GitHub for those wishing to report bugs or contribute to Kerbalism, see `CONTRIBUTING.md <CONTRIBUTING.md>`_
+Make sure to install exactly one configuration pack only.\
+Don't combine packs unless there is explicit instructions to do so.
+- [ROKerbalism](https://github.com/Standecco/ROKerbalism) for Realism Overhaul / RP-1 by standecco
+- [SIMPLEX Living](https://spacedock.info/mod/2067) by theJesuit
 
-**I think I have found a bug, and I have just a few mods installed**
+**Installation checklist** for the "GameData" folder required content : 
 
-- Try to reproduce it consistently, then provide us with reproduction steps that demonstrates the issue. You may be asked to supply log files, screen shots and maybe a save game. Post the report on the `Kerbalism KSP forums thread`_, or raise an issue on `GitHub Kerbalism Issues`_.
+- `CommunityResourcePack` (folder)
+- `Kerbalism` (folder)
+- `KerbalismConfig` (folder, can be replaced by a third-party config pack)
+- `ModuleManager.X.X.X.dll` (file)
 
-**I want to add support for Kerbalism to my parts**
+## Documentation, help and bug-reporting
 
-- Add the appropriate modules to your parts. Check the `Kerbalism documentation`_ for the module specifications.
+- **Tutorials and documentation** are available at the **[Github wiki]**
 
-**I want to interact with Kerbalism in my code**
+- Need **help** ?
 
-- Have a look at the `System/API.cs <src/Kerbalism/System/API.cs>`_ source code on GitHub. Raise an issue to request more functions.
+  Ask on the **[official Discord]** or in the **[KSP forums thread]**
 
-----------
+- You **found a bug** ?
+  - Maybe it's related to another mod ? Check the [Mod Compatibility] page.
+  - Maybe it's a known issue ? Check the [GitHub issues] and ask on the [official Discord].
+  - Try to reproduce it consistently, take screenshots, save your KSP.log file.
 
-INSTALLATION
-------------
+- You want to **report a bug** ?
 
-Required modules:
+  Report it on [Github issues] (preferred) or in the [KSP forums thread] (we don't go there often).\
+  A good bug report contain the expected behavior, what is happening, steps to reproduce, download link to your KSP.log and screenshots.
 
-- Module Manager
-- CommunityResourcePack
-- Kerbalism-Core
-- Kerbalism-Config
+## [Mod compatibility] and support
 
-Kerbalism-Core and Kerbalism-Config can be downloaded here: https://github.com/Kerbalism/Kerbalism/releases
+Kerbalism does custom stuff. In some cases this break compatibility with other mods. For a lot of them, we provide support code and configuration files. However sometimes there is too much feature overlap or support is too complex to implement.
 
-The configuration package is exchangeable. However, if you plan to use a different configuration, download
-that package instead of Kerbalism-Config. Make sure to install exactly one configuration package only, don't
-combine two or more different configurations.
+See the **[mod compatibility]** page for the full support list.
 
-Known configuration packs:
+#### Creating support configs for my part mod
 
-- Realism Overhaul: https://github.com/Standecco/ROKerbalism
+If your part have crew capacity, resource converters, experiments or antennas, you will probably need to tweak some values and replace some PartModules with the Kerbalism ones.
 
-This mod includes version checking using MiniAVC_. If you opt-in, it will use the Internet to check whether there is a new version available. Data is only read from the Internet and no personal information is sent. For a more comprehensive version checking experience, please download the `KSP-AVC Plugin`_.
+Check the technical guide on the [Github wiki], especially the pages on the [profile](https://github.com/Kerbalism/Kerbalism/wiki/TechGuide-~-Profile) and on the [background simulation](https://github.com/Kerbalism/Kerbalism/wiki/TechGuide-~-Background-Simulation).
 
+#### Using the Kerbalism API in my plugin
 
-----------
+Have a look at the [System/API.cs] source code on GitHub. Raise an issue to request more functions.
 
-LICENSE
--------
-This mod is released under the `Unlicense <LICENSE>`_. For more information, please refer to `unlicense.org <http://unlicense.org>`_
+## Disclaimer and license
 
-.. _Support folder: https://github.com/Kerbalism/Kerbalism/tree/master/GameData/Kerbalism/Support
-.. _Kerbalism KSP forums thread: https://forum.kerbalspaceprogram.com/index.php?/topic/172400-131144-kerbalism-v171/
-.. _GitHub Kerbalism Issues: https://github.com/Kerbalism/Kerbalism/issues
-.. _Kerbalism documentation: https://github.com/Kerbalism/Kerbalism/wiki
+This mod is released under the [Unlicense], which mean it's in the public domain.
 
-.. _MiniAVC: https://ksp.cybutek.net/miniavc/Documents/README.htm
-.. _KSP-AVC Plugin: https://forum.kerbalspaceprogram.com/index.php?/topic/72169-13-12-ksp-avc-add-on-version-checker-plugin-1162-miniavc-ksp-avc-online-2016-10-13/
+It includes [MiniAVC]. If you opt-in, it will use the Internet to check whether there is a new version available. Data is only read from the Internet and no personal information is sent. For more control, download the full [KSP-AVC Plugin].
 
-.. |Kerbalism| image:: misc/img/banner.png
+[Github releases]: https://github.com/Kerbalism/Kerbalism/releases
+[Github wiki]: https://github.com/Kerbalism/Kerbalism/wiki
+[GitHub issues]: https://github.com/Kerbalism/Kerbalism/issues
+[Mod Compatibility]: https://github.com/Kerbalism/Kerbalism/wiki/Home-~-Mod-Support
+[System/API.cs]: https://github.com/Kerbalism/Kerbalism/blob/master/src/System/API.cs
+[KSP forums thread]: https://forum.kerbalspaceprogram.com/index.php?/topic/172400-131144-kerbalism-v171/
+[official Discord]: https://discord.gg/3JAE2JE
+[MiniAVC]: https://ksp.cybutek.net/miniavc/Documents/README.htm
+[KSP-AVC Plugin]: https://forum.kerbalspaceprogram.com/index.php?/topic/72169-13-12-ksp-avc-add-on-version-checker-plugin-1162-miniavc-ksp-avc-online-2016-10-13/
+[Unlicense]: https://github.com/Kerbalism/Kerbalism/blob/master/LICENSE
 
-.. |build| image:: https://travis-ci.com/steamp0rt/Kerbalism.svg?style=flat-square&branch=master
-    :alt: Build Status
-    :scale: 100%
-    :target: https://travis-ci\.com/steamp0rt/Kerbalism
+[KerbalismBanner]: https://github.com/Kerbalism/Kerbalism/misc/img/banner.png
+[build]: https://travis-ci.com/steamp0rt/Kerbalism.svg?style=flat-square&branch=master