Backtalk File Formats

Version 1.1.14

© 2002: Jan Wolter, Steve Weiss

1. Introduction

This document describes some of the file formats used in Backtalk.

1. List of Conferences

The conflist file resides in the top level "bbs" directory. It is used to map typed names of conferences to the actual directory names. It allows you to have multiple names for the same conference, or to abbreviate the names of conferences. These features are mainly useful when people are typing in conference names, which isn't that common in most Backtalk interfaces - you more often select the conference from a list, and having alternate names for it isn't that useful there. However, it's a nice feature to have for command-line interfaces like Picospan and Fronttalk.

A typical conflist file might look like this:

    !<hl01>
    /usr/local/backtalk/bbs/general2
    gen_eral2:/usr/local/backtalk/bbs/general2
    general1:/usr/local/backtalk/bbs/general1
    oldgen_eral:/usr/local/backtalk/bbs/general1
    tes_t1:/usr/local/backtalk/bbs/test1
    mar_tian1:/usr/local/backtalk/bbs/martian1
    mars:/usr/local/backtalk/bbs/martian1
    bar_soom:/usr/local/backtalk/bbs/martian1
The first line is always ``!<hl01>''. This is a magic number identifying the file type and version.

The second line is the directory name of the default conference. This is rarely used in Backtalk's web interfaces, but it is in command-line interfaces.

The remaining lines each consist of a conference name, a colon, and a conference directory. Conference names usually have an underscore inserted in them somewhere. When a user types the name of a conference, he may abbreviate it by leaving off letters after the underscore. Thus, you could join version 2 of the general conference by typing ``gen,'' ``gene,'' ``gener,'' ``genera,'' ``general,'' or ``general2.'' To join version 1, you'd have to type ``general1'' however, because there is no underscore in the name so no abbreviations are allowed. Note that there can be more than one line for the same conference. Thus we can also go to version 1 of the general conference by using the name ``oldgen.''

If ``/usr/local/backtalk/bbs/'' is the default location for conference directories (this is set during the installation process), then you can abbreviate directory names by replacing that part of the path with a % sign. Thus, the following file would be equivalent to the one above:

    !<hl01>
    %general2
    gen_eral2:%general2
    general1:%general1
    oldgen_eral:%general1
    tes_t1:%test1
    mar_tian1:%martian1
    mars:%martian1
    bar_soom:%martian1
This format is recommended, since it is easier to maintain. It is not, however, understood by Yapp.

Lines may be commented out by starting them with a # sign.

2. Menu of Conferences

3. Conference Configuration File

4. Conference Summary File

5. Item File

6. Index File

7. Participation File

Participation files record information about a user's participation in a particular conferences. Traditionally this includes a record of which responses have been read, which items have been forgotten, and the user's alias in the conference. Backtalk will expand on this a bit.

7.1. Traditional Picospan Participation Files

Picospan participation files reside in the user's home directory, or, if it exists, a directory name .cfdir under the user's home directory. They are owned by the user. There is one file for each conference which the user has joined. The names of the files for the individual conferences are specified in the conference configuration files.

In most Unix-login configurations, Backtalk changes the group of the files to one it can read/write. In Backtalk-login and Yapp 3.0 compatible Unix-login configurations, the files are owned by the cfadm account.

7.1.1. Sample

    !<pr03>
    Jan Wolter
    1 76 3D1C5899
    2 8 3D1C5A80
    3 3 3D1C5A8A
    4 20 3D1C5B69
    5 18 3D1C5B80
    6 58 3D1C5BA3
    7 52 3D1C5CD8
    8 -9 3D1CEF3F
    9 -30 3D1CEF6A

7.1.2. Description

The first line identifies the file type. It is always !<pr03> in Picospan and Yapp.

The second line gives the user's alias in this conference.

The remaining lines describe items that the user has read. Each contains three columns.

The number of the last response read may be prefixed with a minus sign. This means that the item has been forgotten. Picospan recognizes "-0" as a distinct value from "0" - the former is an item that has never been read, but has been forgotten. The later is an un-read, un-forgotten item. Yapp does not understand "-0" and does not allow unread items to be forgotten.

The time of last reading is represented as a standard unix time value (the number of seconds since the begining of 1970), written in hexidecimal notation.

The time of last reading is used to distinguish between new and unseen items. An item has unseen responses if the number of responses in the item exceeds the last response read. An item has new responses if it is unseen AND the date of the last response in the item exceeds the date on which we last read responses.

7.2. Backtalk Participation Files

Backtalk likes to store some additional per-user/per-conference and per-user/per-item information that is not included in traditional Picospan Participation Files. So a more flexibly formatted file is used for Backtalk systems that do not need to be Picospan compatible.

These files are named the same as a Picospan file would have been, and are stored in the same locations, except that Backtalk accounts don't usually have .cfdir directories.

7.2.1. Sample

    !<pr10>
    alias=(Jan Wolter)
    pistacho.background=(C0FFE0)
    1
    r=(76)
    d=1025267865
    2
    r=(8)
    d=1025267352
    3
    r=(3)
    d=1025268362
    4
    r=(20)
    d=1025268585
    fav
    5
    r=(4-9,11,18)
    d=1025268608
    6
    r=(58)
    d=1025268643
    7
    r=(52)
    d=1025268952
    fav
    8
    r=(9)
    d=1025306431
    forgot
    9
    r=(30)
    d=1025306474
    forgot

7.2.2. Description

This is basically a series of tagfiles, separated by item numbers alone on a line. The tags defined before the first number apply to the entire conference. The tags after each number apply to only that item. Some tags have meaning to the Backtalk interpretor, others are only used by the interfaces. Ones that are specific to a particular interpretor usually have names like 'pistachio.background'.

In the conference-wide section, the 'alias' tag defines the user's name in the conferences.

In the per-item sections, the 'r' field is a selector describing all unread responses in the item. There is an implied '-$' at the end of each, so 'r=(9)' means we have not read responses 9-$. Currently these are always single digits, because, like Picospan, if we have read response 109, then we assume that we have read all that went before. But to support tree-style items, we need to remember exactly the set of responses which are still unread, so these will become more general selectors. If this is a single number (as it usually is), it can be written out as a number instead of a string, without the parentheses.

The d field is the date the item was last read. This is exactly like the date field in the traditional picospan participation file, except that it is written in decimal instead of hexadecimal.

Forgotten items are marked by a 'forgot' tag.

Extensions to the standard Picospan format include the 'fav' tag which is included if the item is one of the user's favorites, and the title flag which gives the user's personal title for the item.

7.3. Backtalk Participation Extension Files

When Yapp or Picospan compatibility is needed, we must maintain two files for each item the user reads. One is the standard Picospan participation file. The other is an extension file. We can't try to jam our extra information into the Picospan file, because Picospan and Yapp destructively rewrite the file every time you enter and leave the conference. Even if we could hide some extra information in there in such a way that they wouldn't choke on it, they probably wouldn't write it back out for us.

So we maintain our extra information in an extra file, called the participation extension file. It's name is the same as the participation file, but with an 'x' appended to the name.

7.3.1. Sample

    !<px01>
    pistacho.background=(C0FFE0)
    4
    fav
    5
    r=(4-9,11,18)
    7
    fav

7.3.2. Description

This files format is just like a Backtalk participation file, except that it starts with a !<px01> line and it includes only fields that have information not included in the Backtalk file.
backtalk@hvcn.org Wed Feb 6 09:35:00 EST 2002