contrib/libxo/doc/field-roles.rst

   1
   2 .. index:: Field Roles
   3 .. _field-roles:
   4
   5 Field Roles
   6 ~~~~~~~~~~~
   7
   8 Field roles are optional, and indicate the role and formatting of the
   9 content.  The roles are listed below; only one role is permitted:
  10
  11 === ============== =================================================
  12 R   Name           Description
  13 === ============== =================================================
  14 C   color          Field has color and effect controls
  15 D   decoration     Field is non-text (e.g., colon, comma)
  16 E   error          Field is an error message
  17 G   gettext        Call gettext(3) on the format string
  18 L   label          Field is text that prefixes a value
  19 N   note           Field is text that follows a value
  20 P   padding        Field is spaces needed for vertical alignment
  21 T   title          Field is a title value for headings
  22 U   units          Field is the units for the previous value field
  23 V   value          Field is the name of field (the default)
  24 W   warning        Field is a warning message
  25 [   start-anchor   Begin a section of anchored variable-width text
  26 ]   stop-anchor    End a section of anchored variable-width text
  27 === ============== =================================================
  28
  29     EXAMPLE:
  30         xo_emit("{L:Free}{D::}{P:   }{:free/%u} {U:Blocks}\n",
  31                 free_blocks);
  32
  33 When a role is not provided, the "*value*" role is used as the default.
  34
  35 Roles and modifiers can also use more verbose names, when preceded by
  36 a comma::
  37
  38     EXAMPLE:
  39         xo_emit("{,label:Free}{,decoration::}{,padding:   }"
  40                 "{,value:free/%u} {,units:Blocks}\n",
  41                 free_blocks);
  42
  43 .. index:: Field Roles; Color
  44 .. _color-role:
  45
  46 The Color Role ({C:})
  47 +++++++++++++++++++++
  48
  49 Colors and effects control how text values are displayed; they are
  50 used for display styles (TEXT and HTML)::
  51
  52     xo_emit("{C:bold}{:value}{C:no-bold}\n", value);
  53
  54 Colors and effects remain in effect until modified by other "C"-role
  55 fields::
  56
  57     xo_emit("{C:bold}{C:inverse}both{C:no-bold}only inverse\n");
  58
  59 If the content is empty, the "*reset*" action is performed::
  60
  61     xo_emit("{C:both,underline}{:value}{C:}\n", value);
  62
  63 The content should be a comma-separated list of zero or more colors or
  64 display effects::
  65
  66     xo_emit("{C:bold,inverse}Ugly{C:no-bold,no-inverse}\n");
  67
  68 The color content can be either static, when placed directly within
  69 the field descriptor, or a printf-style format descriptor can be used,
  70 if preceded by a slash ("/"):
  71
  72    xo_emit("{C:/%s%s}{:value}{C:}", need_bold ? "bold" : "",
  73            need_underline ? "underline" : "", value);
  74
  75 Color names are prefixed with either "fg-" or "bg-" to change the
  76 foreground and background colors, respectively::
  77
  78     xo_emit("{C:/fg-%s,bg-%s}{Lwc:Cost}{:cost/%u}{C:reset}\n",
  79             fg_color, bg_color, cost);
  80
  81 The following table lists the supported effects:
  82
  83 =============== =================================================
  84  Name           Description
  85 =============== =================================================
  86  bg-XXXXX       Change background color
  87  bold           Start bold text effect
  88  fg-XXXXX       Change foreground color
  89  inverse        Start inverse (aka reverse) text effect
  90  no-bold        Stop bold text effect
  91  no-inverse     Stop inverse (aka reverse) text effect
  92  no-underline   Stop underline text effect
  93  normal         Reset effects (only)
  94  reset          Reset colors and effects (restore defaults)
  95  underline      Start underline text effect
  96 =============== =================================================
  97
  98 The following color names are supported:
  99
 100 ========= ============================================
 101  Name      Description
 102 ========= ============================================
 103  black
 104  blue
 105  cyan
 106  default   Default color for foreground or background
 107  green
 108  magenta
 109  red
 110  white
 111  yellow
 112 ========= ============================================
 113
 114 When using colors, the developer should remember that users will
 115 change the foreground and background colors of terminal session
 116 according to their own tastes, so assuming that "blue" looks nice is
 117 never safe, and is a constant annoyance to your dear author.  In
 118 addition, a significant percentage of users (1 in 12) will be color
 119 blind.  Depending on color to convey critical information is not a
 120 good idea.  Color should enhance output, but should not be used as the
 121 sole means of encoding information.
 122
 123 .. index:: Field Roles; Decoration
 124 .. _decoration-role:
 125
 126 The Decoration Role ({D:})
 127 ++++++++++++++++++++++++++
 128
 129 Decorations are typically punctuation marks such as colons,
 130 semi-colons, and commas used to decorate the text and make it simpler
 131 for human readers.  By marking these distinctly, HTML usage scenarios
 132 can use CSS to direct their display parameters::
 133
 134     xo_emit("{D:((}{:name}{D:))}\n", name);
 135
 136 .. index:: Field Roles; Gettext
 137 .. _gettext-role:
 138
 139 The Gettext Role ({G:})
 140 +++++++++++++++++++++++
 141
 142 libxo supports internationalization (i18n) through its use of
 143 gettext(3).  Use the "{G:}" role to request that the remaining part of
 144 the format string, following the "{G:}" field, be handled using
 145 gettext().
 146
 147 Since gettext() uses the string as the key into the message catalog,
 148 libxo uses a simplified version of the format string that removes
 149 unimportant field formatting and modifiers, stopping minor formatting
 150 changes from impacting the expensive translation process.  A developer
 151 change such as changing "/%06d" to "/%08d" should not force hand
 152 inspection of all .po files.
 153
 154 The simplified version can be generated for a single message using the
 155 "`xopo -s $text`" command, or an entire .pot can be translated using
 156 the "`xopo -f $input -o $output`" command.
 157
 158    xo_emit("{G:}Invalid token\n");
 159
 160 The {G:} role allows a domain name to be set.  gettext calls will
 161 continue to use that domain name until the current format string
 162 processing is complete, enabling a library function to emit strings
 163 using it's own catalog.  The domain name can be either static as the
 164 content of the field, or a format can be used to get the domain name
 165 from the arguments.
 166
 167    xo_emit("{G:libc}Service unavailable in restricted mode\n");
 168
 169 See :ref:`i18n` for additional details.
 170
 171 .. index:: Field Roles; Label
 172 .. _label-role:
 173
 174 The Label Role ({L:})
 175 +++++++++++++++++++++
 176
 177 Labels are text that appears before a value::
 178
 179     xo_emit("{Lwc:Cost}{:cost/%u}\n", cost);
 180
 181 .. index:: Field Roles; Note
 182 .. _note-role:
 183
 184 The Note Role ({N:})
 185 ++++++++++++++++++++
 186
 187 Notes are text that appears after a value::
 188
 189     xo_emit("{:cost/%u} {N:per year}\n", cost);
 190
 191 .. index:: Field Roles; Padding
 192 .. _padding-role:
 193
 194 The Padding Role ({P:})
 195 +++++++++++++++++++++++
 196
 197 Padding represents whitespace used before and between fields.
 198
 199 The padding content can be either static, when placed directly within
 200 the field descriptor, or a printf-style format descriptor can be used,
 201 if preceded by a slash ("/")::
 202
 203     xo_emit("{P:        }{Lwc:Cost}{:cost/%u}\n", cost);
 204     xo_emit("{P:/%30s}{Lwc:Cost}{:cost/%u}\n", "", cost);
 205
 206 .. index:: Field Roles; Title
 207 .. _title-role:
 208
 209 The Title Role ({T:})
 210 +++++++++++++++++++++
 211
 212 Title are heading or column headers that are meant to be displayed to
 213 the user.  The title can be either static, when placed directly within
 214 the field descriptor, or a printf-style format descriptor can be used,
 215 if preceded by a slash ("/")::
 216
 217     xo_emit("{T:Interface Statistics}\n");
 218     xo_emit("{T:/%20.20s}{T:/%6.6s}\n", "Item Name", "Cost");
 219
 220 Title fields have an extra convenience feature; if both content and
 221 format are specified, instead of looking to the argument list for a
 222 value, the content is used, allowing a mixture of format and content
 223 within the field descriptor::
 224
 225     xo_emit("{T:Name/%20s}{T:Count/%6s}\n");
 226
 227 Since the incoming argument is a string, the format must be "%s" or
 228 something suitable.
 229
 230 .. index:: Field Roles; Units
 231 .. index:: XOF_UNITS
 232 .. _units-role:
 233
 234 The Units Role ({U:})
 235 +++++++++++++++++++++
 236
 237 Units are the dimension by which values are measured, such as degrees,
 238 miles, bytes, and decibels.  The units field carries this information
 239 for the previous value field::
 240
 241     xo_emit("{Lwc:Distance}{:distance/%u}{Uw:miles}\n", miles);
 242
 243 Note that the sense of the 'w' modifier is reversed for units;
 244 a blank is added before the contents, rather than after it.
 245
 246 When the XOF_UNITS flag is set, units are rendered in XML as the
 247 "units" attribute::
 248
 249     <distance units="miles">50</distance>
 250
 251 Units can also be rendered in HTML as the "data-units" attribute::
 252
 253     <div class="data" data-tag="distance" data-units="miles"
 254          data-xpath="/top/data/distance">50</div>
 255
 256 .. index:: Field Roles; Value
 257 .. _value-role:
 258
 259 The Value Role ({V:} and {:})
 260 +++++++++++++++++++++++++++++
 261
 262 The value role is used to represent the a data value that is
 263 interesting for the non-display output styles (XML and JSON).  Value
 264 is the default role; if no other role designation is given, the field
 265 is a value.  The field name must appear within the field descriptor,
 266 followed by one or two format descriptors.  The first format
 267 descriptor is used for display styles (TEXT and HTML), while the
 268 second one is used for encoding styles (XML and JSON).  If no second
 269 format is given, the encoding format defaults to the first format,
 270 with any minimum width removed.  If no first format is given, both
 271 format descriptors default to "%s"::
 272
 273     xo_emit("{:length/%02u}x{:width/%02u}x{:height/%02u}\n",
 274             length, width, height);
 275     xo_emit("{:author} wrote \"{:poem}\" in {:year/%4d}\n,
 276             author, poem, year);
 277
 278 .. index:: Field Roles; Anchor
 279 .. _anchor-role:
 280
 281 The Anchor Roles ({[:} and {]:})
 282 ++++++++++++++++++++++++++++++++
 283
 284 The anchor roles allow a set of strings by be padded as a group,
 285 but still be visible to xo_emit as distinct fields.  Either the start
 286 or stop anchor can give a field width and it can be either directly in
 287 the descriptor or passed as an argument.  Any fields between the start
 288 and stop anchor are padded to meet the minimum width given.
 289
 290 To give a width directly, encode it as the content of the anchor tag::
 291
 292     xo_emit("({[:10}{:min/%d}/{:max/%d}{]:})\n", min, max);
 293
 294 To pass a width as an argument, use "%d" as the format, which must
 295 appear after the "/".  Note that only "%d" is supported for widths.
 296 Using any other value could ruin your day::
 297
 298     xo_emit("({[:/%d}{:min/%d}/{:max/%d}{]:})\n", width, min, max);
 299
 300 If the width is negative, padding will be added on the right, suitable
 301 for left justification.  Otherwise the padding will be added to the
 302 left of the fields between the start and stop anchors, suitable for
 303 right justification.  If the width is zero, nothing happens.  If the
 304 number of columns of output between the start and stop anchors is less
 305 than the absolute value of the given width, nothing happens.
 306
 307 .. index:: XOF_WARN
 308
 309 Widths over 8k are considered probable errors and not supported.  If
 310 XOF_WARN is set, a warning will be generated.