Combine documentations of classic and modern modes into one documentation about gmt HOT 16 CLOSED

WOuld love to avoid the two dirs which was just a convenience to get changes incoroprated for modern mode. There are also other issues such as references to modern mode names. I.e., in basemap.rst we may reference coast.rst while in psbasemap.rst we reference pscoast.rst etc. Any way to include a file with variables that could be "coast" or "pscoast", for instance?

from gmt.

Yes, you're right. It's not easy to reference coast and pscoast in one file.

Maybe we can use sphinx's substitutions feature.

We need two files to define the substitutions, one for modern mode:

.. |DOC-coast| replace:: :doc:`coast <coast>`

one for classic mode,

.. |DOC-coast| replace:: :doc:`pscoast <pscoast>`

Then we can reference coast/pscoast via link to |DOC-coast|. We also need to make a symbol link pscoast.rst, which references the real file coast.rst.

from gmt.

Another alternative may be to only have one file and hide classic only parts in collapsable sections here and here. That would force classic users to click to expand a section that explains how classic mode differ and add those classic examples.

from gmt.

I think the collapsable section way works for the man pages, but not for the cookbook.

from gmt.

Yes, true.

from gmt.

@leo and I discussed this further. Our current plan is to rewrite the top index.rst file to list man pages in a different way: Section 1 would list all the data processors - they have the same name in modern and classic. Section 2 would list the plotters in modern mode, and then section 3 would list classic mode plotters. For the plotters we will break the current two file versions (classic and modern) into three: Two shorter stubs with the classic and modern file names, and both of them will include a third file that has the large common section of option explanations. The classic file will then add in the -O -K -P items. This plan means copying all the classic plotter rst files from doc_classic to doc_modern, creating the three parts per plotter, update the index.rst, and then finally remove the entire doc_classic tree. This procedure should largely eliminate duplicate information in two files. Comments on this plan, please.

from gmt.

Good plan but it's ignoring the --longoptions revolution

from gmt.

Yes and no. Once we move forward with long-options then those are the ones that are listed in the man ages but the short-ones are listed as alternatives. I am not sure how that will really work if we add long-format options for most things. The syntax between -J and --projection= are different. Combining everything in one man page may turn things very complicated. We cannot alienate all existing GMT classic users by burying their information. So this needs some more thinking.

from gmt.

Seems good plan for man pages. What about the cookbook? Are you going to include both classic and modern mode in one single cookbook, or have two cookbooks, one for classic and another for modern?

Below are another two issues related to the documentation. I can open another issue to discuss them if you think they're off-topic.

1. Split the whole documentation into several subdirectories, e.g. man, cookbook, tutorial, api. There are so many files in the doc_modern directory, making it a little too messy to maintain.
2. The GMT_Docs.rst contains all the content of the whole cookbook, resulting in a large HTML file GMT_Docs.html. It takes several seconds (usually >10 s) to load such a large HTML file and all the included figures. I think we should also split the GMT_Docs.rst into chapters and sections.

from gmt.

Knowing that there will be thousands of old, existing GMT users who will stay with classic mode, I think we have to put ourselves in their shoes and ask what would they want. The answer is likely a clean classic documentation tree not complicated by the two modes. Since the two modes are fundamentally very different it is not so easy to explain both in one go, so perhaps it is better to keep modern and classic fully separate (we just need a way to avoid file duplication on our end).
@joa-quim is right that if we start to add the long-format options (--region, etc) into the man pages (and the long-options is not a mode-specific feature so can be used in classic and modern) then the man pages will get more complicated as well. Since most options takes arguments and optional modifiers it is not as simple as many GNU tools such as grep where they can simply list

-B num, --before-context=num

and then explain what that option does. Our situations may be more like this:

-C<length>[u]/<ds>[/<spacing>][+a][+l|r][+v], --crossing=<length>[u]/<ds>[/<spacing>][+alternate][+left|right][+adjust]

Perhaps I am wrong and that this is OK. We may have to mock up a man page to see what it really looks like.
As for your suggestion to split the large GMT_Docs.rst file: Yes, agree fully, but let us wait until we have decided on the modern/classic division issue. As you know, the developers will meet in Portugal in a few weeks and many decisions will be made at that point.

from gmt.

The big problem with the --longoptions is not that much showing a per option double synopsis. The real problem is that the options description keeps making references like "use +n to do this or +m to do that" and we replacing that to "+number=5 and +model=ultrafast" correspond to effectively create a longoptions version for each man page. So, instead of 2 versions we will end up with 4 ((calssic + modern) * (compact + longopt)). This is obviously a overwhelming effort to maintain and a potential big confusion to users but here I don't see what we can do. Either we document the 4 flavors or not.

To reduce our burden to only 2 versions (the situation we are discussion now how to avoid) we need macros that can be called conditionally. My RST is very rusty but I at the time I worked heavily on the docs I don't remember to have found a way to do this.

Breaking up the CookBook has been in our plans for quite some time, but we never really started that task. Here the situation is different from the man pages because there large parts of it that should be common to all 4 versions. And that awaited magic macro could reduce the burden to only some duplications.

from gmt.

Yes, we need an abstraction solution to this, not duplication.

from gmt.

Gentlemen, as I'm no developer I hope you don't mind me sharing my thoughts here with you:

As a user I would highly appreciate separate documentations for classic and modern mode.

I'm one of those "old, existing GMT users" Paul was talking about. I use GMT (the 5.4 branch) heavily in an 10k+ lines of code project which generates charts for aviation use covering the whole world every night.

Currently I'm experimenting with GMT 6 on the dev machine to see what kind of advantages it might hold for me. I'm often deep in the CookBook, having multiple other browser tabs open with various doc pages and I sometimes get confused what mode I'm looking at.

While this mainly my problem to get more organized I would appreciate a hint or cue in the document itself at what mode I'm looking at. Maybe a colored trim like green for classic and pink for modern mode running along the page border or something.

Thank you for continuously developing GMT! It really is an awesome program collection.

from gmt.

I think if sphinx and rst cannot provide enough abstraction then we can do simple things with variable substitution via sed and cmake. We just need to figure out the best way to maintain the documentation source so that we don't have duplications and have to edit two files to fix the same typo, for instance. We will solve this problem during the summit.

from gmt.

@KristofKoch we certainly appreciate user's input and also agree that we must maintain the nothing changes version. I know well the reaction oh no, you changed that!, even when I say, "no, everything keeps working as before, except that you can also do it in a better way".

Regarding your suggestion, yes something like that would be nice but need to know how to do it.

from gmt.

Closed in #370.

from gmt.