TwittAmiga

     OVERVIEW
     ********

twittAmiga started as a Twitter client. As Twitter changed its API to
something not usable anymore, it is now a client for Bluesky with many
features:

 * Account data stored without password
 * Preview of linked images
 * Send new posts
 * Load list of mentions
 * Show user information and related posts
 * Search function (users and posts)
 * Follow / Unfollow
 * Repost
 * Avatars and image previews
 * MUI interface
 * URLs opened in browser (via OpenURL.library or via native URL:)
 * Links of a post shown as clickable icons below its text

twittAmiga uses libcurl, AmiSSL and others (see license folder for
copyright information), therefore the executable is quite large. You should
have at least 6 MB RAM.

The archive contains several executables optimized for different CPUs:

 * twittAmiga-AmigaOS:     68020/68030 without FPU and higher (default)
 * twittAmiga-AmigaOS-020: 68020/68030 with FPU (68881/68882)
 * twittAmiga-AmigaOS-040: 68040 with FPU
 * twittAmiga-AmigaOS-060: 68060 with FPU
 * twittAmiga-AmigaOS4:    AmigaOS 4.1 (PowerPC)

The icon starts twittAmiga-AmigaOS, the most compatible version. To use an
optimized version, delete or rename twittAmiga-AmigaOS and rename the one
matching your CPU to twittAmiga-AmigaOS.

There is currently no MorphOS version.


     LOGIN
     *****

twittAmiga logs in with your Bluesky user name and an app password. Do not
use your normal Bluesky password. To create an app password, open Bluesky
(website or app) and go to Settings -> Privacy and security -> App
passwords. Add a new app password, e.g. named "twittAmiga", and copy it.
Use your full username, e.g. user.bsky.social, without ().

The password is used only once to log in. twittAmiga then stores the
received session keys in the file keys.dat in the twittAmiga directory, the
password itself is not stored anywhere. If you no longer want twittAmiga 
to access your account, delete its app password in the Bluesky settings.

twittAmiga works with one account at a time. To use another account, rename
or delete keys.dat and restart twittAmiga, it will then ask for the login
data of the new account. If you keep one renamed keys.dat per account (e.g.
keys.dat.alice), you can switch between accounts by renaming the desired
file to keys.dat, without entering the password again.


     USAGE
     *****

The GUI should be self-explanatory for Bluesky users. However, here a short
description of the buttons in the toolbar:

 * Send: Sends a new post (enter text into text editor above).
 * Mentions: Shows posts mentioning you.
 * Home: Goes to the first page of the home timeline.
 * Pred: Loads the previous page of the timeline.
 * Next: Loads the next page of the timeline.
 * Reload: Reloads the current page.
 * Posts: Searches for posts with the string entered in the text editor above.
 * User: Searches for users containing the string entered in the text editor
         above.

You can repost by clicking the double arrow icon on the left side of the post.
By clicking the question mark icon of a user you can see detailed information
about this user. You can also follow/unfollow by clicking the corresponding
icon above the post.

Bluesky does not show links within the text of a post. Instead, every link of
a post is shown as a chain icon below its text. Move the mouse over the icon to
see the URL, click it to open the link in the browser.

The configuration is done via tooltypes of the twittAmiga icon. These are:

 * ACCOUNT: Your user name that you use for login. Can be empty.
 * TWEETS_PER_PAGE: The number of posts that are shown on one page.
 * THEME: The name of the theme for the timeline. This is the name of a
          directory within the twittAmiga directory. To use the default
          background type default.
 * CACHE: Path to a dir to store caching files. An / or : must be appended.
          Downloaded images are also stored here.
 * VIEWER: Name of executable (including path and options) to view images
 * FAST_IMAGE: Method used to decode and shrink thumbnails and avatars:
          fast      - reduced IDCT decoding, integer only (default). Much
                      faster on real Amigas, especially without FPU, but
                      produces slightly softer images. Scaled images are
                      stored as 24 bit IFF ILBM.
          slow      - old full-resolution decoding (also no/0/off/false).
                      Sharper but slower.
          datatypes - decode and scale using the installed picture
                      datatypes (needs datatypes.library V44, OS 3.5+).
                      Scaled images are stored as 24 bit IFF ILBM.
                      Normally slower, but this can make sense in case you
                      have very special DataTypes for PowerPC or Vampire.
          With the debug argument, every processed image is logged with
          an "ImageBenchmark" line to compare the methods.

     FAQ
     ***
Question: It can't login or login fails, what can I do?
Solution: (1) Make sure you use an app password (see LOGIN above), not your
              normal Bluesky password. You can use your e-mail address or
              your handle for login. If you use your handle do not enter
              the leading ().
          (2) If you are not asked for name and password try to delete
              keys.dat which is located in the folder where you have stored
              twittAmiga.
          (3) Check that AmiSSL is installed in the required version
              (>= 4.9 on AmigaOS 3, >= 5 on AmigaOS 4) and that your system
              time is correct.

Question: It does not start and does not show anything. What is happening?
Solution: Maybe there are missing libraries. Check the list above carefully.
          Sometimes also the MUI classes have dependencies that are not met.
          To check this, go to the settings page of this class and see if
          it works correctly. Also, see below for "I have problem XYZ."

Question: twittAmiga crashes when I push any button, is there a bug?
Solution: If you use one of the FPU versions on a CPU without FPU, use
          twittAmiga-AmigaOS instead, which does not need an FPU. If this
          does not solve the problem please continue to the next question.

Question: I have problem XYZ. How can I solve it?
Solution: Try to start twittAmiga from a shell by typing:

          stack 102400
          twittamiga debug

          You will see a long log of everything what is happening. Maybe
          there are error messages that can help you.

Question: twittAmiga loads the content very slowly. What can I do?
Solution: Most of the time is usually spent on downloading, decoding and
          scaling the avatars and image previews. You can try:
          (1) Set the tooltype FAST_IMAGE=fast (default). It is much faster
              than slow, especially on Amigas without FPU.
          (2) Use the executable optimized for your CPU (see OVERVIEW).
          (3) Reduce TWEETS_PER_PAGE, so fewer posts and images are loaded
              per page.
          (4) Set CACHE to a directory on your hard disk instead of T:.
              Downloaded and scaled images are stored there and are then
              still available after a reboot.
          With the debug argument, an "ImageBenchmark" line is logged for
          every processed image, which shows how long it took.
          Please note that this version may be noticeably slower than
          earlier versions of twittAmiga. Even the images Bluesky calls
          "thumbnails" are larger than the screen resolution of most
          Amigas (often 1000 pixels wide and more), and full size images
          are even several megapixels. Therefore every image has to be
          decoded and scaled down on the Amiga, which takes time. The
          status bar shows "Loading image..." while an image is
          downloaded and "Scaling image..." while it is scaled.

Question: Where can I get news and help?
Solution: Search the web for forum threads.

Question: The icons look crappy, what can I do?
Solution: Try another PNG datatype. The toolbar icons are displayed using
          datatypes.

Question: My window does not fit onto screen, what can I do?
Solution: You can configure the MUI for this window. Select "TheBar"
          and choose to view images only.


         CHANGELOG
         *********
         
Please note that I allow distribution in software bundles, on media or on
download sites. However, I personally only upload to Aminet and thus other
sources may contain old versions. Make sure to check Aminet for the newest
version.

5.0
Twitter changed its API to something not usable anymore, therefore
twittAmiga is now a Bluesky client. MorphOS is not supported in this
version.

Features:
- Bluesky support: login with app password, home timeline, mentions,
  sending posts, reposts, follow/unfollow, search for posts and users.
- Links of a post are shown as chain icons below the text. The bubble help
  shows the URL, a click opens it in the browser.
- New executables for 68020 without FPU (default), 68020 with FPU, 68040
  and 68060.
- New tooltype FAST_IMAGE for faster decoding and scaling of images.
- Full size images are scaled down to the screen size before they are
  shown in the viewer, so the viewer does not have to load images with
  several megapixels. The scaled image is stored next to the original one
  in the CACHE folder.
- Status bar shows separately whether an image is loaded or scaled.
- AmigaOS 4: now uses AmiSSL 5 and libcurl 8.10.1.
- AmigaOS 3: requires AmiSSL 4.9 or newer.

4.4.2
Due to changes in Twitter API a test of the connection is not possible
anymore. The check is removed and Amiga OS 3, 4 and MorphOS versions
are now at 4.4.2.

4.4.1
Fixes:
- Minimum requirement of MUI corrected

4.4
This update is for AmigaOS 3 only as it only updates (besides some minor 
fixes) the used libs. Amiga OS 4 and MorphOS versions are still 4.3.

Features:
- Replaces libcurl with 7.74 (OS 3)
- Now uses AmiSSL 4.6 (OS 3)
Fixes:
- Minor fixes in usage of string buffers.

4.3
Many thanks to the donator who made the intensive work on the AmigaOS 4.1 FE
version possible.

Features:
- On OS 4.1 the native command OpenURL is used to open web browser
  instead of the separately installed library.
- OS 4.1 uses different charset, while OS 3.x always uses something similar
  to ISO-8859-1. On OS 4.1 thus the current charset is selected. 
- Retweets are now marked as <User> retweeted <User>
- Click on image preview loads image in full resolution and views it
  using the configured viewer. Image can be found in CACHE folder.
- Viewing all images provided in a single tweet.
- Showing who is retweeting and who is retweeted
Fixes:
- Tweets with many returns exceeded text gadget height,
  now height increased for every return in tweet
- HTML entities now converted to unicode
- You cannot add yourself to followers
- OS 4.1: Disabling a TheBar button seems to crash if mouse is over bar, now
          using sleep flag.
- Twitter API change, passwords must now be URL escaped before encryption
- Possible crash on exit fixed
- URL encoding of searches was wrong. Entered text with special 
  characters like # or % led to errors after pressing "Search" or "Send"  

4.2.2
Bugfix release with following changes:
- Fix in error handling, missing MUI classes error message
- Loading of thumbnails instead of small size as the latter
  increased (change in Twitter API) and is maybe still small 
  for a mobile phone but not for a classic Amiga. 
- Additionally layout changed to view it.
- Another Twitter API change to more characters per tweet 
  but must be loaded differently.
- Map removed as Google changed API completely and now requires
  an API key. Too much work for this small feature.
- Window width can be changed again.

4.2.1
- Amiga OS 3 version is back (without ixemul)
- Linked against OpenSSL 1.0.0a and libcurl 7.46.0
- Fix in GUI viewing tweets and small OS 3 specific code changes

4.2
- Deactivated SSL certificate check as sometimes this check fails
  when sending a tweet.
- Fixed version string.
- Pointing to MorphOS preferences instead of OpenURL settings.
- Fix in button press handling if no timeline was loaded before.
  
4.1
- Twitter now requires cookie for retrieving PIN. Cookie will be only
  used for this and never saved anywhere.
- Dialog for asking username and/or password if ACCOUNT and/or PASSWORD
  is empty in the tooltypes. Dialog only displayed once for retrieving
  PIN and is usually not needed afterwards.
- Password cannot be stored anymore.
- ACCOUNT tooltype selects the default user that is loaded on startup.
  Additionally, it is now optional. If it is not set, the first user in
  list is used.
- Dialog for switching user accounts.
- Currently no update for OS 3.x as libcurl is too old for this OS.
 
4.0
- Native AmigaOS 4 version
- Fix in translating time to current time zone
- Removed HTMLView (due to too many bugs)
- Added native view for tweets
- Fix in "View Map" menu
- URLs now opened via openurl.library

3.0
- Added map view
- Added search on map
- Added caching for maps and city search
- Added menu strip 
- Fixed many memory issues related to MUI
- Fixed progress bar
- Bug fix: Sent tweets are now converted to correct character encoding
- Bug fix: Multiple links in one tweet now handled correctly
- Bug fix: Links are now correct even if tweet contains unicode characters
         
2.1
- Bug fix: last references to xml2.library removed
- Bug fix: Retweet working again.

2.0
- Partially rewritten for new twitter API 1.1
- Uses now JSON instead of XML
- HTTPS instead of HTTP  
- Native MorphOS version
         
1.49
- Bugfix in search function
- Error messages fixed
- Icons now better for plain AOS 3
- Search for user added

1.47
- Search
- Follow/unfollow
- User timeline
- Mentions
- Bugfixes in time handling
         
1.35
- Changed from libxml2 to xml2.library, no more ixemul!
- Less RAM needed
- Debug output optional