Skip to content

Centralize info on character escape sequences in separate file #7221

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Centralize info on character escape sequences in separate file #7221

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions doc/rst/source/character_escape_sequences_info.rst_
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
.. _tbl-escape:

+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| Symbol | Behavior |
+========================+=======================================================================================================================================================+
| @~ | Turns Symbol font on or off (see the :ref:`Symbol font octal code table <Octal_codes_symbol_zap>` for available Greek characters and other symbols) |
+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| @+ | Turns superscript on or off |
+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| @- | Turns subscript on or off |
+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| @# | Turns small caps on or off |
+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| @\_ | Turns underline on or off |
+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| @%\ *font*\ % | Switches to *font* where *font* can either be a font *number* or *name* (try **text -L** for a list); @%% resets to previous font |
+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| @:\ *size*: | Switches to another font size; @:: resets to previous size |
+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| @;\ *color*; | Switches to another font color; @;; resets to previous color |
+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| @!\ | Creates one composite character (overstrike) of the next two characters (see :ref:`examples <escape-examples>`) |
+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| @. | Prints the degree symbol |
+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| @@ | Prints the @ sign itself |
+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| @[ | Turns LaTeX typesetting on or off (see Chapter :doc:`/cookbook/gmt-latex`) |
+------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+

Shorthand notation for a few special European characters has also been added:

.. _tbl-shorthand:

+----------+------------+----------+------------+
| *Code* | *Effect* | *Code* | *Effect* |
+==========+============+==========+============+
| @E | Æ | @e | æ |
+----------+------------+----------+------------+
| @O | Ø | @o | ø |
+----------+------------+----------+------------+
| @A | Å | @a | å |
+----------+------------+----------+------------+
| @C | Ç | @c | ç |
+----------+------------+----------+------------+
| @N | Ñ | @n | ñ |
+----------+------------+----------+------------+
| @U | Ü | @u | ü |
+----------+------------+----------+------------+
| @s | ß | @i | í |
+----------+------------+----------+------------+

Several other European accented characters and many special characters are
available by specifying their full octal code \\xxx (see Chapter
:doc:`/cookbook/octal-codes`). To use the extended character set
:term:`PS_CHAR_ENCODING` must be set to the respective encoding in your
:doc:`/gmt.conf`. Only the special characters belonging to that particular
encoding will be accessible. Remember: Many characters not directly available
by using a single octal codes may be constructed with the composite character
mechanism @!.

However, if your input text contains UTF-8 code characters (e.g., ü, Î)
and you select the ISOLatin1+ character encoding then GMT will substitute
the correct PostScript octal codes for you automatically.
69 changes: 4 additions & 65 deletions doc/rst/source/cookbook/features.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -365,7 +365,7 @@ non-polar plots using **MAP_FRAME_AXES**\ =\ **auto** is **WrStZ**.

For :term:`MAP_LABEL_OFFSET`, **auto** will scale the offset based on figure size if
:term:`MAP_LABEL_MODE` is set to **annot**, but will default to **32p** if
:term:MAP_LABEL_MODE` is set to **axis**.
:term:`MAP_LABEL_MODE` is set to **axis**.

For :term:`MAP_EMBELLISHMENT_MODE`, **auto** means we uses the given size of the
embellishment to set relative sizes of ticks, texts and labels, and offsets.
Expand Down Expand Up @@ -1633,70 +1633,9 @@ Note that under Windows the percent symbol indicates a batch variable,
hence you must use two percent-signs for each one required in the escape
sequence for font switching. In bash scripts the brackets have special meaning, hence you must add double quotes.

.. _tbl-escape:

+-------------------+----------------------------------------------------------------+
+===================+================================================================+
| @~ | Turns symbol font on or off |
+-------------------+----------------------------------------------------------------+
| @+ | Turns superscript on or off |
+-------------------+----------------------------------------------------------------+
| @- | Turns subscript on or off |
+-------------------+----------------------------------------------------------------+
| @# | Turns small caps on or off |
+-------------------+----------------------------------------------------------------+
| @\_ | Turns underline on or off |
+-------------------+----------------------------------------------------------------+
| @%\ *fontno*\ % | Switches to another font; @%% resets to previous font |
+-------------------+----------------------------------------------------------------+
| @:\ *size*: | Switches to another font size; @:: resets to previous size |
+-------------------+----------------------------------------------------------------+
| @;\ *color*; | Switches to another font color; @;; resets to previous color |
+-------------------+----------------------------------------------------------------+
| @! | Creates one composite character of the next two characters |
+-------------------+----------------------------------------------------------------+
| @. | Prints the degree symbol |
+-------------------+----------------------------------------------------------------+
| @@ | Prints the @ sign itself |
+-------------------+----------------------------------------------------------------+

Shorthand notation for a few special European characters has also been added (for others
you must use the full octal code):


.. _tbl-shorthand:

+----------+------------+----------+------------+
| *Code* | *Effect* | *Code* | *Effect* |
+==========+============+==========+============+
| @E | Æ | @e | æ |
+----------+------------+----------+------------+
| @O | Ø | @o | ø |
+----------+------------+----------+------------+
| @A | Å | @a | å |
+----------+------------+----------+------------+
| @C | Ç | @c | ç |
+----------+------------+----------+------------+
| @N | Ñ | @n | ñ |
+----------+------------+----------+------------+
| @U | Ü | @u | ü |
+----------+------------+----------+------------+
| @s | ß | @i | í |
+----------+------------+----------+------------+

However, if your input text contains UTF-8 code characters (e.g., ü, Î)
and you select the ISOLatin1+ character encoding then GMT will substitute
the correct PostScript octal codes for you automatically.

PostScript fonts used in GMT may be re-encoded to include several
accented characters used in many European languages. To access these,
you must specify the full octal code \\xxx allowed for
your choice of character encodings determined by the
:term:`PS_CHAR_ENCODING` setting described in the
:doc:`/gmt.conf` man page. Only the special
characters belonging to a particular encoding will be available. Many
characters not directly available by using single octal codes may be
constructed with the composite character mechanism @!.
.. include:: /character_escape_sequences_info.rst_

.. _escape-examples:

Some examples of escape sequences and embedded octal codes in
GMT strings using the Standard+ encoding:
Expand Down
41 changes: 1 addition & 40 deletions doc/rst/source/text.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,51 +54,12 @@ draw and annotate the map boundaries.
Greek characters, subscript, superscript, and small
caps are supported as follows:

.. list-table::
:widths: 20 80
:header-rows: 1

* - Symbol
- Behavior
* - @~
- Toggles between the selected font and Greek (Symbol)
* - @%\ *font*\ %
- Switches to *font* where *font* can either be a font *number* or *name* (see |-L|) (@%% resets it)
* - @-
- Toggles subscripts on/off
* - @+
- Toggles superscript on/off
* - @#
- Toggles small caps on/off
* - @;\ *color*\ ;
- Changes the font color (@;; resets it)
* - @:\ *size*\ :
- Changes the font size (@:: resets it)
* - @\_
- Toggles underline on/off
* - @@
- Prints the @ sign
* - @.
- Prints the degree symbol

@a, @c, @e, @i, @n, @o, @s, @u, @A, @C, @E, @N, @O, and @U give various accented European
characters, as indicated in Table :ref:`escape <tbl-shorthand>`. Composite characters
(overstrike) may be indicated with the @!<char1><char2> sequence, which will print the
two characters on top of each other.

To learn the octal codes for symbols not available on the
keyboard and some accented European characters, see Section :ref:`Char-esc-seq` and
Appendix :ref:`Chart-Octal-Codes-for-Chars` in the GMT Technical Reference and Cookbook. Note that
:term:`PS_CHAR_ENCODING` must be set to an extended character set in your
:doc:`gmt.conf` file in order to use the accented characters.
.. include:: character_escape_sequences_info.rst_

Using the |-G| or |-W| options, a rectangle underlying the text may be plotted
(does not work for strings with sub/super scripts, symbols, or composite
characters, except in paragraph mode (|-M|)).

Finally, you may typeset LaTeX expressions provided they are enclosed in @[ ... @[ or <math> ... </math>;
see Chapter :doc:`/cookbook/gmt-latex` for more details.

Required Arguments
------------------

Expand Down