home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Exec 5 / CD_Magazyn_EXEC_nr_5.iso / Recent / dev / misc / catcheck.lha / catcheck.doc < prev   
Text File  |  2001-06-07  |  24KB  |  621 lines
  1.  
  2.                               --------------
  3.                                catcheck 1.4
  4.                               --------------
  5.  
  6.  
  7. About catcheck
  8. ==============
  9.  
  10. What?
  11. -----
  12.  
  13. catcheck is a tool to test catalog files. Catalog files are used on the Amiga
  14. by applications to display strings in your native language rather than only a
  15. fixed build-in like English.
  16.  
  17. catcheck finds a large number of common and not so common errors (which can
  18. be quiet annoying:). While most of these errors are human-made, there are
  19. also some that have their origin in buggy catalog compilers. An exotic
  20. example is the #lengthbytes command, which is, to my knowledge, only
  21. supported by C='s own catalog compiler, catcomp. All other compilers
  22. either complain about an unsupported command or, even worse, ignore
  23. it completely and produce somewhat unusable catalogs.
  24.  
  25. Examples for human-made errors are missing or removed strings, wrong
  26. placement or order of arguments (%s, %1$s and that stuff) and the use
  27. of escaped characters like \", \n etc and the string-continues-on-next-
  28. line-marker backslash.
  29.  
  30.  
  31. Why?
  32. ----
  33.  
  34. catcheck's birth was in late 1999. During the translation process of the
  35. catalogs for AmigaOS 3.5, I had a few problems coordinating the work since
  36. we did not get the final catalog sources but update after update appeared,
  37. each one with a new string here and a modified one there.
  38. All in all, it must have been several hundred catalogs to take care of.
  39. Since there was some disagreement about the version string build into
  40. the catalogs (some used it, some not, some in a way I could not use it)
  41. and since this version stuff is insecure anyway (as you'll see in a few
  42. seconds), I wrote a small tool to test if all strings from the original
  43. source also appear in the translation: catcheck.
  44.  
  45. The result was rather disappointing: although I checked all files by
  46. version number and file date several of the files I thought were up-to-date
  47. turned out to be one or more versions behind the current release - that much
  48. for "I'm sure" :]
  49.  
  50. Well, we luckily got that project back on track (only to see it crash
  51. elsewhere;) which would not have been possible without catcheck.
  52.  
  53. catcheck has been improved since then and showed its power during the
  54. AmigaOS 3.9 translation once more.
  55.  
  56.  
  57.  
  58. Legal
  59. =====
  60.  
  61. catcheck has been written by Sönke Tesch <soenke@kino-fahrplan.de>.
  62. catcheck is copyrighted software and may be distributed for free only.
  63. Commercial distribution of any kind requires the written agreement of
  64. the author.
  65.  
  66. I do not give any warranties that catcheck works as described or expected.
  67. More exactly, I'm sure that there are some things that need to be improved.
  68.  
  69. However, it's been in use by me for more than year now and by several other
  70. people for quite some time, too, and should work fine. If you find any bugs,
  71. please contact me.
  72.  
  73.  
  74.  
  75. Using catcheck
  76. ==============
  77.  
  78. Note: The terms "description", "translation" and "catalog" usually refer to
  79. the corresponding files ending in ".cd", ".ct" and ".catalog".
  80.  
  81.  
  82.  
  83. CATNAME/M,CDDIR,CTDIR,CATDIR,ALL/S,STATUS/K,DUMPSTRING/K,DUMP/S,DUMPCT/K:
  84.  
  85.   CATNAME/A/M  = name of the catalog file without extension.
  86.   CDDIR        = Directory in which to look for catalog description (.cd).
  87.                  Defaults to / (parent of current directory).
  88.   CTDIR        = Directory in which to look for catalog translation (.ct).
  89.                  Defaults to current directory.
  90.   CATDIR       = Directory in which to look for catalog (.catalog).
  91.                  Defaults to current directory.
  92.   ALL/S        = Check all directories.
  93.   STATUS/K     = Print status information to this file.
  94.                  File will be created only if there is some status info available!
  95.   DUMPSTRING/K = Show strings from all files with this id.
  96.   DUMP/S       = Print out contents of each catalog.
  97.   DUMPCT/K     = Create catalog translation file from catalog.
  98.  
  99. The above extended help text is also available on the command line. Type
  100. "catcheck ?" and, at the prompt, "?" once again.
  101.  
  102.  
  103. Notes on the arguments:
  104.  
  105. ALL and STATUS may not yet work completely.
  106.  
  107. ALL should be used to automatically check all catalogs in all subdirectories,
  108. for example all the files you see in the directory listing below.
  109.  
  110. I've implemented DUMP and DUMPCT just to test if catcheck correctly loads the
  111. files and don't know if they might be usable for day to day work.
  112.  
  113. DUMPSTRING accepts both numbers and names. It will however fail if the name
  114. of a string is "10" since it'll expect you seek for a string with the id
  115. value of 10. Better fix the description file in this case and use meaningful
  116. names for your strings.
  117.  
  118.  
  119. If you are using the directory structure the system uses, i.e. something like
  120.  
  121.   EggPaint/catalogs
  122.     EggPaint.cd
  123.   EggPaint/catalogs/deutsch
  124.     EggPaint.ct   EggPaint.catalog
  125.   EggPaint/catalogs/italiano
  126.     EggPaint.ct   EggPaint.catalog
  127.   EggPaint/catalogs/català
  128.     EggPaint.ct   EggPaint.catalog
  129.  
  130. you can simply make EggPaint/catalogs/[language] your current directory
  131. and enter "catcheck eggpaint". catcheck will find all files needed.
  132.  
  133.  
  134. DUMPCT
  135. ------
  136.  
  137. The DUMPCT-feature allows you to create a translation-file from an existing
  138. description/catalog-pair.
  139. Although you can theoretically create a catalog from this new translation,
  140. you should not do so without checking the translation first. This has two
  141. good reasons:
  142.  
  143. 1) DUMPCT will create the translation file based on the data -exactly- as
  144.    it appears in the catalog. This effectivly means that if your catalog
  145.    is broken, your translation will be, too.
  146.  
  147.    One thing you will probably notice often is quite some strings appear
  148.    with up to three \x00's at the end.
  149.    Strings in a catalog are stored in a large block of repeating id, length
  150.    and data (text) sequences. Since each of these sequences has to start at
  151.    an even position, you have to add padding or 0-bytes (\x00) at the end of
  152.    your data until you are at an even position. So if your string is 3 bytes
  153.    long you need to add 1 extra byte to get at the even position of 4.
  154.    Too my knowledge it is not cleary defined what 'length' has to be in this
  155.    case. Some catalog compilers store the true length (3 in your example),
  156.    some store the length including the padding bytes at the end (4). In the
  157.    latter case you will get the \x00's from DUMPCT since there is no way to
  158.    find out if the \x00's have been placed there by the translator or by the
  159.    catalog compiler.
  160.    Both variants work with locale.library, however.
  161.  
  162. 2) Strings that do not exist in the catalog, either because the description
  163.    has been updated after the catalog was created (i.e. the catalog is
  164.    outdated) or because they have been removed during optimization (i.e.
  165.    they are the same in description and translation), are taken from the
  166.    description.
  167.    In the latter case this is perfectly ok, however in the first case you
  168.    will end up with a catalog that is only half translated.
  169.  
  170.  
  171. Errors and Warnings
  172. ===================
  173.  
  174. While loading and checking the files, catcheck sends error messages to its
  175. output, one message per line. Some of these messages will not fit into one
  176. line of your cli window, so it's probably a good idea to redirect the output
  177. to a file and use MultiView or similar to have a look at it later.
  178.  
  179.  
  180. Note that..
  181.  ..the same problem might cause more than one error message.
  182.  ..one string may contain more than one error but only the first is displayed
  183.    because parsing stopped after the first error appeared.
  184.  
  185. Therefore you will need to use catcheck once, fix the bugs, re-compile and
  186. call catcheck again.
  187.  
  188.  
  189. Watch out! During the year of its existence, several people complained about
  190. catcheck reporting bugs at places that are "absolutly correct". I won't say
  191. that these complains were always wrong but I actually cannot remember one
  192. that was right.
  193. So, from this point of view, and although I hate to say things like that,
  194. I'd state that catcheck cannot be fooled easily - if catcheck reports a bug,
  195. there is something to take care of.
  196.  
  197.  
  198. The following list is a more or less complete one showing what catcheck
  199. might find. It's an old one however, some messages have disappeared or
  200. been modified, some new have been added.
  201.  
  202.  
  203. Version
  204. -------
  205.  
  206. [file], version "[versionstring]", pos [position]: missing revision value.
  207.  
  208.   The version from this file does not have a revision. The revision was expected
  209.   after the "." at the given position.
  210.  
  211.  
  212. [file], version "[versionstring]", pos [position]: version date missing, incorrect
  213. or in an illegal form.
  214.  
  215.   Check that the date part of the version string looks like "(day.month.year)", e.g.
  216.   "(2.9.89)" or "(18.8.2000)". The problem is at the given position.
  217.  
  218. [file], version "[versionstring]", pos [position]: missing '$VER:'.
  219.  
  220.   Standard Amiga version strings start with $VER:.
  221.  
  222.  
  223. [file], version "[versionstring]", pos [position]: expected version number.
  224.  
  225.   We're expecting a version in front of the "." at the given position.
  226.  
  227.  
  228. [file], version "[versionstring]", pos [position]: missing or incorrect version string.
  229.  
  230.   Couldn't parse the version at all.
  231.  
  232.  
  233. (Description|Translation|Catalog) has no version.
  234.  
  235.   As it says, no version information found.
  236.  
  237.  
  238. Translation version [version] doesn't match description version [version].
  239.  
  240.   You are using different versions of translation and description files.
  241.  
  242.  
  243. No object name in version string.
  244. Object name '%s' in version string doesn't end with '.catalog'.
  245. Object name '%s' in version string doesn't match real catalog name.
  246.  
  247.   The name part of the version string should be the catalogs' name.
  248.  
  249.   Most common problem is case #2: People enter "EggPaint.ct" in the version
  250.   string of the .ct-file, which might seem correct and logical at first.
  251.   However, this version string is copied 1:1 to the catalog and therefore the
  252.   catalog will also report "EggPaint.ct". You'll get the "doesn't end with
  253.   '.catalog'"-message then.
  254.   To fix this, change the name in the version string in the .ct-file to
  255.   "EggPaint.catalog".
  256.  
  257.  
  258. Reading the files
  259. -----------------
  260.  
  261. [file], line [linenumber], pos [position]: [error] - read [token]: `[buffer]`"
  262.  
  263.   Various syntax errors during parsing.
  264.  
  265.  
  266. [file], line [linenumber]: expected string id, found nothing.
  267.  
  268.   error
  269.  
  270.   We expected a string id in this line, but found absolutly nothing.
  271.  
  272.  
  273. [file], line [linenumber], pos [position]: command missing after ##.
  274.  
  275.   error
  276.  
  277.   Commands in translation and description files start with # or ##. We have a # or ##
  278.   here, but no command.
  279.  
  280.  
  281. [file], line [linennumber], pos [position]: language name missing after ##language.
  282.  
  283.   No language given here.
  284.  
  285.  
  286. [file], line [linenumber], pos [position]: string id may not contain spaces: `[buffer]`.
  287.  
  288.   We expected a string id in [buffer], but the string contains spaces.
  289.  
  290.  
  291. [file], line [linenumber], pos [position]: string [id] continues with a ; as first
  292. character. Was this a comment?
  293.  
  294.   In translation files, you can split strings up into several lines by placing
  295.   a \ at the end of a line. Example:
  296.  
  297.     MSG_EXAMPLE
  298.     This is \
  299.     a long string.
  300.     ; \-demo
  301.  
  302.   This will result in "This is a long string." in the catalog.
  303.  
  304.   One in a while it happens that the last part is removed ("a long string." here)
  305.   but that person forgets to remove the "\". That will result in the comment line
  306.   being appened to the real string: "This is ; \-demo" will appear in the catalog.
  307.   catcheck will warn you if it encounters a ";" as the first character on a line
  308.   after the last line had a "\" at its end.
  309.  
  310.  
  311. Checking RawDoFmt
  312. -----------------
  313.  
  314. This routine may still be confused with strings that are used with FormatDate() instead
  315. of FormatString or RawDoFmt.
  316.  
  317.  
  318. [string_id] in [file], line [linenumber], pos [position]: must use argument positioning.
  319.  
  320.   locale.library's FormatString may re-arrange the arguments. If this option is used
  321.   for one argument, it must be used for all others, too.
  322.   This error appears if catcomp first encountered an argument without positioning and
  323.   now found one with positioning.
  324.  
  325.  
  326. [string_id] in [file], line [linenumber], byte [position]: argument positioning not allowed.
  327.  
  328.   This is nearly the same as the error above, but in this case catcomp first found an
  329.   argument with positioning and now found one without.
  330.  
  331.  
  332. [string_id in [file], line [linenumber], pos [position]: argument position must be at least 1
  333.  
  334.   The argument positions used with FormatString start at 1, not at 0.
  335.  
  336.  
  337. [string_id] in [file], line [linenumber], byte [position]: missing field limit after ".".
  338.  
  339.   The maximum number of characters FormatString/RawDoFmt may send to the output may be
  340.   limited by a value. The "." that announces this value is there, but the value not.
  341.  
  342.  
  343. [string_id] in translation, line [linenumber]: argument [count] from description is missing.
  344.  
  345.   The original text in the description file had more arguments than the text in the
  346.   translation. This is not serious, but the user may miss information.
  347.  
  348.  
  349. [string_id] in translation, line [linenumber]: argument [count] is not in description.
  350.  
  351.   Same as above, but this time the argument [count] which is in the translation was not
  352.   in the original text in the description file. This is a serious bug which may trash
  353.   the text that should be displayed to the user.
  354.  
  355.  
  356. [string_id] in description, line [linennumber], and translation, line [linenumber]: types
  357. of argument [count] are not the same ([type1] vs [type2]).
  358.  
  359.   Serious bug. May appear if, e.g., in the original a value should be inserted in the
  360.   text but in the translation a string is output at the same position.
  361.  
  362.  
  363. [string_id] in description, line [linenumber], and translation, line [linenumber]: input
  364. data lengths of argument [count] are not the same.
  365.  
  366.   In the original a longword was specified, in the translation only a word (or the other
  367.   way round). Will mix up the arguments and trash the output.
  368.  
  369.  
  370. [string_id] in description, line [linenumber], and translation, line [linenumber]: field
  371. widths of argument [count] are not the same.
  372. [string_id] in description, line [linenumber], and translation, line [linenumber]: field
  373. limits of argument [count] are not the same.
  374.  
  375.   Will only mean that the output of the translation is a bit more left or right than
  376.   it was in the original. No big deal after all - had some spare time when writing
  377.   this part of catcheck ;)
  378.  
  379.  
  380.  
  381. Checking translation vs. description
  382. ------------------------------------
  383.  
  384. [string_id] in description, line [linennumber], exists more than one time.
  385.  
  386.   There are more than one string with the name [string_id] in your description file.
  387.  
  388.  
  389. [string_id] (description line [linenumber]) is missing in translation.
  390.  
  391.   This string was specified in the description but is not in your translation file.
  392.   All strings that are in the description should appear in the translation, even if
  393.   they are the same.
  394.   You are probably using an old version of the translation file.
  395.  
  396.  
  397. [string_id] in translation, line [linennumber], must be no shorter than [min] bytes (has [length]).
  398.  
  399.   This string has a minimum limit of [min] characters defined in the description
  400.   file but your translation has only [length] bytes and thus is too short.
  401.  
  402.  
  403. [string_id] in translation, line [linennumber], must be no longer than [max] bytes (has [length]).
  404.  
  405.   This string has a maximum limit of [max] characters defined in the description
  406.   file but your translation has [length] bytes and thus is too long.
  407.  
  408.  
  409. [string_id] in description, line [linenumber], was 0 bytes long. Translation, line
  410. [linennumber], has [length] bytes.
  411.  
  412.   No text was specified in the description for this string but there is some text
  413.   in the translation. This usually appears if the programs' author added some optional
  414.   fields in the catalog that e.g. may be used for extra menu shortcuts in translations.
  415.  
  416.  
  417. No text in translation, line [linenumber], for [string_id] from description, line [linenumber].
  418.  
  419.   Some text was given in the description file, but there is nothing in the translation.
  420.   You most likely updated the translation file with your catalog compiler and did not
  421.   yet translate all of the new strings.
  422.  
  423.  
  424. [string_id] in description, line [linenumber], has [num] trailing spaces. In translation,
  425. line [linenumber], it has [num].
  426.  
  427.   The original text had some spaces at its end, maybe used to make some table. The
  428.   translation has no spaces and thus the full output may look weird.
  429.   This problem appears if you are using a text editor to translate the translation
  430.   file and you text editor automatically strips the spaces at the end of each line.
  431.  
  432.   This message may be followed by "Both have same length, though.", which makes it
  433.   a warning instead of an error.
  434.  
  435.  
  436. [string_id] in translation, line [linenumber], exists more than one time in translation.
  437.  
  438.   There are more than one string with the name [string_id] in your translation file.
  439.  
  440.  
  441. [string_id] from translation, line [linenumber], does not exist in description.
  442.  
  443.   A string with this id does not exist in the description file. You are most
  444.   likely using an outdated translation file.
  445.  
  446.  
  447. Catalog version [version] doesn't match translation version [version].
  448.  
  449.   Catalog and translation file versions must match exactly. Note: this means only
  450.   the version does not match. catcheck and locale.library do not care about the
  451.   revision.
  452.  
  453.  
  454. Catalog version [version] doesn't match description version [version].
  455.  
  456.   Catalog and description file versions must match exactly. Note: this means only
  457.   the version does not match. catcheck and locale.library do not care about the
  458.   revision.
  459.  
  460.  
  461. [string_id] (description line [linenumber]) is not in catalog although original and
  462. translation are not the same.
  463.  
  464.   Strings that are the same in the original (i.e. build-in) string and in its
  465.   translation must not appear in the catalog file.
  466.   However this string is not the same in original and translation but does not
  467.   appear in the catalog file.
  468.  
  469.  
  470. [string_id] (description line [linenumber]), is not in catalog.
  471.  
  472.   Same as above, but appears if the translation file was not found or couldn't
  473.   be loaded for some other reason.
  474.  
  475.  
  476. [string_id] in catalog doesn't match same string in translation, line [linenumber].
  477.  
  478.   Oops, this should be the same in translation and catalog as the catalog has
  479.   been compiled from the translation. Different files?
  480.  
  481.  
  482. [string_id] in catalog (description line [linenumber]):
  483.   - compiler didn't store length in first [reallength] bytes.
  484.   - stored length of [storedlength] doesn`t match real length of [reallength] bytes.
  485.  
  486.   With the command #lengthbytes it is possible to store the length of a string
  487.   in its first 1 to 4 bytes. This kind of string is called a b-string, used in
  488.   the programming language BCPL.
  489.   Unfortunatly there seems to be no catalog compiler that supports this command
  490.   except C='s catcomp. Even worse, some compilers simply forget about that, no
  491.   warning, nothing.
  492.  
  493.   If the catalog has been generated by such a compiler, you'll get the first
  494.   of the two errors above. catcheck will recognize if the first bytes are used
  495.   for the size of the string or are actually part of the string.
  496.  
  497.   You will see the second error if the stored length is definitly incorrect
  498.   and has not just been forgotten.
  499.  
  500.   If the stored length is seems to be incorrect but the remaining bytes of
  501.   the string (the rest starting at stored length position upto the real end)
  502.   contains nothing, i.e. only 0C/0x0, the second message will be extended with
  503.   "Only 0Cs in [length] trailing bytes though.".
  504.  
  505.   First two cases are serious bugs, last case is nothing to worry about.
  506.  
  507.  
  508. String [string_id] in catalog is not in description and not in translation.
  509.  
  510.   This string has not been defined in the description nor in the translation.
  511.   The catalog has most likely not been made from the description and
  512.   translation files you have.
  513.  
  514.  
  515. String [string_id] in catalog is not in description, but in translation as [string_id].
  516.  
  517.   This string has not been defined in the description file, but it is in the
  518.   translation file.
  519.   This means that the catalog has been made from the translation file, but
  520.   with the help of a description file other than the one you have.
  521.  
  522.  
  523. String [string_id] in catalog (named [string_name] in description) exists more than one time.
  524. String [string_id] in catalog exists more than one time.
  525.  
  526.   This error appears if the string with the number [string_id] exists more than
  527.   one time in the catalog file.
  528.   If there is no string with this id value in the description file, you'll get the
  529.   second error message instead of the first.
  530.  
  531.  
  532. History
  533. =======
  534.  
  535. 1.4 Aminet release (Aminet release 1.2 had a broken readme)
  536. ---
  537.  - DUMPTCT
  538.    - Now dumps a complete ##version-command to the output file, including name and
  539.      date, not just the version.revision-pair.
  540.    - \n\r-sequences are printed as "\n\r\"+newline, not "\n\"+newline+"\r".
  541.    - Original strings are completely commented, not just the first line.
  542.  - catcheck's version was not readable with c:version because another string
  543.    containing a $VER: appeared before the real version string in the executable.
  544.    Oops.
  545.  - Translation/catalog string comparison went one byte too far.
  546.  - If the stored length of a string is longer than the maximum allowed and the part
  547.    between the max and the defined length is filled with 0x00's, no "String too
  548.    long" error will be printed anymore.
  549.    This reduces the error list for catalogs where the stored length of a string
  550.    does not match the real length because padding bytes at the end where counted
  551.    by the compiler, too.
  552.  - Prints a warning if a string in the translation continues with a ; on the next
  553.    line. This might be a comment and someone forgot to remove the / one line up.
  554.  
  555. 1.3
  556. ---
  557.  - Catalog version name variable was not cleared between tests of two catalogs.
  558.  
  559. 1.2 Aminet release
  560. ---
  561.  - Added checking of the name part of the catalogs' version string.
  562.  
  563. 1.1
  564. ---
  565.  - DUMPTCT did not work correctly (and is still not fully tested).
  566.  
  567. 1.0
  568. ---
  569.  - LoadCatalog() treated pad-bytes in the catalog STRS-chunk as being part of
  570.    the string and thus recorded the wrong string length.
  571.  - DUMPSTRING treated arguments like MSG_42 as number instead of name.
  572.  - Errors during file loading (read: DOS errors) now appear in line with the
  573.    other errors.
  574.  - Now "only" needs 8k of stack. Unfortunatly this means that it can only
  575.    handle strings up to 2k in length instead of the previous 4k, but your
  576.    editor will probably break down on that long lines anyway :)
  577.  
  578. 0.5
  579. ---
  580.  - Did not check description file if translation could not be loaded -> buggy
  581.    description files were reported to be ok.
  582.  - DUMPCT did not print default string if there was no translation in catalog
  583.  - DUMPCT did not place the whole original string into comments but only
  584.    the first line
  585.  
  586. 0.4
  587. ---
  588.  - New arguments CD, CT and CATALOG allow checking of specific files.
  589.  - Errors are no longer reported at the time they are found but collected and
  590.    printed after all checking is done. This way file load errors do not appear
  591.    before file status line is printed.
  592.  - Pattern matching works for now CATNAME.
  593.  
  594. 0.3
  595. ---
  596.  - Parsing of octal escape characters (\nnn) still did not work. If there were
  597.    less than three numbers (\nn or \n) the resulting value was 8 times as big
  598.    as it should have been. Never liked that octal numbering system anyway ;)
  599.  - DUMPSTRING didn't recognize special escape characters like \n and displayed
  600.    them as hex values ("\x0A").
  601.  - catcheck's own version was not readable by c:version because some other
  602.    strings (actually error messages) that contained "$VER:" appeared first in
  603.    the executable - bad luck.
  604.  
  605. 0.2
  606. ---
  607.  - Argument positions displayed in error messages for wrong RawDoFmt-strings were
  608.    to small by 1.
  609.  - Parsing of escaped characters using hex numbers (\xnn) was completely broken.
  610.  - For octal placeholders (\nnn) always four characters were removed/replaced, even
  611.    if the octal value was only something like \0 or similar.
  612.  - Did not accept dates in version string with a year value >100 (usually 4-digit years).
  613.  
  614. Still to do:
  615. ------------
  616.  - Stack-hungry.
  617.  - If a problem with escaped characters using hex or octal numbers appears, the
  618.    position catcheck reports is wrong - it's the one in the internal buffer, not
  619.    in the original text.
  620.  
  621.