j1-template 2021.1.28 → 2021.2.2

data/lib/starter_web/pages/public/asciidoc_skeletons/documentation/_includes/documents/200_themes/212_values.asciidoc

@@ -0,0 +1,502 @@
+== Values
+
+The value of a key may be one of the following types:
+
+* String
+  - Font family name (e.g., Roboto)
+  - Font style (normal, bold, italic, bold_italic)
+  - Alignment (left, center, right, justify)
+  - Color as hex string (e.g., #ffffff)
+  - Image path
+  - Enumerated type (where specified)
+  - Text content (where specified)
+* Null (clears any previously assigned value)
+  - _empty_ (i.e., no value specified)
+  - null
+  - ~
+* Number (integer or float) with optional units (default unit is points)
+* Array
+  - Color as RGB array (e.g., [51, 51, 51])
+  - Color CMYK array (e.g., [50, 100, 0, 0])
+  - Margin (e.g., [1in, 1in, 1in, 1in])
+  - Padding (e.g., [1in, 1in, 1in, 1in])
+* Variable reference (e.g., $base_font_color)
+* Math expression
+
+Note that keys almost always require a value of a specific type, as documented
+in section *Keys*.
+
+=== Inheritance
+
+Like CSS, inheritance is a principle feature in the *Asciidoctor PDF* theme
+language. For many of the properties, if a key is not specified, the key
+inherits the value applied to the parent content in the content hierarchy.
+This behavior saves you from having to specify properties unless you want to
+override the inherited value.
+
+The following keys are inherited:
+
+* font_family
+* font_color
+* font_size
+* font_style
+* text_transform
+* line_height (currently some exceptions)
+* margin_bottom (if not specified, defaults to $vertical_spacing)
+
+==== Heading Inheritance
+
+Headings inherit starting from a specific heading level (e.g.,
+`heading_h2_font_size`), then to the heading category (e.g.,
+`heading_font_size`), then directly to the base value (e.g., `base_font_size`).
+Any setting from an enclosing context, such as a sidebar, is skipped.
+
+
+=== Variables
+
+To save you from having to type the same value in your theme over and over, or
+to allow you to base one value on another, the theme language supports variables.
+Variables consist of the key name preceded by a dollar sign (`$`) (e.g.,
+`$base_font_size`). Any qualified key that has already been defined can be
+referenced in the value of another key. (In order words, as soon as the key is
+assigned, it's available to be used as a variable).
+
+IMPORTANT: Variables are defined from top to bottom (i.e., in document order).
+Therefore, a variable must be defined before it is referenced. In other words,
+the path the variable refers to must be *above* the usage of that variable.
+
+For example, once the following line is processed,
+
+[source,yaml]
+----
+base:
+  font_color: #333333
+----
+
+the variable `$base_font_color` will be available for use in subsequent lines
+and will resolve to `#333333`. Let's say you want to make the font color of the
+sidebar title the same as the heading font color. Just assign the value
+`$heading_font_color` to the `$sidebar_title_font_color`.
+
+[source,yaml]
+----
+heading:
+  font_color: #191919
+sidebar:
+  title:
+    font_color: $heading_font_color
+----
+
+You can also use variables in math expressions to use one value to build
+another. This is commonly done to set font sizes proportionally.It also makes
+it easy to test different values very quickly.
+
+[source,yaml]
+----
+base:
+  font_size: 12
+  font_size_large: $base_font_size * 1.25
+  font_size_small: $base_font_size * 0.85
+----
+
+We'll cover more about math expressions later.
+
+==== Custom Variables
+
+You can define arbitrary key names to make custom variables. This is one way
+to group reusable values at the top of your theme file. If you are going to
+do this, it's recommended that you organize the keys under a custom namespace,
+such as `brand`.
+
+For instance, here's how you can define your brand colors:
+
+[source,yaml,subs=attributes+]
+----
+brand:
+  primary: #E0162B <1>
+  secondary: '#FFFFFF' <2>
+  alert: '0052A5' <3>
+----
+<1> To align with CSS, you may add a `+#+` in front of the hex color value.
+A YAML preprocessor is used to ensure the value is not treated as a comment
+as it would normally be the case in YAML.
+
+<2> You may put quotes around the CSS-style hex value to make it friendly
+to a YAML editor or validation tool.
+
+<3> The leading `+#+` on a hex value is entirely optional. However, we
+recommend that you always use either a leading `+#+` or surrounding quotes
+(or both) to prevent YAML from mangling the value.
+
+You can now use these custom variables later in the theme file:
+
+[source,yaml]
+----
+base:
+  font_color: $brand_primary
+----
+
+=== Math Expressions & Functions
+
+The theme language supports basic math operations to support calculated values.
+Like programming languages, multiple and divide take precedence over add and
+subtract.
+
+The following table lists the supported operations and the corresponding
+operator for each.
+
+[width="100%", cols="50%,50%", options="header", role="table-responsive mt-3"]
+|===
+|Operation |Operator
+
+|multiply
+|*
+
+|divide
+|/
+
+|add
+|+
+
+|subtract
+|-
+
+|===
+
+IMPORTANT: Operators must always be surrounded by a space on either side
+(e.g., 2 + 2, not 2+2).
+
+Here's an example of a math expression with fixed values.
+
+[source,yaml]
+----
+conum:
+  line_height: 4 / 3
+----
+
+Variables may be used in place of numbers anywhere in the expression:
+
+[source,yaml]
+----
+base:
+  font_size: 12
+  font_size_large: $base_font_size * 1.25
+----
+
+Values used in a math expression are automatically coerced to a float value
+before the operation. If the result of the expression is an integer, the
+value is coerced to an integer afterwards.
+
+IMPORTANT: Numeric values less than 1 must have a 0 before the decimal
+point (e.g., 0.85).
+
+The theme language also supports several functions for rounding the result
+of a math expression. The following functions may be used if they surround
+the whole value or expression for a key.
+
+round(...):: Rounds the number to the nearest half integer.
+floor(...):: Rounds the number up to the next integer.
+ceil(...):: Rounds the number down the previous integer.
+
+You might use these functions in font size calculations so that you get more
+exact values.
+
+[source,yaml]
+----
+base:
+  font_size: 12.5
+  font_size_large: ceil($base_font_size * 1.25)
+----
+
+=== Measurement Units
+
+Several of the keys require a value in points (pt), the unit of measure for
+the PDF canvas. A point is defined as 1/72 of an inch. If you specify a number
+without any units, the units defaults to pt.
+
+However, us humans like to think in real world units like inches (in),
+centimeters (cm), or millimeters (mm). You can let the theme do this
+conversion for you automatically by adding a unit notation next to any number.
+
+The following units are supported:
+
+[width="100%", cols="50%,50%", options="header", role="table-responsive mt-3"]
+|===
+|Unit |Suffix
+
+|Centimeter
+|cm
+
+|Inches
+|in
+
+|Millimeter
+|mm
+
+|Percentage^[1]^
+|%, vw, or vh
+
+|Points
+|pt (default)
+|===
+
+A percentage with the % unit is calculated relative to the width or height
+of the content area. Viewport-relative percentages (vw or vh units) are
+calculated as a percentage of the page width or height, respectively.
+Currently, percentage units can only be used for placing elements on the
+title page or for setting the width of a block image.
+
+IMPORTANT: Numbers with more than two digits should be written as a float
+(e.g., 100.0), a math expression (e.g, 1 * 100), or with a unit (e.g., 100pt).
+Otherwise, the value may be misinterpreted as a hex color (e.g., '100') and
+could cause the converter to crash.
+
+Here's an example of how you can use inches to define the page margins:
+
+[source,yaml]
+----
+page:
+  margin: [0.75in, 1in, 0.75in, 1in]
+----
+
+The order of elements in a measurement array is the same as it is in CSS:
+
+. top
+. right
+. bottom
+. left
+
+=== Alignments
+
+The align subkey is used to align text and images within the parent container.
+
+==== Text Alignments
+
+Text can be aligned as follows:
+
+* left
+* center
+* right
+* justify (stretched to each edge)
+
+==== Image Alignments
+
+Images can be aligned as follows:
+
+* left
+* center
+* right
+
+=== Font Styles
+
+In most cases, whereever you can specify a custom font family, you can also
+specify a font style. These two settings are combined to locate the font to #
+use.
+
+The following font styles are recognized:
+
+* normal (no style)
+* italic
+* bold
+* bold_italic
+
+=== Text Transforms
+
+Many places where font properties can be specified, a case transformation can
+be applied to the text. The following transforms are recognized:
+
+* uppercase
+* lowercase
+* none (clears an inherited value)
+
+[CAUTION#transform-unicode-letters]
+====
+Since Ruby 2.4, Ruby has built-in support for transforming the case of any
+letter defined by Unicode. If you're using Ruby < 2.4, and the text you want
+to transform contains characters beyond the Basic Latin character set (e.g.,
+an accented character), you must install either the `activesupport` or the
+`unicode` gem in order for those characters to be transformed.
+
+ $ gem install activesupport
+
+or
+
+ $ gem install unicode
+====
+
+// Additional transforms, such as capitalize, may be added in the future.
+
+=== Colors
+
+The theme language supports color values in three formats:
+
+Hex:: A string of 3 or 6 characters with an optional leading `#`, optional surrounding quotes or both.
+RGB:: An array of numeric values ranging from 0 to 255.
+CMYK:: An array of numeric values ranging from 0 to 1 or from 0% to 100%.
+Transparent:: The special value `transparent` indicates that a color should not be used.
+
+==== Hex
+
+The hex color value is likely most familiar to web developers. The value must
+be either 3 or 6 characters (case insensitive) with an optional leading hash
+(`#`), optional surrounding quotes or both.
+
+To align with CSS, you may add a `+#+` in front of the hex color value. A YAML
+preprocessor is used to ensure the value is not treated as a comment as it
+would normally be the case in YAML.
+
+You also may put quotes around the CSS-style hex value to make it friendly to
+a YAML editor or validation tool. In this case, the leading `+#+` on a hex
+value is entirely optional.
+
+Regardless, we recommend that you always use either a leading `+#+` or
+surrounding quotes (or both) to prevent YAML from mangling the value.
+
+The following are all equivalent values for the color red:
+
+[cols="8*m"]
+|===
+|#ff0000
+|#FF0000
+|'ff0000'
+|'FF0000'
+|#f00
+|#F00
+|'f00'
+|'F00'
+|===
+
+Here's how a hex color value appears in the theme file:
+
+[source,yaml]
+----
+base:
+  font_color: #ff0000
+----
+
+==== RGB
+
+An RGB array value must be three numbers ranging from 0 to 255. The values
+must be separated by commas and be surrounded by square brackets.
+
+NOTE: An RGB array is automatically converted to a hex string internally,
+so there's no difference between ff0000 and [255, 0, 0].
+
+Here's how to specify the color red in RGB:
+
+* [255, 0, 0]
+
+Here's how a RGB color value appears in the theme file:
+
+[source,yaml]
+----
+base:
+  font_color: [255, 0, 0]
+----
+
+==== CMYK
+
+A CMYK array value must be four numbers ranging from 0 and 1 or from 0% to
+100%. The values must be separated by commas and be surrounded by square
+brackets.
+
+Unlike the RGB array, the CMYK array _is not_ converted to a hex string
+internally. PDF has native support for CMYK colors, so you can preserve the
+original color values in the final PDF.
+
+Here's how to specify the color red in CMYK:
+
+* [0, 0.99, 1, 0]
+* [0, 99%, 100%, 0]
+
+Here's how a CMYK color value appears in the theme file:
+
+[source,yaml]
+----
+base:
+  font_color: [0, 0.99, 1, 0]
+----
+
+==== Transparent
+
+It's possible to specify no color by assigning the special value
+`transparent`, as shown here:
+
+[source,yaml]
+----
+base:
+  background_color: transparent
+----
+
+=== Images
+
+An image is specified either as a bare image path or as an inline image macro
+as found in the AsciiDoc syntax. Images are currently resolved relative to the
+value of the `pdf-stylesdir` attribute.
+
+The following image types (and corresponding file extensions) are supported:
+
+* PNG (.png)
+* JPEG (.jpg)
+* SVG (.svg)
+
+CAUTION: The GIF format (.gif) is not supported.
+
+Here's how an image is specified in the theme file as a bare image path:
+
+[source,yaml]
+----
+title_page:
+  background_image: title-cover.png
+----
+
+Here's how the image is specified using the inline image macro:
+
+[source,yaml]
+----
+title_page:
+  background_image: image:title-cover.png[]
+----
+
+Like in the AsciiDoc syntax, the inline image macro allows you to supply
+set the width of the image and the alignment:
+
+[source,yaml]
+----
+title_page:
+  logo_image: image:logo.png[width=250,align=center]
+----
+
+=== Quoted String
+
+Some of the keys accept a quoted string as text content.
+The final segment of these keys is always named `content`.
+
+A content key accepts a string value. It's usually best to quote the string or
+use the {uri-symfony-yaml-format-strings}[YAML multi-line string syntax, {browser-window--new}].
+
+Text content may be formatted using a subset of inline HTML. You can use the
+well-known elements such as `<strong>`, `<em>`, `<code>`, `<a>`, `<sub>`,
+`<sup>`, `<del>`, and `<span>`. The `<span>` element supports the `style`
+attribute, which you can use to specify the `color`, `font-weight`, and
+`font-style` CSS properties. You can also use the `rgb` attribute on the
+`<color>` element to change the color or the `name` and `size` attributes
+on the `<font>` element to change the font properties. If you need to add an
+underline or strikethrough decoration to the text, you can assign the
+`underline` or `line-through` to the `class` attribute on any aforementioned
+element.
+
+Here's an example of using formatting in the content of the menu caret:
+
+[source,yaml]
+----
+menu_caret_content: " <font size=\"1.15em\"><color rgb=\"#b12146\">\u203a</color></font> "
+----
+
+NOTE: The string must be double quoted in order to use a Unicode escape
+code like `\u203a`.
+
+Additionally, normal substitutions are applied to the value of content keys
+for running content, so you can use
+most AsciiDoc inline formatting (e.g., `+*strong*+` or `+{attribute-name}+`)
+in the values of those keys.