Reference using LaTeX style \ref for titles/text

[jackbeagley]

Description of the desired feature
I am writing my thesis using LaTeX and want to make a map which shows the location of data that I am showing in other figures. Ideally the figure numbers could be automatically generated, to make a map looking something like this:

As figure numbers can change when more figures are added automatic generation would save lots of time and ensure consistency and correctness too.

It is already possible to include LaTeX equations, but from what I can see this doesn't extend to other LaTeX macros.
Does anyone know what would be involved in implementing this feature?

Are you willing to help implement and maintain this feature? Not for a few months...

Looking forward to some discussion on this, I'm very impressed with GMT overall and the community seems really great.

Cheers

[welcome]

👋 Thanks for opening your first issue here! Please make sure you filled out the template with as much detail as possible. We appreciate that you took the time to contribute!

Please make sure you read our Contributing Guide and abide by our Code of Conduct.

[PaulWessel]

I understand your request and why this would be especially helpful for a thesis or book with lots of figures where manually handling such changes could be a headache. I dislike manual intervention as well. However,...

When we handle the equation we simply create a tiny latex file with that math and render it to an EPS file. This EPS snippet is then placed as any other image or EPS in GMT. This works pretty well and was not too taxing on old brains to figure out and implement.

Working on a paper in Latex myself, I know that when I run my pdflatex commands it builds the *.aux file and it is full of these types of commands:

...
WKWS22_seamounts.aux:\newlabel{WKWS22_Fig_flux}{{7}{9}}
WKWS22_seamounts.aux:\newlabel{eq:flux}{{11}{9}}
WKWS22_seamounts.aux:\newlabel{WKWS22_Fig_increments}{{8}{10}}
WKWS22_seamounts.aux:\newlabel{WKWS22_Fig_slide}{{9}{12}}
...

So I know that my figure WKWS22_Fig_flux is figure 7 and will appear on page 9. In general, I can see us taking the ref argument and finding and returning the item number and the page number. But I dont know how we would make any use of the page number. We dont even know from this whether the ref is a figure or equation, for instance, but that is OK since you have to know that anyway as you type Fig.~\ref{myfig} in the text. I dont know how one would set something that would be formatted as "As we saw in Fig. 43 on page 144".

For GMT to learn this we would have to assume you already have run latex so the aux file is up to date. Then, we would need to know the prefix of you Latex file so we can look for prefix.aux. We must also find any \ref{} statements in the latex text given to GMT so it can look up that reference and replace it.

Since building the paper files may involve a Makefile and special commands we have to assume the *.aux is up to date. How should you pass the Latex name? Some options:

• Set a GMT_LATEX_PREFIX environmental variable. In my case I would do export GMT_LATEX_PREFIX=WKWS22_seamounts
• Add a GMT defaults setting GMT_LATEX_PREFIX which defaults to blank. You would then do either gmt set GMT_LATEX_PREFIX=prefix or use --GMT_LATEX_PREFIX=prefix on the command making a figure.

Since there is no specific option that deals with Latex issues I think those are the two possibilities. Of these, 99% of GMT users cannot spell Latex so that makes the less intrusive environmental setting more appealing to me.

The reference thing is totally different than the equation since GMT is not running latex at all - just fishing out some info from a file and replacing any \ref{} we find in text. So it should be very simple to implement compared to equations. We would do it first before any Latex checking happens since you may have a figure title like -B+t"<math>\Nabla^4w = 0</math> (see Fig. \ref{myFig}", for instance which needs to be come -B+t"<math>\Nabla^4w = 0</math> (see Fig. 6-19}" before we process the Latex.

Happy to see what others in the @GenericMappingTools/gmt-team thinks of this request and my sketched-out solution. I am not particularly convinced that referencing figure numbers from a figure itself is widely used but perhaps it is because it is a pain in the ankle...

[seisman]

For GMT to learn this we would have to assume you already have run latex so the aux file is up to date.

To run latex and generate the aux files, users need to have their GMT images ready. So it means that users have to:

1. Run the GMT script to produce an image (the \ref reference is broken)
2. Include the GMT image in the latex documentation and run latex to generate the aux file
3. Run the GMT script again and replace \ref with the figure number
4. Run latex again to include the updated image in the documentation.

It looks really complicated to me.

Once GMT supports \ref, people may want GMT to support more latex commands (for example, \cite), so I prefer not to implement the feature in GMT.

[PaulWessel]

Fair enough. It is also likely that there can't be that many figures even in a thesis that want to cite figures. So, how much work is it to deal with one or two figures manually versus robbing the GMT team a perfectly good weekend to implement something like this?

[gd-a]

The way I would have done it is by calling GMT script from LaTeX (\input or whatever) to pipe the info.
First run generates the index table (making an incomplete plot)
Second run generates things correctly

PSEUDO-CODE

\begin{document}


\input[./script_gmt.sh \ref{stuff}]

\begin{figure}
\includegraphics{from_gmt.png}
\label{stuff}
\end{figure}

\end{document}

Maybe you can work something from this ?

[jackbeagley]

For GMT to learn this we would have to assume you already have run latex so the aux file is up to date.

To run latex and generate the aux files, users need to have their GMT images ready. So it means that users have to:

1. Run the GMT script to produce an image (the \ref reference is broken)
2. Include the GMT image in the latex documentation and run latex to generate the aux file
3. Run the GMT script again and replace \ref with the figure number
4. Run latex again to include the updated image in the documentation.

It looks really complicated to me.

Once GMT supports \ref, people may want GMT to support more latex commands (for example, \cite), so I prefer not to implement the feature in GMT.

These are pretty valid points and I think for a REALLY robust solution it would need to be done like this, however for me at least I think @PaulWessel's solution would work. This would leave the onus of making sure the Latex file is up to date and that the figure order is correct (and will remain correct after updating the figures) on the user. I think this would be OK, especially if documented properly. It would basically make the proposed feature a "Latex .aux file parser"