|No-spaces| Description ----------- **text** plots text strings of variable size, font type, and orientation. Various map projections are provided, with the option to draw and annotate the map boundaries. Greek characters, subscript, superscript, and small caps are supported as follows: The sequence @~ toggles between the selected font and Greek (Symbol). @%\ *no*\ % sets the font to *no*; @%% resets the font to the starting font, @- 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), and @\_ toggles underline on/off. @@ prints the @ sign while @. 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 `. Composite characters (overstrike) may be indicated with the @! 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. 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**)). Required Arguments ------------------ .. _-J: .. |Add_-J| unicode:: 0x20 .. just an invisible code .. include:: explain_-J.rst_ .. _-R: .. |Add_-R| unicode:: 0x20 .. just an invisible code .. include:: explain_-R.rst_ .. |Add_-Rz| unicode:: 0x20 .. just an invisible code .. include:: explain_-Rz.rst_ Optional Arguments ------------------ *textfiles* This is one or more files containing 1 or more records with (*x*, *y*\ [, *font*, *angle*, *justify*], *text*). The attributes in brackets can alternatively be set directly via **-F**. If no files are given, **text** will read standard input. *font* is a font specification with format [*size*,][*font*,][*color*] where *size* is text size in points, *font* is the font to use, and *color* sets the font color. To draw outline fonts you append =\ *pen* to the font specification. The *angle* is measured in degrees counter-clockwise from horizontal, and *justify* sets the alignment. If *font* is not an integer, then it is taken to be a text string with the desired font name (see **-L** for available fonts). The alignment refers to the part of the text string that will be mapped onto the (*x*,\ *y*) point. Choose a 2 character combination of L, C, R (for left, center, or right) and T, M, B for top, middle, or bottom. e.g., BL for lower left. .. _-A: **-A** Angles are given as azimuths; convert them to directions using the current projection. .. _-B: .. include:: explain_-B.rst_ .. _-C: **-C**\ [*dx/dy*][**+to**\|\ **O**\|\ **c**\|\ **C**] Adjust the clearance between the text and the surrounding box [15%]. Only used if **-W** or **-G** are specified. Append the unit you want (**c**\ m, **i**\ nch, or **p**\ oint; if not given we consult :term:`PROJ_LENGTH_UNIT`) or % for a percentage of the font size. Optionally, use modifier **+t** to set the shape of the textbox when using **-G** and/or **-W**. Append lower case **o** to get a straight rectangle [Default]. Append upper case **O** to get a rounded rectangle. In paragraph mode (**-M**) you can also append lower case **c** to get a concave rectangle or append upper case **C** to get a convex rectangle. .. _-D: **-D**\ [**j**\|\ **J**]\ *dx*\ [/*dy*][**+v**\ [*pen*]] Offsets the text from the projected (*x*,\ *y*) point by *dx*,\ *dy* [0/0]. If *dy* is not specified then it is set equal to *dx*. Use **-Dj** to offset the text away from the point instead (i.e., the text justification will determine the direction of the shift). Using **-DJ** will shorten diagonal offsets at corners by sqrt(2). Optionally, append **+v** which will draw a line from the original point to the shifted point; append a *pen* to change the attributes for this line. .. _-F: **-F**\ [**+a**\ [*angle*]][**+c**\ [*justify*]][**+f**\ [*font*]][**+j**\ [*justify*]][**+h**\|\ **l**\|\ **r**\ [*first*] \|\ **t**\ *text*\|\ **z**\ [*format*]] By default, text will be placed horizontally, using the primary annotation font attributes (:term:`FONT_ANNOT_PRIMARY`), and centered on the data point. Use this option to override these defaults by specifying up to three text attributes (font, angle, and justification) directly on the command line. Use **+f** to set the font (size,fontname,color); if no font info is given then the input file must have this information in one of its columns. Use **+a** to set the angle; if no angle is given then the input file must have this as a column. Alternatively, use **+A** to force text-baselines to convert into the -90/+90 range. Use **+j** to set the justification; if no justification is given then the input file must have this as a column. Items read from the data file should be in the same order as specified with the **-F** option. Example: **-F**\ **+f**\ 12p,Helvetica-Bold,red\ **+j+a** selects a 12p red Helvetica-Bold font and expects to read the justification and angle from the file, in that order, after *x*, *y* and before *text*. In addition, the **+c** justification lets us use x,y coordinates extracted from the **-R** string instead of providing them in the input file. For example **-F+c**\ TL gets the *x_min*, *y_max* from the **-R** string and plots the text at the Upper Left corner of the map. Normally, the text to be plotted comes from the data record. Instead, use **+h** or **+l** to select the text as the most recent segment header or segment label, respectively in a multisegment input file, **+r** to use the record number (counting up from *first*), **+t**\ *text* to set a fixed text string (if *text* contains plus characters then the **+t** modifier must be the last modifier in **-F**), or **+z** to format incoming *z* values to a string using the supplied *format* [use :term:`FORMAT_FLOAT_MAP`]. **Note**: If **-Z** is in effect then the *z* value used for formatting is in the 4th, not 3rd column. If you only want a specific word from the trailing text and not the whole line, use **-it**\ *word* to indicate which word (0 is the first word) you want. .. _-G: **-G**\ [*fill*][**+n**] Sets the shade or color used for filling the text box [Default is no fill]. Alternatively, give no *fill* to plot text and then use the text dimensions (and **-C**) to build clip paths and turn clipping on. This clipping can then be turned off later with :doc:`clip` **-C**. To **not** plot the text but activate clipping, use **-G+n** instead. .. _-L: **-L** Lists the font-numbers and font-names available, then exits. .. _-M: **-M** Paragraph mode. Files must be multiple segment files. Segments are separated by a special record whose first character must be *flag* [Default is **>**]. Starting in the 3rd column, we expect to find information pertaining to the typesetting of a text paragraph (the remaining lines until next segment header). The information expected is (*x y* [*font angle justify*] *linespace parwidth parjust*), where *x y font angle justify* are defined above (*font*, *angle*, and *justify* can be set via **-F**), while *linespace* and *parwidth* are the linespacing and paragraph width, respectively. The justification of the text paragraph is governed by *parjust* which may be **l**\ (eft), **c**\ (enter), **r**\ (ight), or **j**\ (ustified). The segment header is followed by one or more lines with paragraph text. Text may contain the escape sequences discussed above. Separate paragraphs with a blank line. Note that here, the justification set via **-F+j** applies to the box alignment since the text justification is set by *parjust*. .. _-N: **-N** Do NOT clip text at map boundaries [Default will clip]. .. _-Q: **-Q**\ **l**\|\ **u** Change all text to either **l**\ ower or **u**\ pper case [Default leaves all text as is]. .. _-U: .. include:: explain_-U.rst_ .. _-V: .. |Add_-V| unicode:: 0x20 .. just an invisible code .. include:: explain_-V.rst_ .. _-W: **-W**\ *pen* Sets the pen used to draw a rectangle around the text string (see **-C**) [Default is width = default, color = black, style = solid]. .. _-X: .. include:: explain_-XY.rst_ .. _-Z: **-Z** For 3-D projections: expect each item to have its own level given in the 3rd column, and **-N** is implicitly set. (Not implemented for paragraph mode). .. include:: explain_-aspatial.rst_ .. |Add_-e| unicode:: 0x20 .. just an invisible code .. include:: explain_-e.rst_ .. |Add_-f| unicode:: 0x20 .. just an invisible code .. include:: explain_-f.rst_ .. |Add_-h| unicode:: 0x20 .. just an invisible code .. include:: explain_-h.rst_ .. _-i: **-it**\ *word* In this module, **-it** can be used to select a specific word from the trailing text [Default is the entire trailing text]. The *word* indicates the word order, with the first word being 0. No numerical columns can be specified. .. include:: explain_colon.rst_ .. |Add_perspective| replace:: (Not implemented for paragraph mode). .. include:: explain_perspective.rst_ .. include:: explain_-qi.rst_ .. include:: explain_-t.rst_ If no transparency is appended then we will read it from the last column per data record instead. .. include:: explain_help.rst_