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