home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / mail / valen102.zip / VALENCE.DOC < prev    next >
Text File  |  1993-03-16  |  40KB  |  802 lines

  1. \WHValence QWK Door v. 1.02 by William McBrine
  2. Copyright (c) 1993 Iconoclast Software
  3.  
  4.  
  5.                      \BL:\RD*\BL:\RD*\BL:\RD*\BL: USER DOCUMENTATION :\RD*\BL:\RD*\BL:\RD*\BL:
  6.  
  7.  
  8. \LB:::: \WHINTRODUCTION\LB ::::\NO
  9.  
  10. Welcome to Valence, the powerful new QWK door for Searchlight. This program
  11. will allow you to read and reply to messages offline, with all the
  12. convenience and power of Searchlight, and then some. It's packed with
  13. features. Writing them is more fun than writing about them, and I'm pressed
  14. for time, so I'll try to make this summary brief. To find out more about the
  15. door, explore it. I've tried to make it fairly simple to use.
  16.  
  17. I hope you enjoy using it as much as I enjoyed writing it.
  18.  
  19.  
  20. \LB:::: \WHQUICK START\LB ::::\NO
  21.  
  22. (No pun intended.) Just run the door, Download, answer "Y" when prompted,
  23. and enjoy! There is no mandatory setup. There are slews of options, but they
  24. all have default values. You can start QWKing right away, then go back and
  25. explore the options when you're more comfortable with it.
  26.  
  27. Ask your sysop or someone who you know uses offline mail for help on setting
  28. up a "Reader" program. They're all different, but pretty simple really. If
  29. you're game, just download one and try it. There should be at least one
  30. available for download on \%s.
  31.  
  32. If you don't want to fool with a reader program yet, you can try Valence in
  33. Text mode. (I actually programmed this part first.) This is mainly intended
  34. as a preview, or for use with systems that don't have QWK Readers, but it's
  35. pretty nice as is. In fact, I honestly would rather read Text packets from
  36. Valence than QWK packets from some other doors I've been inflicted with.
  37.  
  38. Note that the file MESSAGES.TXT will actually be an ANSI file, unless you
  39. turn off color codes in the Options section.
  40.  
  41.  
  42. \LB:::: \WHDOWNLOAD\LB ::::\NO
  43.  
  44. You can download in either Text or QWK packet mode (this file, whether
  45. you're reading it as a Bulletin or a help screen, is an example of what the
  46. text mode looks like). Downloaded packets include - at your option - new
  47. mail and messages, new bulletins, a system news file (if the sysop has
  48. provided for one), a list of new files, a SESSION.TXT file, and three
  49. pointer files.
  50.  
  51. The first time you download, you'll see the prompt:
  52.  
  53. The subboard list has been changed since your last download.
  54. Please upload any existing .REP files before proceeding.
  55.  
  56. Proceed? (Y/N)
  57.  
  58. If you have any packets from other/previous QWK doors that you want to
  59. upload to Valence, answer "N" to this prompt, and go back and upload them
  60. first. Otherwise, go ahead... later, you may see this prompt again, when the
  61. sysop has added or deleted subboards, or your access has changed. When you
  62. do, it's important that you upload the older replies first, or they may go
  63. to the wrong subboards. This is the one negative side effect of Valence's
  64. handling of conference numbers (see below for more info). On the up side,
  65. you'll always know when subboards are added to the board. :-)
  66.  
  67. Next you'll see
  68.  
  69. Copying WELCOME
  70.  
  71. (which may or may not appear, and may be followed by NEWS and/or GOODBYE)
  72.  
  73. and then scans for new bulletins, messages, and files. Any new bulletins
  74. found are listed by number. For the new message display and new files
  75. display, you have a choice of several display modes. By default, you get a
  76. screenful of numbers while message scanning, and the area descriptions while
  77. file scanning. Other options are descibed later in this document.
  78.  
  79. If you reach the maximum number of messages per packet, or the maximum
  80. number of messages in any subboard (these are user-selectable; see below),
  81. and you still have more new messages, you'll see this:
  82.  
  83. *** Your packet is full, but you have more new messages ***
  84.  
  85. Then, unless there were no new messages, the packet will be archived, and
  86. you'll be prompted:
  87.  
  88. Download this packet? (Y/N/G)
  89.  
  90. "Y" and "N" are self-explanatory; "G" stands for "Goodbye after download".
  91. This option will hang up on you after the transfer is completed, with a
  92. ten-second delay in which you can abort the hangup, much like a download
  93. from Searchlight. Unlike some other doors I've seen, this WORKS in Valence,
  94. and I recommend always using the "G" option, unless you have a very small
  95. packet or are on at high speed (so it won't take long).
  96.  
  97. After the above prompt, you'll be asked to choose a protocol if you don't
  98. have one set in the BBS. If you do, you don't have to set it in Valence; it
  99. will use the BBS protocol automatically. However, if you WANT to use a
  100. different protocol for Valence, you have that option, too.
  101.  
  102. If you're using a bidirectional protocol, and you have some .REPs to upload,
  103. you can upload them while downloading, and Valence should process them when
  104. the download is complete. This feature is untested at present, however. (Let
  105. me know if it works!)
  106.  
  107. You also have the option to download multiple packets at once; see below for
  108. details.
  109.  
  110.  
  111. \LB:::: \WHUPLOAD\LB ::::\NO
  112.  
  113. When you select this option, Valence will jump right into the upload -
  114. unless you don't have a protocol selected, in which case it will prompt you
  115. for one, as above. There is no option to hang up after upload, for the
  116. simple reason that I personally have rarely encountered a .REP file much
  117. over 10k, 5k being a more usual size. The file transfer should be over in a
  118. snap, and when your terminal program returns from its protocol display, you
  119. may find your new messages already posted. :-) It's pretty fast. It also is
  120. not very prone to lockups.
  121.  
  122. If you're using a batch protocol, you can upload multiple .REP files in one
  123. transfer. The name can be anything, but the extension must be .REP. (If you
  124. attempt to upload .REPs from another BBS, they will still be rejected; the
  125. filename of the .REP isn't the indicator.) After the transfer, Valence will
  126. AUTODETECT the compression method of each .REP file, instantly, and extract
  127. it with the appropriate program. When processing uploaded .REPs, Valence
  128. doesn't care at all what you have set for your archiver choice and pays no
  129. attention to it whatsoever. You can download with ZIP and upload with ARJ,
  130. for all it cares.
  131.  
  132. Uploaded messages are threaded automatically. "Low-bit" characters, which
  133. cause problems with Searchlight, are converted. (ESC codes, in particular,
  134. are converted to the character <`>, which is recognized by many offline
  135. reader programs as an ESC replacement in ANSI sequences. Thus uploaded ANSI
  136. will be preserved for other QWKers, though not for online reading in
  137. Searchlight.) In echomail subboards, "high-bit" characters are converted,
  138. and "Fido-style" taglines are enforced automatically. You have the option to
  139. switch this on and off for each subboard (echo and non-) individually.
  140.  
  141. ADD, DROP, RESET, and CONFIG control messages are supported. (See below for
  142. details.) Valence will recognize messages adressed to "VALENCE", "QMAIL", or
  143. "SLQWIK" (ugh) as control messages. These messages are not counted in your
  144. "total uploaded messages".
  145.  
  146. When your user record is first created, your subboard list is initialized in
  147. "yucky" mode (q.v.), although the yucky mode flag is set to false. This
  148. allows you to upload packets from older/other QWK doors before doing
  149. anything else - handy if the sysop has installed Valence as a replacement
  150. and deleted the other door.
  151.  
  152.  
  153. \LB:::: \WHOPTIONS\LB ::::\NO
  154.  
  155. There are altogether too many options in the Options section, but that's
  156. better than too few. Valence allows you substatianial control over the size
  157. and shape of your packet.
  158.  
  159. There are three screens of options. On the first screen, you can can set
  160. your choice of Archiver, Protocol (here you can set new protocols for both
  161. Searchlight and Valence, together or separately), packet size in number of
  162. messages, and ten yes/no options. These options will be explained in more
  163. detail at the end of this file.
  164.  
  165. At each numeric prompt, you'll see a range of numbers in parentheses, along
  166. with another number in brackets. These are the maximum, minimum, and default
  167. values. If you just press <RETURN>, the default will be used.
  168.  
  169. Note that most changes in options can be discarded when you leave the
  170. Options section by answering "N" at the "Save changes?" prompt, BUT, the BBS
  171. protocol selection and Alias name are written to Searchlight's user file at
  172. the time you edit them and are not affected by this prompt.
  173.  
  174. \LB*** ANSI/Translation ***\NO
  175.  
  176. The ANSI/Translation screen allows you to set the default mode Valence uses
  177. in translating messages. By default, all translation is ON. When I first
  178. wrote it, I thought the translation might slow message exporting down a bit,
  179. but there proved to be no detectable difference. Thus you can run with full
  180. Searchlight translation, without overhead. Color codes may be translated to
  181. ANSI, stripped, or simply passed through. Note that translating to ANSI
  182. takes precedence over stripping if both are set to "YES". Metacharacters
  183. (like your name, \%k) may be translated or passed through. The use of
  184. underline characters to join lines may be turned on or off, and this is one
  185. case where I might recommend setting it to "NO", because this feature of
  186. Searchlight is rarely used, and in my own experience I get much more
  187. unintentional wrapping than deliberate, from people using underline chars
  188. for other reasons (as, for instance, to indicate the title of a book).
  189.  
  190. Just as in Searchlight, all translation is also applied to included files,
  191. except - as in Searchlight - for underline joining and including files
  192. (which could lead to infinite recursion). Thus with the default settings,
  193. you should get in your QWK packet just what you would see if you were
  194. reading online in Searchlight.
  195.  
  196. The ANSI wrap is a little feature I had to add when I saw what SLMR did to
  197. the included files that had lines which went over 80 characters. My wrap
  198. will split the lines nicely, and join them with <ESC>[s and <ESC>[u
  199. sequences. This works great for most ANSI pictures, but will mess up ones
  200. that scroll the screen. If your reader will handle long lines, you may want
  201. to reset the wrap length to 255, so they'll all come through correctly. The
  202. wrapping is only applied to included files, not regular text, and only in
  203. QWK mode.
  204.  
  205. There's a special option here to strip flashing codes, for people like me
  206. who find it annoying. Other color codes will be unaffected. Only Searchlight
  207. flashing codes will be removed, not actual ANSI sequences from included
  208. files.
  209.  
  210. The "Color the filelist" option puts NEWFILES.DAT in color. You might want
  211. to turn this off if your reader doesn't like it, or to save space, or
  212. because you just don't like the color scheme. This option is ignored in Text
  213. packet mode, where the regular ANSI conversion attributes are checked
  214. instead.
  215.  
  216. All translation options are global defaults, and can be reset for each
  217. subboard. You can have some subboards with colors, and some without; some
  218. with metacharacters, and some without. Mix and match any way you like!
  219.  
  220. \LB*** Advanced options ***\NO
  221.  
  222. The first option on this menu is "Alias name". There is a field defined in
  223. the Searchlight user file for this; it's been there for some time, but
  224. Searchlight doesn't use it. Well, now Valence uses it. (I've heard there's
  225. another program out now which uses it, too, but I haven't seen it.) When you
  226. set your alias, Valence will scan the user file to make sure no one else is
  227. using it for either their name or alias. To delete your alias name, just hit
  228. <ENTER> when Valence prompts you for a new name.
  229.  
  230. Valence uses the alias name in two ways: when scanning for new personal
  231. messages, and when posting to an "Anonymous"-allowed subboard, where you can
  232. post with your alias, real name, or "ANONYMOUS". This is a bit of a kludge;
  233. let me know if you have any better ideas on how to implement alias support.
  234.  
  235. The rest of the Advanced options will be explained at the end of the
  236. document.
  237.  
  238.  
  239. \LB:::: \WHSUBLIST\LB ::::\NO
  240.  
  241. The subboard list editor allows you to join, unjoin, mass join/unjoin, set
  242. new high message markers, and set the special options for each subboard that
  243. you have access to. You can page through it easily with the + and - keys.
  244. Most of these options are, I hope, fairly self-explanatory.
  245.  
  246. Note that you are not allowed to unjoin or edit the MAIL subboard, even
  247. though it's displayed. The attributes used for the MAIL subboard are
  248. controlled by the global variables only.
  249.  
  250. Each line of the display in the subboard list shows the number, the name,
  251. the long description, the high message (i.e., your last read message), the
  252. number of the last message in the subboard, and the special attribute list.
  253. This last one looks a little cryptic; the header says "PAHFSCM". These
  254. letters each stand for a flag; there are seven flags packed into a byte for
  255. each subboard. The flags are:
  256.  
  257. \WHP = Personal Only
  258. A = Personal + All ;This takes precedence over P\NO
  259. H = High Bits Allowed
  260. F = Enforce Fido Taglines
  261. S = Strip Color Codes
  262. C = Convert Color Codes
  263. M = Convert Metacharacters
  264.  
  265. The last three, we've already seen under Options. Here you can reset them
  266. for each subboard. Note that these three options are not really active,
  267. UNLESS you explicit set them with the <C>hange attributes command.
  268. Otherwise, the global values are active. There is a hidden eighth bit, the
  269. master bit, which controls whether these three options are checked.
  270.  
  271. \LB*** High bits allowed, Enforce Fido taglines ***\NO
  272.  
  273. These two options are also subject to the master bit. By default, "high-bit"
  274. characters - those in the range 128-255 - are excluded from echomail areas,
  275. and Fido-style taglines are required there. (This is a rule in most Fidonet
  276. echos. Violating it will get you reprimanded by the moderator.) This is
  277. reversed for local subboards.
  278.  
  279. When Valence is asked to translate the high-bit characters in incoming
  280. messages, it does a rapid translation with a lookup table that turns the
  281. high-bits into similar-looking low-bit ones. (This translation is performed
  282. when high bits are allowed, too, to take care of some other problem
  283. characters; Valence just uses a different table then.) To make "Fido-style"
  284. taglines, "tearlines" are converted from "---" to "-=-".
  285.  
  286. What this boils down to is, you don't have to worry about setting Fido-style
  287. taglines in your reader, or using high-bit characters in messages. You can
  288. do as you like, and Valence will take care of it for you. If, however, you
  289. have an echo conference on which high-bit characters ARE allowed, or you
  290. want to change either of these options for a subboard for whatever reason,
  291. the options are here.
  292.  
  293. \LB*** Personal only and Personal/All ***\NO
  294.  
  295. These two options are the most useful. They are not subject to the master
  296. bit; which is to say, you can set either of these without it affecting the
  297. non-preservation of the other attributes.
  298.  
  299. Instead of having to download all the messages on a subboard, you can set
  300. that subboard to scan for just messages adressed to you (and your alias
  301. name, if one is set), or just just messages to you and "ALL". There are two
  302. mass-join features on the main SubList menu to facilitate this; unlike the
  303. <X> toggle option, which only applies to the subboards on the screen before
  304. you, the <P> and <A> options will join ALL unjoined subboards which you have
  305. access to, in either personal or personal/all mode.
  306.  
  307. When Valence is looking for messages to all, it actually checks only that
  308. the first four characters of the To: field are "ALL ", OR, that the first
  309. five characters of the field are "EVERY". This means it will include
  310. messages adressed to "Everybody", "Everyone", and "All You Zombies" (to
  311. quote The Hooters).
  312.  
  313. Note that when you join a subboard in personal or personal/all mode, you are
  314. genuinely Joined to that subboard, as far as Searchlight is concerned, and
  315. if you then do a New/Joined scan from Searchlight, you'll hit that subboard
  316. (without the benefit of personal/all filtering).
  317.  
  318. All edited attributes will follow the subboards they're attatched to if
  319. their conference numbers change.
  320.  
  321. For an amusing display, try the subboard list in "yucky" mode. The numbers
  322. can end up in any order. This is what your CONTROL.DAT file will look like
  323. in yucky mode, too.
  324.  
  325.  
  326. \LB:::: \WHPOINTERS\LB ::::\NO
  327.  
  328. Most other QWK doors only give you one pointer file, but with Valence you
  329. get three for the price of one.
  330.  
  331. A pointer file is a record of the "high message markers" in each conference.
  332. Valence only records the ones it updates. The one with the .PTO extension
  333. contains the old pointers, from before your download; the .PTN file is what
  334. Valence sets them to after a successful download. (The .PTN file is the
  335. actual file read by Valence at the end of a download when it says "Updating
  336. pointers".) The .PTX file is not really a pointer file, but a copy of your
  337. record in Valence's user file, with a character 255 at the beginning to make
  338. it an odd byte length. (Valence detects what type of pointer file you've
  339. uploaded by the length. Uh, this could be a problem if you're using Xmodem,
  340. or another protocol that saves received files in even block lengths. Don't
  341. try uploading a .PTX file with Xmodem; it won't work right. The others
  342. will.)
  343.  
  344. You'll rarely have to use any of these files, or this feature of the menu,
  345. but they're there if you need them. The pointer files are placed first in
  346. the packet, so that if you have a failed transfer, they'll be most likely to
  347. get through.
  348.  
  349. If your packet was corrupted in downloading, but you can still extract the
  350. .PTO file, and Valence thought your transfer went ok and updated your
  351. pointers, (ARGH!) you can upload the .PTO file to put things back the way
  352. they were before the transfer and redownload the messages.
  353.  
  354. If there's a crash on the BBS, and it's restored from yesterday's backup,
  355. and all your message pointers are set back to what they were the day before,
  356. you can upload the .PTN file to avoid rereading.
  357.  
  358. If you get a "The subboard list has been changed since your last download"
  359. message, and you really want to go on and download, but you haven't finished
  360. replying to your last packet yet, go ahead and download. Then go back and
  361. finish replying to the first packet, and upload the .PTX file from it, THEN
  362. the .REP. Then, before you upload your .REP to the new packet, upload the
  363. .PTX file from it. Make sure you keep the .REPs SEPARATE!
  364.  
  365.  
  366. \LB:::: \WHCONTROL MESSAGES\LB ::::\NO
  367.  
  368. These are messages you send to Valence in a .REP to configure it in the same
  369. way as you would online. All the options of online configuration are
  370. available here, with the exception of subboard attributes other than
  371. personal and personal/all. The form of a control message is a message
  372. adressed to "VALENCE", with the subject either "ADD", "DROP", "RESET", or
  373. "CONFIG".
  374.  
  375. "ADD", "DROP", and "RESET" are standard messages which can be generated by
  376. some readers automatically. If you're doing it manually: The message should
  377. be sent in the conference (subboard) to be added, dropped, or reset.
  378. Following the command in the subject for "ADD" and "RESET" may be a number;
  379. this number is the new high message to set for that subboard. If it's
  380. positive, it's an absolute message number; if it's negative, it's an offset
  381. from the last message on the subboard. If no number is given, ADD sets the
  382. high message to 0, and RESET sets it to last message on the subboard. The
  383. ADD command may further be followed by a "Y" to indicate join in personal-
  384. only mode, or a "YA" for join in personal/all.
  385.  
  386. "CONFIG" messages are a little more complicated. These allow you to set all
  387. the options you can set in Valence online, as well as joining and dropping
  388. multiple conferences from within a single message. "CONFIG" is the subject,
  389. and the message may be sent in any conference. Each line of the message
  390. consists of a command keyword, followed by optional parameters. You can use
  391. these keywords in any order, and case is irrelevant. Comments may be added
  392. to the message with semicolons, and blank lines will be ignored. The
  393. commands are as follows... "#" represents a number, brackets indicate an
  394. optional parameter:
  395.  
  396. \YEADD   <conference> [#] [Y] [YA]
  397. DROP  <conference>
  398. RESET <conference> [#]\NO
  399.  
  400. As when used in the subject field, with the addition of the conference
  401. number.
  402.  
  403. \YEMAXSUB   #  ; Maximum number of messages per subboard
  404. MAXTOTAL #  ; Maximum number of messages per packet
  405.  
  406. VPROTO   #  ; Set Valence's protocol to this number
  407. SLPROTO  #  ; Set Searchlight's protocol to this number
  408.  
  409. ARCHIVER  name\NO
  410.  
  411. Set your archiver choice to the one named, if the name is found.
  412.  
  413. \YEALIAS     name  ; Set/reset your alias
  414.  
  415. ANSIWRAP  #     ; Set ANSI wrap length to this number\NO
  416.  
  417. The remainder of the options are "boolean-type". Put a "Y" or "Yes" after
  418. each keyword to set it to "Yes" (true), or a "N" or "No" to set it to "No"
  419. (false).
  420.  
  421. \YEUNDERJOIN   ; Join lines with underline      Default: \WHYES\NO
  422. \YEMETACHARS   ; Replace metacharacters         Default: \WHYES\NO
  423. \YESTRIPCOL    ; Strip color codes              Default: \WHYES\NO
  424. \YEANSICOL     ; Translate color codes to ANSI  Default: \WHYES\NO
  425. \YEFLASHOFF    ; Ignore flashing codes          Default: \LRNO\NO
  426. \YEFILECOLOR   ; Color the filelist             Default: \WHYES\NO
  427. \YEINCLUDE     ; Expand included files          Default: \WHYES\NO
  428.  
  429.  
  430. \LB:::: \WHMORE YES/NO OPTIONS\LB ::::\NO
  431.  
  432. As promised, an explanation of all the unexplained options. These will be
  433. listed both as they appear on the Options screens and with their
  434. CONFIG-message keywords.
  435.  
  436. \YEMARK        ; Mark new messages as read    Default: \WHYES\NO
  437.  
  438. If set to YES, Valence will update the high message pointers in all scanned
  439. subboards, and increment the number of times read of, or delete, each
  440. private MAIL message, after a successful packet download. About the only
  441. reason you'd want to set this to NO is for testing purposes.
  442.  
  443. \YETEXT        ; Text packets instead of QWK  Default: \LRNO\NO
  444.  
  445. Text packets (mentioned above) combine the new bulletins, new messages, and
  446. new files into a single large text (or ANSI) file, and archive it together
  447. with the pointer files and WELCOME/NEWS/GOODBYE/SESSION.TXT files, if those
  448. are selected. Where QWK packets use the extension .QWK, Text packets use the
  449. default extension of the archiver (.ZIP, .ARJ, .LZH, etc.). You won't be
  450. able to reply offline to messages downloaded in Text format. Other than
  451. that, this mode is identical to QWK mode.
  452.  
  453. \YEFILES       ; Include new files listing    Default: \WHYES\NO
  454.  
  455. Valence will scan all directories you have access to, sorted by MAIN.DIR,
  456. for new files, and list any it finds in the file NEWFILES.DAT (or
  457. MESSAGES.TXT in Text mode).
  458.  
  459. \YEBULLETINS   ; Include new bulletins        Default: \WHYES\NO
  460.  
  461. You can leave them out if you want. The only time I'd do that is if the
  462. board I was on was updating ten a day or so, and they were all game high
  463. score files. (I've been in that situation, in fact, but not on a Searchlight
  464. board (so far).) Note these are scanned for by date, and you may have
  465. bulletins being updated without the date being changed. If so, encourage
  466. your sysop to use BUPDATE.EXE, provided with the Valence package.
  467.  
  468. \YENEWONLY     ; DL only new private mail     Default: \LRNO\NO
  469.  
  470. By default, Valence will download all the old junk you've kept online in
  471. your mailbox, as well as the new mail...
  472.  
  473. \YEKILLMAIL    ; Kill private mail after DL   Default: \WHYES\NO
  474.  
  475. ...and then, delete it. You can save it from your reader, which should be
  476. more convenient, and certainly will be more convenient to your sysop. Just
  477. please BE AWARE that this is being done, and don't just discard a packet,
  478. thinking that your old mail is still saved on the BBS.
  479.  
  480. The defaults here are partly to keep the MAIL subboard clean of old
  481. messages, and partly a personal preference, because I too am guilty of
  482. letting huge numbers of messages collect in my Searchlight mailboxes. Or
  483. rather, I used to be; now Valence keeps 'em empty for me. And it works a lot
  484. better than what I used to do: wait until I had a couple dozen accumulated,
  485. then jump to DOS, read them with SLMAIL, archive them, move them to the
  486. uploads directory, return to the BBS, download the archive, kill it, and
  487. purge my mail. Valence does the same thing (and much more) automatically
  488. (and it runs faster than SLMAIL, and purges faster than Searchlight).
  489.  
  490. One reason you might want to disable this option is NETMAIL. At present,
  491. Valence will not allow you to send netmail from the door, so if you have a
  492. netmail message in your packet, you can't reply to it directly; you have to
  493. go back to the BBS to do it. And if the original message has been deleted,
  494. it's a bit less convenient to reply to. (I hope to allow direct replies to
  495. netmail SOON.)
  496.  
  497. \YEOWN         ; DL messages FROM yourself    Default: \LRNO\NO
  498.  
  499. The default saves a little space by keeping you from downloading what you
  500. just uploaded.
  501.  
  502. \YEYUCKY       ; Yucky conference numbers     Default: \LRNO\NO
  503.  
  504. OK, this is a BIG one.
  505.  
  506. \LB*** Conference numbers in Valence ***\NO
  507.  
  508. One of the biggest features of Valence is the way it handles conference
  509. numbers. This has been alluded to earlier in this document; here are the
  510. details:
  511.  
  512. Searchlight uses 8-character names (which are DOS filenames) to identify its
  513. subboards. The QWK format uses "conference numbers" to identify each area.
  514. These are matched to names with the CONTROL.DAT text file, but it's the
  515. conference numbers which are used to tell what area a message came from, and
  516. the conference numbers which are used to tell the door what area a reply is
  517. going to. So far, so good; it isn't hard to generate a list of numbers to
  518. match a list of names. But there IS a MAJOR problem here, in that with
  519. Searchlight, a new subboard can be inserted in between two existing ones, or
  520. an old subboard can be deleted, moving the subboards that follow it on the
  521. list up one place. If the subboards are numbered sequentially, then, and
  522. subboards are added or subtracted in between the time you download a packet
  523. and the time you upload a reply, the conference numbers stamped on your
  524. reply messages may no longer be valid. That means the messages you upload
  525. will be posted to the wrong subboards.
  526.  
  527. So, you can't use sequential numbering of the subboards in Searchlight - at
  528. least, not without some trickery. So what DO you do? How do you make a
  529. sensible translation from Searchlight's named subboards to the QWK format's
  530. numbered conferences? ...A translation that will hold up when subboards are
  531. added or deleted?
  532.  
  533. The first solution attempted in a QWK door for Searchlight was SLQWiK's use
  534. of the absolute record number of a subboard in the SUBBOARD.SL2 file (the
  535. master list of subboards). This number won't change, as long as the subboard
  536. exists. If the subboard is removed, it's marked as a deleted record, and the
  537. record numbers don't change. If a new subboard is added, it will be added to
  538. the end or inserted in a previously deleted record.
  539.  
  540. As far as I know, Jack Ridgway hacked this method out himself, which was
  541. pretty clever. It was successful enough that Frank LaRosa then adopted it as
  542. the "official" way of making unchangeable reference numbers, by adding an
  543. "absolute record number" field to the subboard information returned by the
  544. subboard list intializer in the Searchlight Programmer's Library.
  545.  
  546. But this method leaves something to be desired. The numbers you end up with
  547. in CONTROL.DAT are in a random order. This is very ugly, to say the least,
  548. and can mess up some readers. (SLMR, for one, can't make a correct ".MRB"
  549. bookmark file for packets like this. If you come back to reread such a
  550. packet after exiting SLMR, the "Read" markers will be all over the place.)
  551. When I set out to write my own QWK door, this was one of the first things I
  552. wanted to fix. The way I saw it, the subboard list in your reader should
  553. look just like the one you see in Searchlight - sorted by MAIN.SUB, etc. -
  554. with nice sequential numbers in the CONTROL.DAT, and no gaps. And that's
  555. what Valence gives you.
  556.  
  557. Internally, Valence keeps a table of sequential numbers -> absolute record
  558. numbers - one for each user. This list is recalculated every time you select
  559. the "Download" or "SubList" function, and is compared to the stored list. If
  560. it's different, you get the "Subboard list has been changed" warning
  561. message.
  562.  
  563. When you upload a .REP file, the conference numbers in the .REP are
  564. translated back to absolute record numbers, using the stored table from your
  565. last download or edit, and thence to subboard names. Thus the messages will
  566. go the right subboards as surely as if I used absolute record numbers. The
  567. difference here is, you have more opportunity to mess it up, by ignoring the
  568. "Subboard list has been changed" prompt, and then uploading .REPs to
  569. previous packets. I see this as an unlikely scenario (but see above under
  570. POINTERS), although my personal message-reading habits make it more likely
  571. for me than average. :-)
  572.  
  573. When you first enter Valence, it intializes your list to an absolute record
  574. number list, so that you can upload .REPs from other QWK doors as the first
  575. thing you do. After your first download, however, you'll have to set Valence
  576. to "Yucky mode" (ah, finally we come to that) if you want to interchange
  577. .REP files between it and another QWK door.
  578.  
  579. \LB*** Yucky mode ***\NO
  580.  
  581. Yucky mode discards the usual Valence method of generating conference
  582. numbers, and uses absolute record numbers for conference numbers. I call it
  583. that because it's yucky. I don't recommend its use, ever, except if you HAVE
  584. to upload a .REP from another QWK door. You might also use it if you're
  585. paranoid about the possibility of uploading a message into the wrong
  586. subboard. That can't happen in yucky mode (unless you upload replies to a
  587. packet downloaded in NON-yucky mode). It will RARELY happen in Valence ever,
  588. and will NEVER happen if you follow the prompts, but yucky mode offers a
  589. very tiny extra margin of security.
  590.  
  591. \YENUMBERED    ; Numbered packet names        Default: \WHYES\NO
  592.  
  593. This option appends a two-digit number to the name of each of your packets.
  594. The number used is the number of the packet mod 100. My own opinion of
  595. numbered packets is that they're unaesthetic, but useful. I first saw this
  596. feature in SLQWiK, and it's the one point (aside from devising the use of
  597. absolute record numbers) on which I give Jack Ridgway a lot of credit. Note
  598. that unlike SLQWiK, Valence pads numbers below ten out with a zero, so
  599. the packets will sort correctly.
  600.  
  601. If you're doing a non-stop multiple-packet download, and you DON'T have
  602. numbered packets selected, Valence will rename files after the first one in
  603. the form: <BBBSID>.QW0, .QW1... .Q98, .Q99. Valence will in no case allow
  604. you to download more than 99 packets at a time. :-)
  605.  
  606. \YEEMPTY       ; DL packets with no messages  Default: \LRNO\NO
  607.  
  608. Valence will terminate with an error and return to the BBS if this is set to
  609. NO and it finds no new messages. Please note that if you DO have new
  610. *bulletins* or new *files*, Valence will still abort (it won't even scan the
  611. files), so you might want to set this to YES.
  612.  
  613. \YEWELCOME     ; Include Welcome and Goodbye  Default: \WHYES\NO
  614.  
  615. If YES, and these files exist, they will be included in the packet. These
  616. are normally ANSI screens, and default to Searchlight's LOGIN.ANS and
  617. LOGOFF.ANS.
  618.  
  619. \YENEWS        ; Include News file            Default: \WHYES\NO
  620.  
  621. Optional system News file, which the sysop may or may not have implemented.
  622.  
  623. \YEBBDATE      ; New bulletins from BBS date  Default: \LRNO\NO
  624. \YEBFDATE      ; New files from BBS date      Default: \LRNO\NO
  625.  
  626. By default, Valence scans for new files and bulletins, separately, from the
  627. date it last found any, rather than the date you were last on. If you've
  628. ever called a board after a while's absence, logged off or been cut off, and
  629. then realized you didn't see the new files list, but can't remember what
  630. date it was you last called, and now if you call back and do a "New" in
  631. "Files" Searchlight will only scan today's files... you'll appreciate this.
  632.  
  633. But if, on the other hand, you've been calling every day and checking new
  634. files and reading new bulletins, but not always using Valence, you may want
  635. to set these to YES to avoid rereading.
  636.  
  637. The internal dates are intialized with your last on date the first time you
  638. use Valence, so your first download should be the same either way.
  639.  
  640. \YEALLBULLET   ; Download ALL bulletins       Default: \LRNO\NO
  641. \YEALLNEWS     ; ALWAYS include News file     Default: \LRNO\NO
  642.  
  643. If set to YES, it forces these files to be included in your packet whether
  644. they've been updated or not. This may be useful once in a while, especially
  645. for the bulletins.
  646.  
  647. \YESESSION     ; Include SESSION.TXT          Default: \WHYES\NO
  648.  
  649. SESSION.TXT is a simple text file identical to what you see on your screen
  650. while scanning, from the "Copying WELCOME" message on down through the new
  651. files, but without the colors. It may be useful for you to see what messages
  652. you scanned sometimes, but for the most part, this is just a frill (though
  653. part of the QWK standard). It's just a little file, usually, but turning it
  654. off will save you an open file handle while scanning, which can be a help
  655. sometimes. (At the max, Valence has eleven files open at once.)
  656.  
  657. \YEINCREAD     ; Add to number of times read  Default: \LRNO\NO
  658.  
  659. This increments the "number of times read" counter in each message you
  660. download. Perhaps this should be on by default, but it may slow Valence down
  661. slightly, and since that field isn't even used in QWK packets (unless you
  662. turn on "MOREINFO", below), and since another QWK door I tried didn't bother
  663. incrementing them...
  664.  
  665. \YEMULTIPLE    ; Download multiple packets    Default: \LRNO\NO
  666.  
  667. This is a powerful option. When set to YES, whenever you get a "*** Your
  668. packet is full, but you have more new messages ***" message, Valence will
  669. automatically start scanning and packing the next packet after it
  670. successfully sends the first, and will repeat until all new messages are
  671. sent. On scans after the first one, the download prompt is turned off, as
  672. are the bulletins, welcome/goodbye, and new files (since these have already
  673. been scanned), and hangup after download (i.e., after transfer of ALL
  674. packets) is automatically selected. If you only have one packet's worth of
  675. messages, hangup is not automatically selected, and Valence operates just as
  676. it would with this option set to NO.
  677.  
  678. \YEDLPROMPT    ; Prompt for download          Default: \WHYES\NO
  679.  
  680. If this is turned off, the "Download this packet? (Y/N)" prompt does not
  681. appear, Valence goes straight to the download, and hangup mode is
  682. automatically selected. It also replaces the "The subboard list...Proceed?
  683. (Y/N)" prompt with a message: "Warning: The subboard list has been changed.
  684. Old .REPs may be invalid", and goes right on with the download, so I really
  685. advise against using this option.
  686.  
  687. \YEBLANKLIST   ; Show empty areas in scan     Default: \LRNO\NO
  688.  
  689. Shows all areas scanned, even if there's nothing new in them.
  690.  
  691. \YEMANYNUM     ; A lot of numbers in scan     Default: \WHYES\NO
  692.  
  693. In scanning for new messages, Valence will list First Msg, Last Msg, Last
  694. Read, New Last, Extracted, and Personal. This takes precendence over
  695. "wordy" mode. It has no effect in scanning files.
  696.  
  697. \YEWORDY       ; Area descriptions in scan    Default: \WHYES\NO
  698.  
  699. This prints the area descriptions when scanning new messages (if not
  700. overridden by manynum) and new files. If off, only the area name and number
  701. extracted (and personal) will be shown.
  702.  
  703. \YEWRAPFILES   ; Wrap filelist into 40 cols   Default: \WHYES\NO
  704.  
  705. Instead of having one short file description line of 40 characters followed
  706. by two lines of 60 characters, you can have 4 lines (approximately) of 40
  707. characters each, all neatly aligned. Try it, I think you'll like it. But it
  708. does make for a larger NEWFILES.DAT than the non-wrapping mode.
  709.  
  710. \YEEXTRALN1    ; Blank line after long descs  Default: \WHYES\NO
  711.  
  712. This, the default mode, is like Searchlight's internal file listing:
  713. single-line descriptions run together, while multi-line descriptions have a
  714. blank line between them.
  715.  
  716. \YEEXTRALN2    ; Blank line after each file   Default: \LRNO\NO
  717.  
  718. A different way to do it.
  719.  
  720. \YEFULLSUBJ    ; Full subject in text         Default: \WHYES\NO
  721.  
  722. Searchlight's subject lines are up to 40 characters long; the QWK format is
  723. limited to 25. If, and only if, a message's subject is over 25 characters
  724. long, Valence will by default include it in the first line of the message
  725. with the word "Subject: ", and a blank line afterwards. Valence will also do
  726. this ALWAYS for "Fwd Fm:" and received netmail (which Searchlight prints as
  727. "Origin:" but Valence prints as "Netmail:").
  728.  
  729. Also, if a subject line starts with a "Re: ", "RE: ", or "(R) ", Valence
  730. will automatically strip it out, both to save space in the subject field and
  731. fit more of the originial subject in, and to allow better sorting of
  732. messages by subject. (SLMR does this automatically, and it works distinctly
  733. better since I added "Re: " stripping.) There is no option to turn this off
  734. (sorry). The "Re: " will not be stripped out of the long subject line in the
  735. body of the text, nor in Text mode.
  736.  
  737. \YEMOREINFO    ; Even more info in text       Default: \LRNO\NO
  738.  
  739. This adds a line, like the ones just mentioned, into the body of the QWK
  740. message, listing number of times read, number of replies, and whether the
  741. message has been imported or exported.
  742.  
  743. Together, these two keywords cover all the "extra" information in the
  744. Searchlight message header. Neither has any affect in Text packet mode.
  745. Headers in Text packets are identical to Searchlight's display, apart from
  746. the colors.
  747.  
  748. \YEDISORDER    ; Ignore subboard list file    Default: \LRNO\NO
  749. \YEFDISORDER   ; Ignore directory list file   Default: \LRNO\NO
  750.  
  751. Ordinarily, Valence, like Searchlight, reads the files MAIN.SUB and MAIN.DIR
  752. and sorts the subboard and file directory lists, respectively, according to
  753. these files. You can turn this off if you want.
  754.  
  755. \YEPERSINDEX   ; Include personal index file  Default: \WHYES\NO
  756.  
  757. You can turn off the PERSONAL.NDX file (saving another of those eleven open
  758. files), and you won't have a "Personal" conference in your reader (or you'll
  759. have an empty one). The only reason this option is here is because I
  760. remember seeing it in Qmail (? I think), and it was trivial to implement.
  761.  
  762. \YEBRANDNEW    ; You haven't DLed yet         Default: \BLSee below\NO
  763.  
  764. This is normally a one-shot option; it's set to YES when you enter Valence
  765. for the first time, to tell it to send you THIS FILE (and the intro message
  766. in MAIL), and then set the option to NO. If you ever want to receive this
  767. file over again, you can set the option to YES.
  768.  
  769. \YEJOINED      ; Only joined subs in sublist  Default: \LRNO\NO
  770.  
  771. This will shrink your CONTROL.DAT somewhat if you turn it on, and may make
  772. for a neater display in your reader (though it will make gaps between
  773. conference numbers appear), but it will prevent you from joining any
  774. unjoined subboards offline, except with the "CONFIG" message method.
  775.  
  776.  
  777. \LB:::: \WHSOMETHING NOT TO DO\BL ::::\NO
  778.  
  779. For all you masochists out there, to make Valence functionally equivalent to
  780. SLQWiK, set these options:
  781.  
  782. UNDERJOIN NO
  783. METACHARS NO
  784. STRIPCOL  NO
  785. ANSICOL   NO
  786. FILECOLOR NO
  787. INCLUDE   NO
  788. BULLETINS NO
  789. NEWONLY   YES
  790. KILLMAIL  NO
  791. YUCKY     YES
  792. WELCOME   NO
  793. NEWS      NO
  794. SESSION   NO
  795. WRAPFILES NO
  796. FULLSUBJ  NO
  797. DISORDER  YES
  798. FDISORDER YES
  799.  
  800. Sorry, there's no way I know to make Valence slow down and lock up
  801. frequently. :-)
  802.