From 736e783557790a45a7a87a4a761ba36c22c68fe4 Mon Sep 17 00:00:00 2001 From: Andy Meneely Date: Fri, 12 Feb 2016 22:14:54 -0500 Subject: [PATCH] docs: finished porting text --- docs/config.rst | 42 ++++++++++++++++++++++++++++++++++++++++++ docs/dsl/text.rst | 45 +++++++++++++++++++++++++++++++++------------ 2 files changed, 75 insertions(+), 12 deletions(-) diff --git a/docs/config.rst b/docs/config.rst index 076a15b..c86b644 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -55,6 +55,48 @@ warn_png_scale Show a warning on the console when a PNG file is upscaled. Warning is issued per card. +lsquote + default: ``"\u2018"`` + + Smart quoting: change the left single quote when ``markup: true`` + +rsquote + default: ``"\u2019"`` + + Smart quoting: change the right single quote when ``markup: true`` + +ldquote + default: ``"\u201C"`` + + Smart quoting: change the left double quote when ``markup: true`` + +rdquote + default: ``"\u201D"`` + + Smart quoting: change the right double quote when ``markup: true`` + +em_dash + default: ``"\u2014"`` + + Convert the ``--`` to this character when ``markup: true`` + +en_dash + default: ``"\u2013"`` + + Convert the ``---`` to this character when ``markup: true`` + + +ellipsis + default: ``"\u2026"`` + + Convert ``...`` to this character when ``markup: true`` + +smart_quotes + default: true + + When ``markup: true``, the ``text`` method will convert quotes. With ``smart_quotes: false``, explicit replacements like em-dashes and en-dashes will be replaced but not smart quotes. + + Options are available as methods ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/dsl/text.rst b/docs/dsl/text.rst index 563a3c1..368f8ee 100644 --- a/docs/dsl/text.rst +++ b/docs/dsl/text.rst @@ -5,6 +5,7 @@ Renders a string at a given location, width, alignment, font, etc. Unix newlines are interpreted even on Windows (i.e. ``"\n"``). + Options ------- .. include:: /args/expansion.rst @@ -12,41 +13,39 @@ Options str default: ``''`` - the string to be rendered. Must support `#to_s`. If the card responds to `#each`, it's mapped out one at a time across the cards. + the string to be rendered. Must support ``#to_s``. font default: ``'Arial 36'`` - the Font description string, including family, styles, and size. (e.g. `'Arial bold italic 12'`). For the official documentation, see the [Pango docs](http://ruby-gnome2.sourceforge.jp/hiki.cgi?Pango%3A%3AFontDescription#style). This [description](http://www.pygtk.org/pygtk2reference/class-pangofontdescription.html) is also quite good. + the Font description string, including family, styles, and size. (e.g. ``'Arial bold italic 12'``). For the official documentation, see the `Pango docs )`_. This `description `_ is also quite good. font_size default: ``nil`` - an override of font string description, for scaling the font according to the size of the string + an override of font string description (i.e. ``font``). .. include:: /args/xy.rst markup: default: ``false`` - Enable markup parsing of `str` using the HTML-like Pango Markup syntax, defined [here](http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup) and [here](https://developer.gnome.org/pango/stable/PangoMarkupFormat.html). Also does other replacements, such as smart quotes, curly apostraphes, en- and em-dashes, and explict ellipses (not to be confused with ellipsize option). See README for full explanation. + When set to true, various extra styles are allowed. See :ref:`Markup `. width default: ``:auto`` - the width of the box the string will be placed in. Stretches to the content by default.. Supports Unit Conversion, see {file:README.md#Units Units}. + the width of the box the string will be placed in. Stretches to the content by default.. Supports :doc:`/units`. height - default: :``auto`` + default: ``:auto`` - the height of the box the string will be placed in. Stretches to the content by default. Supports Unit Conversion, see {file:README.md#Units Units}. + the height of the box the string will be placed in. Stretches to the content by default. Supports :doc:`/units`. wrap default: ``:word_char`` - [:none, :word, :char, :word_char, true, false] (:word_char) When height is set, determines the behavior of how the string wraps. The `:word_char` option will break at words, but then fall back to characters when the word cannot fit. # - -# Options are `:none, :word, :char, :word_char`. Also: `true` is the same as `:word_char`, `false` is the same as `:none`. Default `:word_char` + when ``height`` is set, determines the behavior of how the string wraps. The ``:word_char`` option will break at words, but then fall back to characters when the word cannot fit. Options are ``:none``, ``:word``, ``:char``, ``:word_char``. Also: ``true`` is the same as ``:word_char``, ``false`` is the same as ``:none``. spacing default: ``0`` @@ -81,7 +80,7 @@ angle stroke_width default: ``0.0`` - the width of the outside stroke. Supports Unit Conversion, see {file:README.md#Units Units}. + the width of the outside stroke. Supports :doc:`/units`, see {file:README.md#Units Units}. stroke_color default: ``:black`` @@ -96,7 +95,7 @@ stroke_strategy dash default: ``''`` - define a dash pattern for the stroke. Provide a string with space-separated numbers that define the pattern of on-and-off alternating strokes, measured in pixels by defautl. Supports Unit Conversion, see {file:README.md#Units Units} (e.g. `'0.02in 0.02in'`). + define a dash pattern for the stroke. Provide a string with space-separated numbers that define the pattern of on-and-off alternating strokes, measured in pixels by defautl. Supports :doc:`/units` (e.g. ``'0.02in 0.02in'``). hint default: ``:nil`` (i.e. no hint) @@ -110,6 +109,28 @@ color .. include:: /args/range.rst .. include:: /args/layout.rst +.. _text-markup: + +Markup +------ + +If you want to do specialized formatting within a given string, Squib has lots of options. By setting ``markup: true``, you enable tons of text processing. This includes: + + * Pango Markup. This is an HTML-like formatting language that specifies formatting inside your string. Pango Markup essentially supports any formatting option, but on a letter-by-letter basis. Such as: font options, letter spacing, gravity, color, etc. See the `Pango docs `_ for details. + * Quotes are converted to their curly counterparts where appropriate. + * Apostraphes are converted to curly as well. + * LaTeX-style quotes are explicitly converted (````like this''``) + * Em-dash and en-dash are converted with triple and double-dashes respectively (``--`` is an en-dash, and ``---`` becomes an em-dash.) + * Ellipses can be specified with ``...`` (three periods). Note that this is entirely different from the ``ellipsize`` option (which determines what to do with overflowing text). + + A few notes: + * Smart quoting assumes the UTF-8 character set by default. If you are in a different character set and want to change how it behaves + * Pango markup uses an XML/HTML-ish processor. Some characters require HTML-entity escaping (e.g. ``&`` for ``&``) + + + You can also disable the auto-quoting mechanism by setting ``smart_quotes: false`` in your config. Explicit replacements will still be performed. See :doc:`/config` + + Examples --------