Bug fixes for VersionResource

Bugs in VersionResource. The strings in the StringFileInfo structure were
written with commas instead of dots. Several methods we corrected and
private method deleted. The change is mostly backward compatible because the
setter still accepts the 'N,N,N,N' format instead of the correct 'N.N.N.N'
format.

The confusion came I think from the following fact. The file and product
versions are stored as numbers and strings in a version resource. The
standard resource compiler expects the numbers in the format N,N,N,N but the
display in the explorer is still N.N.N.N. The string variant of the version
can be any string but usually is just the printed version of the number
variant. It could include things like "RC2" for example and a little
different formatting. E.g. notepad.exe from Microsoft has the file version
number "5.0.2140.1" but the file version strings "5.00.2140.1". The
VersionResource in Dolphin updates the string always with the printed
version of the number variant which is I think ok. The only bug was it used
commas instead of dots.

The fixes are included (including method deletions which are flagged with
#toBeDeleted):

!VersionResource methodsFor!

decodeVersionString: versionString
 "Private - Answer a two element <Array> of 32-bit <integer>, being the most
and least significant
 (respectively) version numbers composed from the <readableString> argument,
which is
 expected to be in the standard 'N.N.N.N' (preferred) or 'N,N,N,N' format."

 | words stream i |
 words := Array new: 4 withAll: 0.
 stream := versionString readStream.
 i := 0.
 [i < words size and: [stream skipWhile: [:c | c isDigit not]]] whileTrue: [
  i := i + 1.
  words at: i put: (Integer readFrom: stream)].
 ^Array with: (DWORD new
    highWord: (words at: 1);
    lowWord: (words at: 2);
    asInteger)
  with: (DWORD new
    highWord: (words at: 3);
    lowWord: (words at: 4);
    asInteger)! !
!VersionResource categoriesFor: #decodeVersionString:!helpers!private! !

!VersionResource methodsFor!

fileVersion
 "Answer the <readableString> file version number for the receiver in the
standard 'N.N.N.N' format."
 "CHA FIX: documentation and correct format."

 ^self fixedInfo fileVersionString! !
!VersionResource categoriesFor: #fileVersion!accessing!public! !

!VersionResource methodsFor!

fileVersion: versionString
 "Set the file version number for the receiver from the <readableString>
 argument, expected to be in the 'N.N.N.N' (preferred) or 'N,N,N,N' format."
 "CHA FIX: Write the stings in the correct N.N.N.N format and documentation
change."

 | versions  |
 versions := self decodeVersionString: versionString.

 "VS_FIXEDFILEINFO does not have any write accessors at present"
 self fixedInfo bytes
  dwordAtOffset: 8 put: versions first;
  dwordAtOffset: 12 put: versions last.

 stringTables do: [:table |
  (table includesKey: 'FileVersion') ifTrue: [
   table at: 'FileVersion' put: self fileVersion]]
! !
!VersionResource categoriesFor: #fileVersion:!accessing!public! !

!VersionResource methodsFor!

fixedInfo
 "Answer the value of the receiver's ''fixedInfo'' instance variable."

 ^fixedInfo! !
!VersionResource categoriesFor: #fixedInfo!accessing!public! !

!VersionResource methodsFor!

formatVersionString: versions
 "Private - Answer a <readableString> version number composed from the two
integer arguments, representing
 the most and least significant 32-bit version numbers respectively,  in the
standard 'N,N,N,N' format."
 "CHA FIX: use dots instead of commas for the STRINGFILEINFO. This method is
no longer used and should be deleted (should be no problem because it is
private."

 #toBeDeleted.
 ^String writeStream
  print: versions first highWord;
  nextPutAll: '.';
  print: versions first lowWord;
  nextPutAll: '.';
  print: versions last highWord;
  nextPutAll: '.';
  print: versions last lowWord;
  contents! !
!VersionResource categoriesFor: #formatVersionString:!helpers!private! !

!VersionResource methodsFor!

productVersion
 "Answer the <readableString> product version number for the receiver in the
standard 'N,N,N,N' format."
 "CHA FIX: documenation and correct format."

 ^self fixedInfo productVersionString! !
!VersionResource categoriesFor: #productVersion!accessing!public! !

!VersionResource methodsFor!

productVersion: versionString
 "Set the product version number for the receiver from the <readableString>
 argument, expected to be in the 'N.N.N.N' (preferred) or 'N,N,N,N' format."
 "CHA FIX: Write the stings in the correct N.N.N.N format and documentation
change."

 | versions |
 versions := self decodeVersionString: versionString.

 "VS_FIXEDFILEINFO does not have any write accessors at present"
 self fixedInfo bytes
  dwordAtOffset: 16 put: versions first;
  dwordAtOffset: 20 put: versions last.

 stringTables do: [:table |
  (table includesKey: 'ProductVersion') ifTrue: [
   table at: 'ProductVersion' put: self productVersion]]! !
!VersionResource categoriesFor: #productVersion:!accessing!public! !

!VersionResource methodsFor!

versionStringFormat
 "Private - Answer a Win32 format <String> to be used for formatting version
numbers."
 "CHA FIX: This private method is no longer used and should be deleted."

 #toBeDeleted.
 ^'%1!!d!!.%2!!d!!.%3!!d!!.%4!!d!!'! !
!VersionResource categoriesFor: #versionStringFormat!constants!private! !

Blair,

is this fix accepted for 5.1.5?

Regards

Carsten

"Carsten Haerle" <[hidden email]> schrieb im Newsbeitrag
news:41120dc6$0$27030$[hidden email]...
> Bugs in VersionResource. The strings in the StringFileInfo structure were
> written with commas instead of dots. Several methods we corrected and
> private method deleted. The change is mostly backward compatible because
the
> setter still accepts the 'N,N,N,N' format instead of the correct 'N.N.N.N'
> format.
>
> The confusion came I think from the following fact. The file and product
> versions are stored as numbers and strings in a version resource. The
> standard resource compiler expects the numbers in the format N,N,N,N but
the
> display in the explorer is still N.N.N.N. The string variant of the
version
> can be any string but usually is just the printed version of the number
> variant. It could include things like "RC2" for example and a little
> different formatting. E.g. notepad.exe from Microsoft has the file version
> number "5.0.2140.1" but the file version strings "5.00.2140.1". The
> VersionResource in Dolphin updates the string always with the printed
> version of the number variant which is I think ok. The only bug was it
used
> commas instead of dots.
>
> The fixes are included (including method deletions which are flagged with
> #toBeDeleted):
>
> !VersionResource methodsFor!
>
> decodeVersionString: versionString
>  "Private - Answer a two element <Array> of 32-bit <integer>, being the
most
> and least significant
>  (respectively) version numbers composed from the <readableString>
argument,
> which is
>  expected to be in the standard 'N.N.N.N' (preferred) or 'N,N,N,N'
format."
>
>  | words stream i |
>  words := Array new: 4 withAll: 0.
>  stream := versionString readStream.
>  i := 0.
>  [i < words size and: [stream skipWhile: [:c | c isDigit not]]] whileTrue:
[ format."
>  "CHA FIX: Write the stings in the correct N.N.N.N format and
documentation the
> standard 'N,N,N,N' format."
>  "CHA FIX: use dots instead of commas for the STRINGFILEINFO. This method
is the <readableString>
>  argument, expected to be in the 'N.N.N.N' (preferred) or 'N,N,N,N'
format."
>  "CHA FIX: Write the stings in the correct N.N.N.N format and
documentation version

"Carsten Haerle" <[hidden email]> wrote in message
news:411cb975$0$26161$[hidden email]...
> Blair,
>
> is this fix accepted for 5.1.5?
>

I'm not convinced there is a bug to fix. We just followed the lead of Visual
Studio (6 as it was at the time) in using a string representation printed
with commas. We also adopted its same behaviour of automatically sync'ing
the string product and file versions with the number version when the latter
is updated, but not vice versa.  This allows one to store additional
information in the string representation if one wishes, as long as this is
set after setting the numeric version numbers.

I don't know of any standard for these, indeed as far as I am aware it isn't
even required that the string version numbers be present at all, and since
they are purely for display purposes and have no fixed format, I don't see
any particularly compelling reason to change it in a patch level.

Regards

Blair

You are right that the there isn't  a standard really requiring that.
Actually it is only a convention and you could write anything into the
version resource and you can append additional things like "RC2" for
example. The widly accepted standard is however the dot notation, which is
also how the explorer formats the number representation. I also checked some
other resources:

1) On my system 94% of all EXEs and DLL use the standard dot notation. If
you just check the Microsoft DLLs and EXE it is even 99% (including most
VisualStudio 6 (98) files). The comma notation is used mostly in programs
which violate several other Microsoft guidelines as well, so I suspect these
programmers simply confused the resource compiler syntax with the usual
string syntax.

2) MSDN:
ms-help://MS.MSDNQTR.2003OCT.1033/tools/tools/stringfileinfo_block.htm
Mentions the dot notation also as an example.

I think Dolphin should also follow common conventions when generating EXEs
and it is also easier to understand, because there are not two formats, and
it took my some hours to understand why Dolphin (uncessarily) deals with two
formats instead of only one (the dot format). If you want to divert from the
common convention you can still set the string version to something else
manually or use special code to do so, but you shouldn't have additional
work to have "standard" programs.

BTW: Originally this problem was reported by a customer to me and then I
started the investigation why almost all DLLs and EXEs use dots and only my
Dolphin generated programs had commas in it.

Regards

Carsten Härle

"Blair McGlashan" <[hidden email]> schrieb im Newsbeitrag
news:[hidden email]...
> "Carsten Haerle" <[hidden email]> wrote in message
> news:411cb975$0$26161$[hidden email]...
> > Blair,
> >
> > is this fix accepted for 5.1.5?
> >
>
> I'm not convinced there is a bug to fix. We just followed the lead of
Visual
> Studio (6 as it was at the time) in using a string representation printed
> with commas. We also adopted its same behaviour of automatically sync'ing
> the string product and file versions with the number version when the
latter
> is updated, but not vice versa.  This allows one to store additional
> information in the string representation if one wishes, as long as this is
> set after setting the numeric version numbers.
>
> I don't know of any standard for these, indeed as far as I am aware it
isn't
> even required that the string version numbers be present at all, and since
> they are purely for display purposes and have no fixed format, I don't see
> any particularly compelling reason to change it in a patch level.
>
> Regards
>
> Blair
>
>

"Carsten Haerle" <[hidden email]> wrote in message
news:411e0320$0$24819$[hidden email]...
Well strictly speaking it is not violating any Microsoft guidelines is it,
at least not any that you or we are aware of.

>....so I suspect these
> programmers simply confused the resource compiler syntax with the usual
> string syntax.

I think it more likely that they just accepted the default which Microsoft
Visual C++ 6.0 creates for a new project. A reasonable thing to do given
that it was Microsoft's premier development environment for nearly 5 years.
Or possibly they got fed up with changing it to dots (if indeed they thought
there was any reason to do so) because VC++ 6 will only automatically update
the string version numbers to match the numeric ones if the string version
number is comma separated. Actually with this in mind I'm surprised that
quite so many version resources do use dots.

Well, I agree, I just think it is a minor cosmetic issue that is not of
sufficient importance to change in a patch level. There is after all no
actual published standard, and it only relates to a display-only text field
that often contains free format additional text, so any tool that read
version numbers (such as an installer) would have to use the numeric version
numbers anyway.

> BTW: Originally this problem was reported by a customer to me and then I
> started the investigation why almost all DLLs and EXEs use dots and only
> my
> Dolphin generated programs had commas in it.

If we define a cosmetic issue as something which adversely affects the user
experience (usually the visual experience) without impairing functionality,
then the format of the string version numbers might just about count,
although even there its arguable since one is free to define ones own format
for the string version numbers anyway. Sounds like good news for you and
your customer that he/she is down at the level of reporting issues that are
only of very minor cosmetic effect :-).

Regards

Blair