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