Update for current version of MESSAGEix-GLOBIOM about message_doc HOT 4 CLOSED

Should we automate the versioning here? E.g., could define a variable in conf.py like MESSAGE_VERSION=message_ix.__version__ and utilize it throughout..

from message_doc.

Also, I note in the reviewer assignments, I am assigned to review "climate". Who is revising?

from message_doc.

I went through the sessions I was assigned to revise (some related to GLOBIOM and water).
I do not have major comments, the explanation and reference look exhaustive.

Only comment perhaps is to increase the fonts of figure 19, which is not really readable.
But I cannot make the changes as I do not have the source image

from message_doc.

I read the documentation and have the following comments/remarks:

1. General
   1.1. It is not clear (to me:-)) whether the model is MESSAGEix or MESSAGE? Maybe a clarification should be added
   1.2. I think that the description of data sources for the model and the parameters should be stated in the beginning. I know that it’s not an easy task, but I think that a paragraph-long description that the model is based on the actual energy and economic data for the years 1960-2015 (is it so?)+ the official projections for economic development for the years 2020-2100 would be beneficial.
   1.3. In addition, the question of what is input and what is the output of the model is unclear. For instance, if socio –economic development from SSPs is an input, I would recommend titling this section differently, e. g. Input of drivers of future socio-econ development, or something more clear for external reader.

2. Overview
   2.1. I suggest to move Fig 1 up to appear just after the first paragraph, so that the structure is visualized from the first glance on the page
   2.2. In SSPs section, the 3 SSPs out of five are presented. Is MESSAGE run for all 3 SSPs? or only SSP2? is one of them so called "baseline scenario" and the other are alternatives?
   2.3 then the natural question of external reader is if the scenarios are plugged in as given to MESSAGE, what is its output? what is left to evaluate. I know that there is a lot to, but maybe it's worth to address briefly. and refer to latest papers

3. Energy
   3.1. Suggest putting the figure of MESSAGE structure after the first paragraph + the link to mathematical representation of the model.
   3.2. There is a mentioning of mathematical representation of MESSAGE in the end of this section. I recommend to add the hyperlink there too
   3.3. Energy resource endowments – this section is empty – only redirects to subsections. I would add, again that historical data of resource utilization until 2015 are based on official statistics, and the developments of reserves and resources are described in subsections to follow+add link to math representation in "3 Domestic Resources"
   3.4. Non-Biomass Renewable Resources- Title for row 1 in table 1 is missing
   3.5. add hyperlink from Energy conversion description to sub section on conversion in math documentation
   3.6. Energy demand – in this sub section of documentation, I would recommend to start from clear statement that the energy demand by 7 final users till the end of 21st century is generated based on forecasts for GDP and population. And, if possible add the link to mathematical representation of the scenario generator. In addition, the last paragraph before table 21 states that “final energy is converted to useful energy in each region by using the average final-to-useful energy efficiencies used in the MESSAGE”. is it possible to report these final-to-useful energy efficiencies – what are the values or reference where they come from?

from message_doc.