Changing the documentation to account for longstanding bugs

The documentation says picture.saveasgif and picture.saveastiff are cross-platform. If you run Picture.IsExportFormatSupported(Picture.FormatGIF) or Picture.IsExportFormatSupported(Picture.FormatTIFF) on OS X they both return true.

However, for about 2 years (at least) if you try and use picture.saveasgif or picture.saveastiff, you get an unsupported format exception on OS X. (<https://xojo.com/issue/20726>)

The documentation is wrong. IsExportFormatSupported is wrong. Granted, it is wrong due to a bug that will be fixed (I think? I hope?) but at what point do you just change things to reflect how things are rather than what you wish them to be?

Submit a Feedback report via the Feedback application. Paul is very good about updating documentation.

Sometimes its a bug that it doesn’t work
Sometimes the docs are outright wrong

So its on a case by case basis what needs to be done
Sometimes its fix the bug
Sometimes its update the docs

The problem is compounded by the fact that Picture.IsExportFormatSupported(Picture.FormatGIF) or Picture.IsExportFormatSupported(Picture.FormatTIFF) return True, leading one to believe it is indeed possible to save in these formats.

So notwithstanding the possible issue about the documentation being wrong, the fact that IsExportFormatSupported and SaveAs don’t agree look like a very real bug that should be fixed. Either by having IsExportFormatSupported report False, or by making SaveAsGIF and SaveAsTIFF work.

For the time being I’ve moved SaveAsGIF and SaveAsTIFF to a new “Platform-Specific Formats” section with a note to always check for an UnsupportedFormatException.

SaveAsMacintoshPICT doesn’t work either. Same problem.
Looking back, I tested this back in the summer of 2012 and I never got either PICT, TIFF or GIF to work, according to my notes (I also have some test code left). I just figured I did something wrong, was missing something needed to pass the data, felt stupid and gave up. My mistake was trusting the LR.

It would be a good idea to connect the feedback system to the reference in some way, so when the user is struggling to get things working it would be easy to see if there might be issues already reported that may not be caused by him/her… I don’t know how many hours I wasted on this one alone…
I think, especially, when a bug is confirmed, there could be a little link placed beside the property/Method/costructors telling the user that there might be an issue, linking to the Feedback system or a short description.
In this case, when SaveAsGIF was confirmed not working (at the same time as it was confirmed), why not just mark it as possibly broken. After all it was confirmed and had been broken for years.
It could mean minutes wasted instead of hours. -And a much happier customer.

[quote=161521:@Roger Jönsson]SaveAsMacintoshPICT doesn’t work either. Same problem.
Looking back, I tested this back in the summer of 2012 and I never got either PICT, TIFF or GIF to work, according to my notes (I also have some test code left). I just figured I did something wrong, was missing something needed to pass the data, felt stupid and gave up. My mistake was trusting the LR.
[/quote]

Pict has been deprecated by Apple a while ago. But as you can see, Paul Lefebvre who is in charge of the documentation has been pretty diligent to update the LR following your posts.

Yes, that is good, but something like that should have happened at the same time as the issue/bug was confirmed.

Confirming a bug could/should raise a flag somewhere which would/could lead to an update of the LR without a long delay. So when a bug is confirmed → update the LR, without users needing to report it again. After all the bug was already reported and confirmed…

Also it should not have to take + two years to have a bug like this one confirmed. It is quick and easy to test and especially in this case it should have been easy to confirm broken, as it seems to be solid = just plain dead (after a certain version OS X? from 10.7 and on? -I probably ran 10.7.x back in 2012 when I at the first attempts could not make SaveAsGIF/TIFF work).

Actually, I just verified SaveAsGIF already was not supported back in RS 2011. I did not try in an older one, since 2011 4.3 is the oldest I keep on my disk. So it never, ever worked in Xojo. You are right, it is downright ridiculous this has not been made public before. I also wonder why the have kept the non working function in for so long. If they do not intend to fix it, the simplest course of action would it not be to simply remove it ?

The documentation thing is yet another story. When you file a bug report, it is processed by the guys in charge of the development who will see if they can fix the issue. But they are not in charge of the documentation. You have to file a specific feedback report signaling the bug in documentation to bring it to the attention of our excellent Paul Lefebvre, who generally takes care of that right away. As he did here, answering efficiently your thread call.

Yes, but what I meant was, when a solid bug (like this one) is confirmed the guys confirming it raise a flag somewhere and the one(s) responsible for the documentation gets to know that its time to update the documentation (LR). Bug confirmed -> flag -> update of the LR. Bug fixed -> flag -> update of the LR. Simple and efficient.
I think the user did his job by reporting the bug. There should be no need to report again that the LR was not updated when the bug was confirmed.

[quote=161578:@Roger Jönsson]Yes, but what I meant was, when a solid bug (like this one) is confirmed the guys confirming it raise a flag somewhere and the one(s) responsible for the documentation gets to know that its time to update the documentation (LR). Bug confirmed -> flag -> update of the LR. Bug fixed -> flag -> update of the LR. Simple and efficient.
I think the user did his job by reporting the bug. There should be no need to report again that the LR was not updated when the bug was confirmed.[/quote]

Maybe you should file a feedback report in the miscellaneous section with your suggestion to have a chance to see it taken into account.

It appears that the constant for SaveAsMacintoshPICT is wrong. It should be 200, not 100. Manually using 200 seems to work and I’ve added this note to the docs. But Apple deprecated PICT some time ago, so it might not be good to rely on it. <https://xojo.com/issue/16859>

If you want to save as GIF or TIFF on OSX… it requires the SIPS utility (included as part of OSX)

here are the basic steps… I will leave it to you to figure out the details (this code was cut from an existing project of mine)

    //
    // Save Picture in GIF or TIFF format using SIPS command
    //
    // 1. save image as png file in temp directory
    temp_file=SpecialFolder.Temporary.child("temp.png")
    If temp_file.Exists Then temp_file.Delete
    // 2. use sips to convert from PNG to GIF and move to desired directory
    //pic_stack(current_picture).Save temp_file,Format
    work_area.save temp_file,Format
    'temp_file.SaveAsPicture pic_stack(Current_Picture),format
    app.DoEvents
    s="sips -s format "+sips_format+" "+temp_file.shellpath+" --out "+xfile.shellPath
    
    //
    sh.Mode = 0
    sh.Execute s
    app.DoEvents
    If InStr(sh.Result,"command not found")>0 Then 
      Beep
      myMsgBox "SIPS Not Found^The Image Conversion utility 'SIPS'^was not located on this computer.^^This is required for GIF and TIFF file^formats.",16
    End If
    If temp_file.Exists Then temp_file.Delete
    
    
    //sips -s format gif /Path/To/Icon.icns --out /Path/To/ConvertedImage.gif
    // 3. delete temp file

sips format should be “gif” or “tiff” in lowercase

The docs are intended to describe how things work. If something doesn’t work as documented, then that may be a bug. Or it may be the docs have become out-of-date. Either way, a Feedback case is appropriate.

If you really feel that there is something in the docs that should be updated to reflect a bug (or anything else for that matter), then you should also file a Feedback case on the docs. I’m not sure I’ll always agree that the bug should be noted in the docs since the docs are not meant for tracking bugs, but there may be valid special cases such as these Picture ones (which primarily seem to be an artifact of the switch from Carbon to Cocoa).

Getting stuff in Feedback is important (even doc stuff). Even though I try to stay on top of the forum, I’m sure there are many posts I miss. However, I do see every Feedback case in the Documentation category.

[quote=161568:@Roger Jönsson]Yes, that is good, but something like that should have happened at the same time as the issue/bug was confirmed.

Confirming a bug could/should raise a flag somewhere which would/could lead to an update of the LR without a long delay. So when a bug is confirmed --> update the LR, without users needing to report it again. After all the bug was already reported and confirmed…

Also it should not have to take + two years to have a bug like this one confirmed. It is quick and easy to test and especially in this case it should have been easy to confirm broken, as it seems to be solid = just plain dead (after a certain version OS X? from 10.7 and on? -I probably ran 10.7.x back in 2012 when I at the first attempts could not make SaveAsGIF/TIFF work).[/quote]
This would certainly help the users out when you can tell at a glance that there may be some functionality issues despite what the LR says. Would certainly save time navigating Feedback’s…interesting…user interface and hoping you’ve used the right search terms. Would probably help cut down on duplicate bug reports, too.

[quote=161688:@Paul Lefebvre]The docs are intended to describe how things work. If something doesn’t work as documented, then that may be a bug. Or it may be the docs have become out-of-date. Either way, a Feedback case is appropriate.

If you really feel that there is something in the docs that should be updated to reflect a bug (or anything else for that matter), then you should also file a Feedback case on the docs. I’m not sure I’ll always agree that the bug should be noted in the docs since the docs are not meant for tracking bugs, but there may be valid special cases such as these Picture ones (which primarily seem to be an artifact of the switch from Carbon to Cocoa).
[/quote]
Exactly. The bug may cause the Reference to not describe how things work. That is exactly my point.
When the bug is confirmed, then one confirming it raises a flag somewhere (Could be different flags depending on severity and how solid the bug is) and the one who fixes the docs sees the flag that may say that something is completely broken and will not be fixed in jiffy and the docs editor decides from that. It would make things easier for everybody.

I as a user can not know that the reference is not correct until I maybe have spending hours fiddling with the code, failing or even giving up. Yes with the help from the forum, this one was caught in a few days, after more testing the suggestions presented, which did not work because the suggestions were based on the reference being correct. After all this wasted time and then finding the bug ( that was already confirmed), one would be ready to send a feed back.

I gave up on the SaveAsGIF/TIFF 2.5 years ago, because I didn’t understand that it was not I who did wrong. How many others have done the same in similar cases…?
A reference is a reference and it should be correct as far as possible.

I think it would be helpful to all with an internal flag system. I am not saying all bugs would have to be written into the reference, but when something is confirmed to not work, then it would be sensible if the confirmation would lead to changes in the reference (without further user interaction), so that it is correct and does not mislead. The one who confirmed the bug is probably much better deciding when something works or does not, than the user who only have a limited picture of things.

Please think about my suggestion.

37872 - SaveAsGIG/SaveAsTIFF is not available the same way on all platforms

OS: Windows 8

Xojo: 2014R3.2 and before

Kind of bug : Documentation

Steps: After the thread about SaveAsGif and SaveAsTiff not working on Mac, there was a bug report, and Robin gave us what was needed to make the documentation a lot better :

Because OS X is not the only O/S in the universe! :slight_smile:
SaveAsGIF and SaveAsTIFF works on Windows.
SaveAsTIFF works with Linux (Mint17), but SaveAsGIF does not.

Would it not be a good idea to do something like :

Some valid formats are:
Picture.SaveAsDefault
Picture.SaveAsDefaultRaster
Picture.SaveAsDefaultVector
Picture.SaveAsGIF supported only on Windows
Picture.SaveAsJPEG
Picture.SaveAsPNG
Picture.SaveAsTIFF supported only on Windows and Linux
Picture.SaveAsWindowsBMP
Picture.SaveAsWindowsEMF
Picture.SaveAsWindowsWMF

<https://xojo.com/issue/37872>