poe.1.in (9198B)
1 .\" This program is licensed under the terms of GNU GPL v3 or (at your option) 2 .\" any later version. Copyright (C) 2021-2026 Страхиња Радић. 3 .\" See the file LICENSE for exact copyright and license details. 4 .Dd %DATE% 5 .Dt POE 1 6 .Os 7 .Sh NAME 8 .Nm poe 9 .Nd .po file editor 10 .Sh SYNOPSIS 11 .Nm 12 .Fl h | \-help | Fl V | \-full\-version | Fl v | \-version 13 .Nm 14 .Op Fl B | \-no\-backup 15 .Op Fl b | \-backup 16 .Op Fl L | \-dont\-break\-literals 17 .Op Fl W | \-no\-wrap 18 .Op Fl w Ar cols No | Fl \-wrap\-width= Ns Ar cols 19 .Ar filename.po 20 .Sh DESCRIPTION 21 .Nm 22 is a .po (GNU gettext) file editor with a terminal UI. 23 .Bl -tag -width Ds 24 .It Fl B , \-no\-backup 25 Disables backups. 26 This option overrides the setting in 27 .Pa config.h . 28 .It Fl b , \-backup 29 Enables backups. 30 This option overrides the setting in 31 .Pa config.h . 32 .It Fl h , \-help 33 Show option summary. 34 .It Fl L , \-dont\-break\-literals 35 Don't break long literals into an empty string and a literal on a separate line. 36 By default (unless changed in 37 .Pa config.h Ns ), 38 if the length of the text 39 .Bd -literal -offset indent 40 msgid \(dq 41 .Ed 42 .Pp 43 (or 44 .Ic msgid_plural , 45 .Ic msgstr , 46 etc) plus the length of the literal, plus one (for the closing quote) is greater 47 than 48 .Va literal_break_threshold , 49 a line of the form 50 .Bd -literal -offset indent 51 msgid \(dqSome really long literal string\(dq 52 .Ed 53 .Pp 54 will be broken into two lines: 55 .Bd -literal -offset indent 56 msgid \(dq\(dq 57 \(dqSome really long literal string\(dq 58 .Ed 59 .Pp 60 This option prevents that. 61 It overrides the setting in 62 .Pa config.h . 63 .It Fl V , \-full\-version 64 Show full version information: like 65 .Fl v , 66 followed by copyright notice and the state of options. 67 .It Fl v , \-version 68 Show version information: program version and source git repository commit date. 69 .It Fl W , \-no\-wrap 70 Sets 71 .Va wrap_width 72 to 0, effectively turning off wrapping of 73 .Ic msgid Ns s, 74 .Ic msgid_plural Ns s, 75 .Ic msgstr Ns s 76 and 77 .Ic msgstr[nn] Ns s 78 on save. 79 .It Fl w Ar cols , Fl \-wrap\-width= Ns Ar cols 80 Sets 81 .Va wrap_width 82 to the specified value. 83 If 84 .Ad cols 85 is negative, it will be set to zero, effectively turning off wrapping on save. 86 .El 87 .Ss Key bindings 88 Main window key bindings are as follows: 89 .Bl -column -offset Ds "C-F or PgDn" 90 .It Sy Key Ta Sy Action 91 .It \f[CR]Esc\fR Ta Close dialog or clear error 92 .It \f[CR]Enter\fR Ta Edit entry 93 .It \f[CR]H\fR or \f[CR]F1\fR Ta Show help dialog 94 .It \f[CR]/\fR or \f[CR]F7\fR Ta Incremental search (end input with Enter) 95 .It \f[CR]n\fR or \f[CR]F3\fR Ta Find next 96 .It \f[CR]N\fR or \f[CR]F4\fR Ta Find previous 97 .It \f[CR]u\fR or \f[CR]F8\fR Ta Go to next untranslated entry 98 .It \f[CR]f\fR or \f[CR]F9\fR Ta Go to next fuzzy entry 99 .It \f[CR]w\fR or \f[CR]C-S\fR Ta Save file (with backup) 100 .It \f[CR]g\fR or \f[CR]Home\fR Ta Go to first entry 101 .It \f[CR]C-B\fR or \f[CR]PgUp\fR Ta Go to previous page 102 .It \f[CR]k\fR or \f[CR]Up\fR Ta Go to previous entry 103 .It \f[CR]j\fR or \f[CR]Down\fR Ta Go to next entry 104 .It \f[CR]C-F\fR or \f[CR]PgDn\fR Ta Go to next page 105 .It \f[CR]G\fR or \f[CR]End\fR Ta Go to last entry 106 .It \f[CR]z\fR or \f[CR]C-Z\fR Ta Toggle fuzzy flag 107 .It \f[CR]q\fR or \f[CR]C-Q\fR Ta Quit 108 .El 109 .Pp 110 Edit dialog key bindings are as follows: 111 .Bl -column -offset Ds "C-A or Home" 112 .It Sy Key Ta Sy Action 113 .It \f[CR]C-S\fR Ta Update entry and close dialog 114 .It \f[CR]C-B\fR or \f[CR]PgUp\fR Ta Update entry and edit previous entry 115 .It \f[CR]C-F\fR or \f[CR]PgDn\fR Ta Update entry and edit next entry 116 .It \f[CR]C-P\fR Ta Show previous plural form of Ic msgstr 117 .It \f[CR]C-N\fR Ta Show next plural form of Ic msgstr 118 .It \f[CR]Escape\fR Ta Cancel changes and close dialog 119 .It \f[CR]C-C\fR Ta Yank (copy) current Ic msgstr No to paste buffer 120 .It \f[CR]C-V\fR Ta Paste the contents of paste buffer into current Ic msgstr 121 .It \f[CR]F8\fR Ta Go to next untranslated entry 122 .It \f[CR]F9\fR Ta Go to next fuzzy entry 123 .It \f[CR]F5\fR Ta Copy Ic msgid No to edit box as current Ic msgstr 124 .It \f[CR]F6\fR Ta Toggle focus between info box and edit box 125 .It \f[CR]C-Z\fR Ta Toggle fuzzy flag 126 .It \f[CR]C-A\fR or \f[CR]Home\fR Ta Go to start of line 127 .It \f[CR]C-E\fR or \f[CR]End\fR Ta Go to end of line 128 .It \f[CR]C-U\fR Ta Erase to start of line 129 .It \f[CR]C-K\fR Ta Erase to end of line 130 .It \f[CR]C-R\fR Ta Go to previous word 131 .It \f[CR]C-T\fR Ta Go to next word 132 .It \f[CR]C-W\fR Ta Erase previous word 133 .It \f[CR]Up\fR Ta Go to previous line 134 .It \f[CR]Left\fR Ta Go to previous character 135 .It \f[CR]Right\fR Ta Go to next character 136 .It \f[CR]Down\fR Ta Go to next line 137 .El 138 .Pp 139 In the table above, 140 .Dq current Ic msgstr 141 refers to the situation when there are multiple 142 .Ic msgstr Ns s, 143 representing different plural forms. 144 Only the currently shown plural form is affected. 145 .Pp 146 When the info box is focused, arrow keys, \f[CR]C-B\fR/\f[CR]C-F\fR 147 (\f[CR]PgUp\fR/\f[CR]PgDn\fR) and \f[CR]C-A\fR/\f[CR]C-E\fR 148 (\f[CR]Home\fR/\f[CR]End\fR) keys scroll the info box. 149 .Pp 150 When the search box is open, relevant text editing and movement commands from 151 the edit box also apply. 152 For example, \f[CR]C-R\fR moves one word backwards, and \f[CR]C-W\fR deletes one 153 word backwards. 154 . 155 .Ss Status line 156 Status line is comprised of a number of segments, by default three. 157 The central segment displays the current message number, the total messages 158 count, then in parentheses: number of untranslated messages, number of fuzzy 159 messages and the number of obsolete messages. 160 Obsolete messages are messages whose 161 .Ic msgid 162 doesn't match any 163 .Ic msgid 164 in the message catalog anymore, and are commented out in the .po file using 165 the \f[CR]#~\fR comments. 166 . 167 .Ss Message flags 168 Message flags are shown to the left of the 169 .Ic msgid 170 in the main window and the statusbar of the edit box. 171 They mean the following: 172 .Bl -column -offset Ds "Character" 173 .It Sy Character Ta Sy Meaning 174 .It \f[CR]C\fR Ta \f[CR]c-format\fR flag 175 .It \f[CR]F\fR Ta \f[CR]fuzzy\fR flag 176 .It \f[CR]P\fR Ta Message has plural forms 177 .It \f[CR]N\fR Ta \f[CR]no-c-format\fR flag 178 .El 179 . 180 .Ss Error checking 181 .Nm 182 has some rudimentary checks of the translated messages built in. 183 First, when saving changes in the edit box, if the 184 .Ic msgid 185 has a newline character (\f[CR]\en\fR), a dot (\f[CR].\fR) or a space 186 (\f[CR]\~\fR) at the end, and the corresponding 187 .Ic msgstr 188 doesn't, 189 .Ic msgstr 190 being saved will have its ending character made to match the one from the 191 .Ic msgid Ns . 192 This feature can be disabled by setting the 193 .Va match_msgstr_ending 194 configuration variable to 0. 195 .Pp 196 Second, if the numbers of newline characters (\f[CR]\en\fR), or, additionally, 197 dots when 198 .Va warn_count_dots 199 is set, in 200 .Ic msgid 201 and 202 .Ic msgstr 203 don't match, 204 .Ic msgstr 205 will be shown in a different color on the main screen. 206 If the number of newlines was intended, you can simply ignore this warning. 207 Otherwise, it can be useful to detect unwanted discrepancies in formatting 208 between the original message and the translation. 209 . 210 .Sh EXIT STATUS 211 .Ex -std 212 .Pp 213 For errors caused by the unsuccessful calls to libc functions setting 214 .Va errno , 215 that value is returned as the exit status. 216 Otherwise, the exit status is one of the following: 217 .Bl -tag -width Ds -offset indent -compact 218 .It Li 201 219 No filename was given on the command line. 220 .It Li 202 221 Command line option is missing a required argument. 222 .It Li 203 223 Command line argument is invalid/unsupported. 224 .It Li 204 225 File is not a valid PO (Portable Object) file. 226 .It Li 205 227 File is not a regular file. 228 .It Li 206 229 There has been a termbox error. 230 .It Li 215 231 Syntax error. 232 .It Li 216 233 PO file doesn't have 234 .Ic "Plural\-Forms:" 235 in the first 236 .Ic msgid . 237 .It Li 217 238 The 239 .Ic nplurals 240 field in the first 241 .Ic msgstr 242 does not contain a valid integer. 243 .El 244 . 245 .Sh DIAGNOSTICS 246 Most error messages output by 247 .Nm 248 are in the format 249 .Bd -ragged -offset Ds 250 .Nm : Ar msg 251 .Ed 252 .Pp 253 In the case of a syntax error, output is in the format: 254 .Bd -ragged -offset Ds 255 .Nm : 256 .Ar filename : Ns Ar lineno : Ns Ar colno : Ar msg 257 .Ed 258 .Pp 259 where 260 .Ar filename 261 is the name of the input file, 262 .Ar lineno 263 and 264 .Ar colno 265 are the line and column numbers in the input file where the error occured. 266 .Pp 267 When the error is caused by an error in the libc function which sets 268 .Va errno , 269 .Nm 270 calls 271 .Xr perror 3 272 prior to outputting an error message in the above format. 273 . 274 .Sh AUTHORS 275 .An Strahinya Radich Aq Mt sr@strahinja.org , 276 2021\-2026 277 . 278 .Sh BUGS 279 Bugs can be reported using the ticket tracker at: 280 .Lk https://\:todo.sr.ht/\:~strahinja/\:poe 281 . 282 .Ss Known limitations 283 .Bl -bullet -width 1m 284 .It 285 UTF-8 character set is assumed. 286 .It 287 RTL scripts are unsupported/problematic. 288 CJK scripts should work better after v2.0, which introduced the use of 289 .Xr wcwidth 3 . 290 .It 291 Only one file can be edited at a time, and no additional files can be loaded at 292 runtime. 293 This is a design decision. 294 .It 295 Unless the variable 296 .Va create_backups 297 is set to 0 before compilation, or the parameter 298 .Fl B 299 is used when invoking 300 .Nm , 301 the directory of the edited file must be writable by the user in order to write 302 the changes to the file. 303 This is due to creating backups in order to avoid the potential data loss under 304 specific circumstances (loss of power during write). 305 .It 306 Only the flags 307 .Dv fuzzy , 308 .Dv c\-format 309 and 310 .Dv no\-c\-format 311 are supported. 312 Other flags will be stripped on save. 313 This is a design decision. 314 .El