Changes between Initial Version and Version 1 of Documentation/Reference


Ignore:
Timestamp:
Oct 6, 2013 9:11:25 PM (11 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\\