Improvements to the new design of the documentations

[seisman]

The latest documentation is available from https://docs.generic-mapping-tools.org/latest.

Please list any problems and suggestions of the new documentations in this issue.

• pssolar and solar are missing from module lineup (Add pssolar to modern and classic module list #1568)
• Thematic listing of modules not alphabetical within each theme (Sort modules alphabetically #1572)
• Inconsistent naming of modules starting with "gmt", e.g. connect, math versus gmtlogo, gmt2kml.
• In the example gallery - have the image link lead to the example page not the original version of the image.
• Show modules list in both alphabetic and thematic (Show both alphametic and thematic module list in one page #1570)
• Split cookbook into chapters even sections
• Have a word about one liners.
• The animation examples don't show the MP4 movie correctly.

[PaulWessel]

pssolar and solar are missing from module lineup.

[PaulWessel]

Thematic listing of modules not alphabetical within each theme.

[PaulWessel]

Inconsistent naming of modules starting with "gmt", e.g. connect, math versus gmtlogo, gmt2kml.

[KristofKoch]

Can't find the PDF Download for the Cookbook. Was super useful to me when on low bandwidth connections. The one-page-monster with all the graphics is a bit difficult in this case.

[KristofKoch]

In the example gallery - have the image link lead to the example page not the original version of the image.

[joa-quim]

IMO the alphabetic list should not have descriptions to allow a more compact organization in multi-columns like we used to have. The idea with it is to find the quickest possible the module we are looking for.

[seisman]

IMO the alphabetic list should not have descriptions to allow a more compact organization in multi-columns like we used to have. The idea with it is to find the quickest possible the module we are looking for.

@joa-quim What do you think about this new design, with both lists and the same page (alphabetic list on top of thematic list).

[seisman]

Can't find the PDF Download for the Cookbook. Was super useful to me when on low bandwidth connections. The one-page-monster with all the graphics is a bit difficult in this case.

@KristofKoch We have decided to drop PDF documentations, due to its limited capability and the complexity to maintain both HTML and PDF versions.

@PaulWessel @joa-quim Do you think we should split the cookbook into smaller files, just like what we did to the tutorial.

[joa-quim]

@seisman Fantastic, like it very much.

[joa-quim]

Regarding the CookBook splitting. Yes, the idea is to break it to make more manageable and easy to find things in it.

[joa-quim]

Have a word about one liners.

[seisman]

Inconsistent naming of modules starting with "gmt", e.g. connect, math versus gmtlogo, gmt2kml.

It's a little odd to have have "2kml" and "kml2gmt". I think we can always have the "gmt" prefix, to make it consistent with the source filenames (i.e. gmtset.c or gmtset.rst).

[PaulWessel]

I agree the one-liner syntax needs to be documented but we kind of want to hide it a bit as well since not the best way for new users to get confused about. I will think of a solution, including even a 1-page appendix. Thoughts?

[PaulWessel]

Hi @seisman, I think the Primer link to the G3 paper is a bit misleading - it is not really a primer I think . I think it is better to have a Reference section at the end and enter the link there.

[PaulWessel]

@seisman, is it OK for me to add another Appendix to GMT_Docs.rst or are you in the process of breaking it up?

[seisman]

Hi @seisman, I think the Primer link to the G3 paper is a bit misleading - it is not really a primer I think . I think it is better to have a Reference section at the end and enter the link there.

The idea of the G3 paper link is to explain modern mode to GMT5 users. But I agree it's not a good primer for new users. Regarding to the Reference section, we already have a section in the cookbook (https://docs.generic-mapping-tools.org/latest/GMT_Docs.html#a-reminder), and also a page in the main site (https://www.generic-mapping-tools.org/cite/), no need for another Reference section.

@seisman, is it OK for me to add another Appendix to GMT_Docs.rst or are you in the process of breaking it up?

Working on it, but it's OK to add chapters/sections to GMT_Docs.rst.

[joa-quim]

I also agree that the gmtmodules should be named as such. math vs grdmath is another example of oddity.
We can add a note at the bottom of the alphabetic list saying that the gmt prefix can be dropped from modules names that have it e.g. use gmt set instead of gmt gmtset

[PaulWessel]

OK, that is a good solution. Agreed.

[seisman]

It seems movie module only works modern mode scripts, do we need to remove it from the classic core module list (https://docs.generic-mapping-tools.org/latest/modules_classic.html)?

[PaulWessel]

I agree. Initially I allowed classic scripts for the pre and post scripts but it is a mess and since the main script has to be modern why even bring it up in classic. So yes, please remove.

[seisman]

I found it a little bit difficult to track multiple issues/suggestions in one issue.

So I'll close this issue. If you have any comments to the new documentations design, please open a new issue.