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