installation doc: cmake unclear and failing

[Peter Baumann]

In the doc at ​http://doc.rasdaman.org/02_inst-guide.html#download-and-install-rasdaman there is a line

cmake .. [ -D<option>... ]

To improve here:

• first provide the concrete command to execute, do NOT show some meta yntax where users expect to copy-paste.
• (optional) guidance comes only after explanation of all the options. According to the funnel GUI pattern, that explanation should be a sideline, but not be on the mainline.

• the command indicated does not work for me because the previous step was not followed properly:

  cmake .. -DCMAKE_INSTALL_PREFIX=$RMANHOME -DCMAKE_BUILD_TYPE=Release \
             -DUSE_NETCDF=ON -DUSE_GRIB=ON -DFILE_DATA_DIR=$RMANHOME/data \
             -DWAR_DIR=/var/lib/tomcat/webapps
  

  a Note should be added to clarify that the first parameter .. is the path to the source directory.

[Peter Baumann]

my mistake was that I did "cd ~rasdaman" instead of "cd rasdaman" in an earlier step. So the error above is a user error. We might think, however, how to make it harder to make errors.

In line with this, documentation should be made easier to read (see proposition above, first bullet).

[Dimitar Misev]

If you follow the steps correctly it will work as expected.
I've no idea how to prevent the user from typing ~rasdaman instead of rasdaman. There's no way to make this installation work without cd-ing into some directories.

[Peter Baumann]

yes, agreed. Still let's consider the first bullet:

• first provide the concrete command to execute, do NOT show some meta yntax where users expect to copy-paste.

As a general rule, cmd boxes should only contain something that can be copy/pasted immediately.

[Dimitar Misev]

Yes, this I'll correct.