Changes between Initial Version and Version 1 of Documentation/Reference


Ignore:
Timestamp:
Oct 6, 2013, 9:11:25 PM (14 months ago)
Author:
AmigaPhil
Comment:

1st edit - Link fixes coming next

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/Reference

    v1 v1  
     1[[TranslatedPages]]\\[[TOC]]
     2
     3= Reference =
     4
     5== Install structure ==
     6
     7In the program directory for YAM the following files and directories will be found:
     8
     9
     10 * '''YAM'''               The program itself
     11 * '''YAM.info'''          The program icon
     12
     13 * '''Resources/'''
     14   * '''Themes/'''            [[#FixTheme| Themes ]] used by YAM along its Graphical User Interface
     15   * '''Gallery/'''               Pictures of people mentioned in the address book
     16   * '''Certificates/'''
     17   * '''Spamfilters/'''
     18
     19 * '''Rexx/'''             ARexx programs for YAM
     20
     21 * '''.config'''           the [[co_w| configuration ]] file
     22 * '''.folders'''          a list of the [[ma00| folders ]]
     23 * '''.addressbook'''      the [[ab_w| address book ]]
     24 * '''.glossary'''         the [[di_w| glossary ]]
     25 * '''.users'''            a list of the [[us_w| YAM users ]]
     26 * '''.spamdata'''         YAM's spam training data
     27 * '''.updatestate'''      information for the auto update mechanism
     28 * '''.signature'''        your personal [[co07| signature ]]
     29 * '''.altsignature1'''    first alternative signature
     30 * '''.altsignature2'''    second alternative signature
     31 * '''.taglines'''         your collection of [[co07| taglines ]]
     32 * '''.autosave?.txt'''    [[co_h| backup copies ]] of the editor contents
     33 * '''.uidl'''             used to [[co02| avoid duplicates ]]
     34 * '''.emailcache'''       cache file used by the [[co05| email cache ]] feature
     35 * '''YAM.log'''           log file (if the [[co09| log feature ]] has been set)
     36
     37 * '''incoming/'''         the incoming mailbox directory
     38 * '''outgoing/'''         the outgoing mailbox directory
     39 * '''sent/'''             the directory for sent mail
     40 * '''trash/'''          the directory for mail marked for deletion
     41
     42
     43== Message storage ==
     44
     45
     46Each message is saved as a separate file of which the filename is constructed
     47by encoding certain information about the mail (date, status, etc) using the Base64
     48standard encoding. The resulting name is compatible to any filesystem.
     49
     50Example: QvZgMAAFe4M=.001,RA
     51
     52   `QvZgMAAFe4M=`      Base64 encoded 5 bytes hash.
     53                                    This hash is based on the DATE info from the message.
     54
     55   `.` (dot)                       - Separator.
     56
     57   `001`                           Sequential value.  Incremented by 1 if the base filename, including this part, already exists.
     58
     59   `,` (comma)                - Separator.
     60
     61   `RA`                             Status of the message.  Possible letters after the comma:
     62                                    R - Read\\
     63                                    A - Answered\\
     64                                    M - Marked\\
     65                                    Y - \\
     66                                    J - \\
     67
     68
     69Every folder contains an '''.index''' file with the headers of every message
     70in the directory. There is also a configuration file called '''.fconfig''' which
     71holds the settings for that particular folder.
     72
     73[[=#FixTheme]]
     74== Theme handling ==
     75
     76YAM will use the icons and pictures in /Themes/default along its
     77Graphical User Interface.  There are several kinds of icons:
     78
     79
     80'''config/config_#?, config_#?_big'''
     81     These images are what you see when you open Settings to
     82     configure YAM.
     83
     84
     85'''folder/folder_#?, folder_#?_new'''
     86     These are the images used in front of the basic Incoming, Deleted,
     87     Outgoing and Sent folders.  Those with the "_new" suffix are used
     88     automatically whenever there is new or unread mail in the folder.
     89
     90     The "folder_fold" and "folder_unfold" images are special: they are
     91     used as the icon for folder groups.
     92
     93     A ".fimage" picture file in a folder overrides the default image.
     94     This is also the only method supported to have images displayed
     95     in front of custom folders.
     96
     97
     98'''icon/check.info, empty.info, new.info, old.info'''
     99     Icons which show the status of the "Incoming" mailbox:
     100
     101     check.info     YAM is checking for new mail\\
     102     empty.info     the mailbox is empty\\
     103     new.info       the mailbox has at least one new message\\
     104     old.info       the mailbox only holds "old" mail\\
     105
     106
     107'''status/status_#?'''
     108     These are the [[ma0s| status icons ]] displayed by YAM to show the status
     109     of the messages.
     110
     111     The "status_mark" icon used when messages are set to "marked"
     112     is special: if it is not present, YAM will mark the messages by
     113     displaying the sender/recipient data in bold letters.
     114
     115
     116'''toolbar/tb_#?, tb_#?_G, tb_#?_S'''
     117     These are the images used to build the toolbars in the Main, Read,
     118     Write and Address book windows.  Those named "tb_#?_G" are the
     119     "ghosted" variety, i.e. they provide the images to be used when the
     120     icons must look ghosted.
     121     "tb_#?_S" are the "selected" variety, i.e. when you press a button.
     122
     123
     124'''.theme, logo, preview'''
     125     .theme contains various important text variables that are needed
     126     for the theme engine to work.
     127
     128     The "logo" is what you see when you start and quit YAM and also
     129     in the "about" window in YAM. (Note: only the default logo is
     130     displayed, no matter what theme you have selected.)
     131
     132     The "preview" is a small preview that shows what that icon theme
     133     looks like in Settings/Look & Feel.
     134
     135
     136== Misc file formats ==
     137
     138=== The .addressbook file ===
     139
     140This plain text file uses a hierarchical scheme following this general format:
     141
     142{{{
     143    YAB4 - YAM Addressbook                          - Identifier
     144    @GROUP alias  ·································
     145    description                                   ·
     146    @USER alias     -------------.                ·
     147    e-mail address               |                ·
     148    real name                    |                ·
     149    description                  |                ·
     150    phone #                      |                ·
     151    street address               |                ·
     152    ZIP/City                      > Person        ·
     153    country                      |                ·
     154    PGP ID                       |                ·
     155    birth date                   |                ·
     156    portrait                     |                 · GROUP
     157    homepage                     |                ·
     158    default security             |                ·
     159    @ENDUSER        -------------'                ·
     160    @LIST alias     >>>>>>>>>>>>>>>>>>>>>>>>>>                 ·
     161    return address               v                ·
     162    list name                    v                ·
     163    description                  v                ·
     164    member #1                     >> LIST          ·
     165    member #2                    ^                ·
     166    ...                          ^                ·
     167    member #n                    ^                ·
     168                                 ^                ·
     169    @ENDLIST        >>>>>>>>>>>>>>>>>>>>>>>>>>                 ·
     170    @ENDGROUP     ·································
     171}}}
     172
     173Groups, lists and people are started with @GROUP <alias>, @LIST <alias>
     174and @USER <alias> and closed with @ENDGROUP, @ENDLIST and @ENDUSER,
     175respectively.  Groups may include lists, and lists may include members.
     176Both lists and people may appear outside groups.  List members may be
     177either aliases, addresses or fully qualified "Real name <address>" pairs.
     178
     179GUI-wise, a group may be dragged&dropped onto a distribution list and
     180viceversa to get all its recipients added to the list.  Recursive loops
     181are watched and promptly avoided when appropriate - for instance, if a
     182group contanining a list is dragged&dropped on that list, only the items
     183available in the group other than the contents of the list itself are
     184added to it.
     185
     186=== The .emailcache file ===
     187
     188This plain text file contains a list of the last n used recipients
     189who were not in the address book, in the format "Name <address>" (or
     190just "<address>" if the name is not available) with one entry per line.
     191
     192New entries get added at the top.  If the limit of entries set in the
     193configuration is exceeded, the oldest entry (i.e. the one at the bottom)
     194is dropped.
     195
     196If it is already in the cache when writing the mail, the entry is
     197moved to the top -- this way, the next time, the most recently used
     198recipient will be suggested first.  Entries in the address book will
     199still have priority over the cache, though.
     200
     201=== The .fconfig file ===
     202
     203This plain text file exists in every folder and stores the settings
     204used therein, using this format:
     205
     206
     207    YFC1 - YAM Folder Configuration\\
     208    Name        = folder_name\\
     209    MaxAge      = age\\
     210    Password    = password\\
     211    Type        = folder_type\\
     212    XPKType     = type_number\\
     213    Sort1       = primary_sort\\
     214    Sort2       = secondary_sort\\
     215    Stats       = Y|N\\
     216    MLSupport   = Y|N\\
     217    MLFromAddr  = MLFrom_address\\
     218    MLRepToAddr = MLRepTo_address\\
     219    MLPattern   = ML_pattern\\
     220    MLAddress   = ML_address\\
     221    MLSignature = signature_number\\
     222
     223
     224where
     225
     226   - '''Name''' is the name of the folder, as it appears in the folder list
     227
     228   - '''MaxAge''' is the number of days the messages in the folder will be kept before removing them automatically, where 0 disables this feature (see [[co10| Configuration/Start/Quit ]])
     229
     230   - '''Password''' is the encoded counterpart of the password used to protect this folder, if any
     231
     232   - '''Type''' is a number indicating which type this folder is (should be usually 0 for user folders - see the documentation for the [[rx_folderinfo| FOLDERINFO ]] command)
     233
     234   - '''XPKType''' refers to the XPK mode used in the folder:
     235
     236        0 = none\\
     237        1 = simple protection (password)\\
     238        2 = compressed\\
     239        3 = compressed with password\\
     240
     241   - '''Sort1''' refers to the primary sort criterion used in the folder, in negative form if the sort is reversed:
     242
     243        1 = Message date\\
     244        2 = Date received\\
     245        3 = Sender\\
     246        4 = Recipient\\
     247        5 = Subject\\
     248        6 = Size\\
     249        7 = Status\\
     250
     251   - '''Sort2''' is just the same as Sort1, but referred to the secondary sort criterion
     252
     253   - '''Stats''' may be either Y or N depending on the status of the "AppIcon stats" flag
     254
     255   - '''MLSupport''' may be either Y or N depending on the status of the "Mailing list support" flag
     256
     257   - '''MLFromAddr''' shows the contents of the "From: address" field
     258
     259   - '''MLRepToAddr''' shows the contents of the "Reply-To: address" field
     260
     261   - '''MLPattern''' shows the contents of the "To: pattern" field
     262
     263   - '''MLAddress''' shows the contents of the "To: address" field
     264
     265   - '''MLSignature''' refers to the default signature to be used when posting messages to this mailing list:
     266
     267        0 = none\\
     268        1 = default signature, i.e. PROGDIR:.signature\\
     269        2 = alt. signature !#1\\
     270        3 = alt. signature !#2\\
     271
     272=== The .folders file ===
     273
     274This plain text file uses a hierarchical scheme following this general format:
     275
     276{{{
     277    YFO1 - YAM Folders                              - Identifier
     278    @FOLDER name    ------------------.
     279    directory                          > Folder
     280    @ENDFOLDER      ------------------'
     281    @GROUP name              ································
     282    status                                                  ·
     283    @FOLDER name    ------------------.                     ·
     284    directory                          > Folder             ·
     285    @ENDFOLDER      ------------------'                     ·
     286    @GROUP name              ······················         ·
     287    status                                        ·         ·
     288    @FOLDER name    ------------------.           ·          · GROUP
     289    directory                          > Folder   ·         ·
     290    @ENDFOLDER      ------------------'            · GROUP  ·
     291    @FOLDER name    ------------------.           ·         ·
     292    directory                          > Folder   ·         ·
     293    @ENDFOLDER      ------------------'           ·         ·
     294    @ENDGROUP                ······················         ·
     295    @ENDGROUP                ································
     296}}}
     297
     298where <status> may be either 0 or 1, the latter meaning that the
     299group is unfolded, e.g. its contents are being displayed.  Folders
     300may live both inside and outside groups, and groups may be nested.
     301
     302The order of the folder tree is saved on disk whenever the
     303[[mam2| Folder/Order/Save ]] menu item is called.
     304
     305=== The .glossary file ===
     306
     307This file contains a list of the definitions made in the [[di_w| glossary ]] using this format:
     308
     309
     310    YDI1 - YAM Dictionary\\
     311    @ENTRY abbreviation\\
     312    contents\\
     313    @ENDENTRY\\
     314    @ENTRY abbreviation\\
     315    contents\\
     316    @ENDENTRY\\
     317    ...\\
     318
     319=== The .uidl file ===
     320
     321If "Avoid duplicates" is enabled in [[co02| Configuration/New mail ]], YAM
     322will use the UIDL POP3 command when connecting to your POP3 server to
     323request an '''U'''nique '''ID''' '''L'''isting of the messages in your mail account.
     324The POP3 server is responsible for assigning an unique ID to every
     325message and put it into a "X-UIDL:" header.
     326
     327If the server doesn't support the UIDL POP3 command, YAM will fall
     328back to the TOP command and try using the "Message-ID:" header instead;
     329if this also fails, an error will be generated.
     330
     331The Unique ID Listing received from the server is compared against
     332the contents of the "PROGDIR:.uidl" file; if this file doesn't exist
     333yet, it will be created.  This is a plain text file with one ID per
     334line using the format <ID>@<POP3 server>, e.g.
     335
     336
     337    9685@mail.saug.org\\
     338    9686@mail.saug.org\\
     339    9687@mail.saug.org\\
     340    9688@mail.saug.org\\
     341    (k5"!N1!"!RkI"!YT4"!@pop.wanadoo.es\\
     342    9689@mail.saug.org\\
     343    9690@mail.saug.org\\
     344    9691@mail.saug.org\\
     345    9692@mail.saug.org\\
     346
     347
     348Whenever an ID is already found in the "PROGDIR:.uidl" file, the
     349relevant message will be considered a duplicate, and thus it won't be
     350downloaded.  New IDs not yet in the "PROGDIR:.uidl" file will be added
     351to it as the corresponding messages are successfully downloaded.
     352
     353=== The .users file ===
     354
     355This file contains a list of the users that can log in and use YAM.
     356YAM maintains this file by itself, so you shouldn't ever touch it,
     357unless maybe you are [[tip2| moving YAM ]] to another place in your hard disk.
     358
     359   The file uses the following format:
     360
     361
     362        1st line:   YUS2 - YAM Users\\
     363        2nd line:   @USER <username>\\
     364        3rd line:   mail directory of this user, e.g.  Comm:YAM\\
     365        4th line:   number\\
     366        5th line:   encrypted password, if any\\
     367        6th line:   @ENDUSER\\
     368   further lines:   next user definition, upto 16 maximum.\\
     369
     370
     371where "number" is a value defining the status of this user combining
     372the following set of elements:
     373
     374
     375        No Supervisor privileges  = 4\\
     376        Share global address book = 2\\
     377        Share global glossary     = 1\\
     378
     379
     380Thus, "3" would mean the user has Supervisor privileges and is sharing
     381the global address book and glossary.  This is the default value in a
     382single user setup.
     383
     384=== The log file ===
     385
     386The log file used by YAM is an ASCII file storing one event per line.
     387Each line is saved in this format:
     388
     389   DD-MMM-YY HH:MM [code] Event description
     390
     391where '''code''' is a two digit number and "Event description" is obviously
     392the event description, possibly localized.  Therefore, any computer-assisted
     393software meant to analyze the log file data should refer to the code of the
     394event.
     395
     396Events out of the 30<->49 range will only be printed if "Log all events"
     397is enabled in the [[co09| Security options ]].
     398
     399   List of possible events:
     400
     401
     402 0 - YAM started\\
     403 1 - Logged in as user 'user_name'\\
     404 2 - Logged in as 'user_name', using configuration 'config_file' and mail directory 'folder_path'\\
     40510 - Wrote new message for 'recipient' about 'subject', including n attachment(s)\\
     40611 - Replied message from 'sender' about 'subject'\\
     40712 - Forwarded message from 'sender' about 'subject' to 'recipient'\\
     40813 - Bounced message from 'sender' about 'subject' to 'recipient'\\
     40914 - Edited message from 'sender' to 'recipient' about 'subject'\\
     41020 - Deleted n message(s) in folder 'folder'\\
     41121 - Deleted message from 'sender' about 'subject' in folder 'folder'\\
     41222 - Moved n message(s) from folder 'folder' to 'folder'\\
     41323 - Moved message from 'sender' about 'subject' from folder 'folder' to 'folder'\\
     41424 - Copied n message(s) from folder 'folder' to 'folder'\\
     41525 - Copied message from 'sender' about 'subject' from folder 'folder' to 'folder'\\
     41626 - Filtered n message(s) in folder 'folder': n match(es)\\
     41730 - Retrieved n message(s) from POP3 account 'user_id@host'\\
     41831 - Logged in on POP3 account 'user_id@host': n messages waiting\\
     41932 - Retrieved message from 'sender' about 'subject' (n bytes)\\
     42040 - Sent n message(s) using SMTP server 'host'\\
     42141 - Connected to SMTP server 'host'\\
     42242 - Sent message to 'recipient' about 'subject' (n bytes)\\
     42350 - Imported n message(s) from file 'filename' into folder 'folder'\\
     42451 - Exported n message(s) from folder 'folder' to file 'filename'\\
     42560 - Saved configuration file 'config_file'\\
     42662 - Saved user configuration\\
     42770 - Saved address book 'filename'\\
     42871 - Added address book entry 'alias'\\
     42980 - Saved attachment 'filename' of message 'mailfile' in folder 'folder'\\
     43081 - Cropped attachment(s) of message 'mailfile' in folder 'folder'\\
     43182 - Changed subject 'subject' of message 'mailfile' in folder 'folder' to 'subject'\\
     43299 - YAM terminated\\