Address review comments from R.R. Palatnik

[khaeru]

Per this helpful comment @Ruslana22, address the following issues by:

• one or more PRs, and
• opening new issues, if needed.

General

1.1 It is not clear (to me:-)) whether the model is MESSAGEix or MESSAGE? Maybe a clarification should be added

• Use 'MESSAGE' or 'MESSAGEix' consistently throughout; add to the style guide Rmeco #10 so future authors do the same.

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.

• Add an early, paragraph-long description of model data sources.

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.

• Change this section title.

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.

• Move the figure.

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?

• Update prefatory text to clarify this issue.

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

• Consider w.r.t. item 1.3 above.

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

• Add/move the figure.
• Add two intersphinx references to the message_ix core.

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

• Fix the table.

3.5. add hyperlink from Energy conversion description to sub section on conversion in math documentation

• Add the link.

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.

• Add text.

And, if possible add the link to mathematical representation of the scenario generator.

• Add the link.

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?

• Address this comment.