Rename `incols` to `use_word` in `pygmt.Figure.text()`

[yvonnefroehlich]

Description of proposed changes

Fixes #1947

Reminders

• [ ] Run make format and make check to make sure the code follows the style guide.
• [ ] Add tests for new features or tests that would have caught the bug that you're fixing.
• [ ] Add new public functions/methods/classes to doc/api/index.rst.
• [ ] Write detailed docstrings for all functions/methods.
• [ ] If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• [ ] If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[yvonnefroehlich]

I think we will go with use_word.

@yvonnefroehlich Please make the changes when you have time.

I started working on this. At the moment the deprecation cycle includes (only) two minor releases, starting at 0.8.0 and ending at 1.0.0 (not 0.10.0 corresponding to the announcement draft). I am unsure about how to

• change i to it or add the t later/externally.
• change the format from string to integer (the docstring is already adjusted corresponding to use_word=<integer>).
• write a test as proposed in the Maintainers Guide.

[seisman]

• change i to it or add the t later/externally.

I think changing i to it is easier.

• change the format from string to integer (the docstring is already adjusted corresponding to use_word=<integer>).

Yes.

[seisman]

Not necessary for just the deprecation of a parameter, but could a new test be written or an existing test modified to include this new parameter? I think it might be good to make sure that text is consistently reading a string from an input file.

Yes, I agree. This can be done in a separate PR.