OS/2 Shareware BBS: 35 Internet

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / yep16.zip / yep.doc < prev next >

Wrap

Text File | 1997-04-09 | 62KB | 1,313 lines

Y E P Yarn Editor Pre/Post Processor Y E P Version 1.6 Contents: ~~~~~~~~~ -1- ------------------------------- Introduction to Yep -2- ------------------------------- Installation of Yep (------------- Edit Yarn CONFIG (----------------- Edit Yep.cfg (--------------Yep but Not Yarn -3- ------------------------------- Tags & Substitution (-------------- {RNDL:filename} (random line) (-------------- {RNDF:filename} (random file) (-------------- {IMPF:filename} (import file) (---- {EXEC:filename arguments} (execute program) (------------ {IMPL:#:filename} (import line) (- {IMPLS:"string"::"filename"} (line string) (---- {IMPLR:L#:S#:C#:filename} (line range) (----------------- Subsitutions -4- ------------------------------- Yep Operation Notes (---------------- . Translation (---------------- Mailing Lists (------------------ SIG Example -5- ------------------------------- Of Conditional Tags (-------------- {IFTO:any text} (------------ {IFSUBJ:any text} (------------ {IFDATE:any text} (-------------- {IFNG:any text} (-------------- {IFXN:any text} (-------------- {IFCC:any text} (------------- {IFBCC:any text} (-------------- {IFRT:any text} (---------- {IFFLAG:true/false} (--------- {SETFLAG:true/false} -6- ------------------------------- Capturing Your URLs -7- ------------------------------- UUencoding and Yep! (---------------{UUEN:filename} -8- ------------------------------- Of Specialized Tags (--------------------- {EXPD:#} (expiry date) (---------------- {DATE:string} (date/time/more!) (---------------------- {POM:#} (phase of moon) (----------------- {YPDEC:code} (Yep decrypt) (------------------- {RNDN:#:#} (random number) (---------------- {RNDC:string} (random character) (---------------- {HEADER:name} (header values) (----------- Special Precedence -9- ------------------------------- Block Process & PGP -10- ------------------------------- Anonymous Remailers -11- ------------------------------- Of Finding Problems *12* ------------------------------- History of Revision -13- ------------------------------- Who, what and where -1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1- Introduction to Yep: ------------------- Yep is an "editor shell" for use specifically with the Yarn off-line newsreader (OS/2 version). Yep will also work with other mail/news readers which call external text editors. Yep provides the following functionality: - Start your editor with the first line number past the message header, or quotes in a reply, (if your editor supports it) - Append your own lines to message headers. - Embedded macro tags at any point can: - import random lines of text (suitable for taglines, SIG lines, random header messages, etc) - import files automatically into messages. - import random files (ie. useful for random SIGs) - execute programs (useful to create macros which automatically import the text output of a program) - conditionally do/print things based on current newsgroup, to, date, or subject field. (for example, have custom headers or SIG files for particular newsgroups) - User defined substitution code table to create "macros" from the above tags, create custom abbreviations, or correct common spelling errors. - Optionally strip unused header entries when starting editor - Automatic URL capturing / logging / converting - Lightning fast built in UUencoder for file importing - Block Processing for filters/PGP encryption, etc - Many, many, many more weird and wonderful things, far too numerous to describe here. Read on! Yep is extremely configurable. The author likes to think of it as a program that can make every email an adventure! (-: It can be utilized in a simple manner for basic functions (like setting start up cursor positions), or in mind bogglingly complex customised craziness. It should be mentioned that there is already an excellent, and far more comprehensive "editor shell" for Yarn which is called "Yes". My reason for creating my own shell was mainly because there is no OS/2 version of Yes (at this time); and also creating my own shell I can tailor it to my specific (and possibly insane) desires. I have no idea if anyone else may find it useful to them, but here it is. And after all, you could set yourself up to use both Yep and Yes at the same time, if you really want to. (-: -2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2- Installation of Yep: ------------------- It doesn't matter what directory you place YEP.EXE in, just as long as the YEP.CFG is in the same directory. 1. Edit your Yarn CONFIG file. Edit the line which begins "editor=". This line should now read: editor=<path>\YEP.EXE where <path> is the path to wherever you placed the YEP.EXE. Note: Yep should have no parameters on that line. You will define the command line for you editor in the YEP.CFG file. 2. Edit your YEP.CFG file. There are comments in this file (all lines beginning with a semi-colon (;) are comment lines), so not many details will be given in this document. Refer to the Yep.Cfg for instruction. You may use multiple copies of YEP for different users of yarn on your system. The YEP will always look for a CFG file that has the same root name as itself. Therefore if you made another copy of Yep and called it YEP2.EXE you would then create a YEP2.CFG file, which could have it's own set up. In the Yep.Cfg if you specify the full path (and EXE extension) of your editor it will be called directly and speed up loading a bit. Otherwise it is called though the command shell and your path is searched. That's all there is to basic installation. How you use and customize Yep is up to you. Yep But Not Yarn ---------------- Yep will work with some other OS/2 news/mail readers which meet the following criteria: - uses an external text editor - sends message headers to the editor Yep may have to be configured to recognise the filename of messages used with your news reader. See the line beginning Process= in the Yep.cfg for details. Yep is set up by default to recognise Yarn, MR2ice (see the MR2ice.doc included). -3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3- Tags & Substitution: ------------------- A major concept of Yep is that of it's "macro" tags. Each message is scanned for substitutions and tags before the editor starts, as well as after the editor exits. There are at this time only a few tags implemented (but many things can be done with them). The basic syntax for tags are: {TAG:arguments} TAG is the name of the tag to be used, followed by a colon, followed immediately by information that the tag is to work with. Tags are not case sensitive-- they can be upper or lower or mixed case. Tags and substitutions are scanned sequentially on each line and therefore nesting (tags within tags) will not work. However all substitutions are done before any tags are interpreted, therefore you can put substitution codes inside tags (i'm not sure what for). Yep attempts to "translate" or "filter" all text that goes though it. It can get somewhat complex, but you can also include tags in imported files, and they will be honoured. {RNDL:filename} This tag will import a random line from the text file specified. The file can be of any length. Blank lines and lines beginning with a semi-colon (;) in the file will be ignored. This tag is useful for creating random "taglines" in your sig, or a random line in a header. It may have many other uses as well-- but that is up to you, and your imagination. For example, if in your YEP.CFG you had a header line like this: X-Funny-Line: {RNDL:funny.txt} In the above example the "X-Funny-Line:" header would be included in your message and a random line from a text file called "funny.txt" would follow it. {RNDF:filename} This tag inserts a random file. The "filename" specified will be considered a "root" or "base" filename (ie. the filename WITHOUT any extension). The directory containing the filename root will be scanned looking for files with that name having numbered extensions .1, .2, .3, and so on. The extension numbers must be sequential, with no gaps. A random file will be picked and inserted. {IMPF:filename} Very simply imports the "filename" file into your message. It could be useful for inserting external files into a SIG, or other places. For example, some people like to include their PGP key in their sig. You could do that by including {ImpF:c:\pgp\mykey.asc} in your SIG file (note: Yep does not append a SIG file itself, but interprets the SIG file that Yarn appends to each message). In this way if you upgrade PGP to a new version and export a new key to the filename noted above, your sig will always automatically have the latest extracted version of your key. {EXEC:filename arguments} This causes your message to stop and execute a file. The idea here is that you might have a file which output some text you would like to insert into the message: perhaps random quotations, or up to the second system statistics. You can execute the file with this tag and redirect the output to a temporary file, and then use the IMPF tag to read in the newly created temporary file. See the Yep.Cfg file for a few examples of this. As with the text editor configuration, if you specify a full path (with EXE extension) for your filename to EXEC then the program will be called directly, which speeds things up. Otherwise the file is run though the command processor and path is searched. Note: if you are using the EXEC tag to capture output using standard I/O redirection, do NOT include the EXE on the path/filename, as the program must be executed indirectly through your command processor in order to do standard output redirection. (See below in the "substitutions" section for more details). {IMPL:#:filename} Perhaps there is a text file from which is only wanted a single specific line of text (for example: to grab a line of information from the output of a text file generated by some other program}. With the ImpL tag you specify the line number you wish to read where the # is (do not include a # symbol), followed by a colon (:), and the filename. As an example: perhaps in your mail headers you would like to display to the world how long your computer has been running. There is a nice utility called "Go" by Carston Wimmer (ftp://hobbes.nmsu.edu/os2/textutil/go_15.zip) which will display OS/2's "up time" (and will do much more). However the output of Go also includes title/copyright line of text which you don't want to import: all you want is the "up time" reported on line 3 of Go's report. The output of "go -ut" might look like this: GO! v1.5 - (c) 1993-95 by Carsten Wimmer <cawim@train.oche.de> Uptime: 1d 23h 56m 59s 364ms Therefore you might include in your yep.cfg a header definition which would look like this: X-OS2-{exec:go -ut >utmp}{impL:3:utmp} The first tag in the above example executes the "Go" utility with the "-ut" switch and redirects the output to a work file called "utmp". The next tag then directs Yep to import line three, and only line three, of the work file that was created. Note also that the output of Go, with the -ut switch, includes a header-like "Uptime:", so in our example the fine output of your header would look like this: X-OS2-Uptime: 1d 23h 56m 59s 364ms {IMPLS:"string"::"filename"} Import the first line from a text file with begins with the string specified. For example, lets use the "GO" program again. Say you wanted to report in your message (God, only knows why) the current number of processes and threads active. When you EXEC "GO" it gives a list of all your processes running, and a summary at the bottom. We can not use IMPL (import line) because the summary is going to be on a different line depending how many processes were in the list above it. The summary line given by "GO" looks like this: There are 11 Processes with 66 Threads. Using the IMPLS tag we can search for the first string in our temporary capture file (see EXEC procedure) beginning with "There are". The tags would then perhaps look like this: {EXEC:go >utmp}{ImpLS:"There are"::"utmp"} {IMPLR:L#:S#:C#:filename} This variation works the same as {IMPL:#:filename} (import line), but with the added control of being able to only import a portion of that line. Three numbers must be specified: L# is the line number to be imported; S# is the starting column of the line to import; and C# is the count number of characters to import from that starting position. For example, say there was a program you ran with an EXEC tag which outputs... After giving this much thought i have realized that I can dream up no practical application for this tag! You are on your own! If you ever need to import just a portion of a certain line (for some task i can not even imagine), here is the tag to do it with! ImpLR stands, only slightly confusingly, for "import line range". That's that. Substitutions: ------------- It would be rather awkward if you had to type in then entire tag, with filenames, and whatever other data that needs to be given, therefore you can define your own tags by using a substitution table. In the Yep.Cfg you may define (currently) up to 100 substitutions. For example, say you wanted a quick way to import your PGP public key into a message when someone asks for it. Rather than typing: {impf:c:\pgp\my.key}, you could set up a substitution in the Yep.Cfg something like this (refer to Yep.Cfg for details on the format): "{pk}"::"{impf:c:\pgp\my.key}" Now whenever you want to insert your PGP public key you would only need to quickly type {pk} in your message and it would be inserted. This is just an example, you could make it whatever you wanted. For another example, silly as it may be, say you had a fetish about how much disk drive space you have free at any given moment, and you are obsessed with telling everyone in every message how much drive space is available that very second. You could define a substitution something like so (assuming you have a utility called "free" which reports current free disk space): "{ds}"::"{exec:free >tmp}{impf:tmp}" In this way the "free" command is executed and its output is redirected to a temporary text file which is then imported into your message. (Note: if you are going to use ">" redirection to send output to a file, Yep needs to go through your OS command interpreter shell-- in this case do not include a full path to your program, as directly calls will not have redirected output.) -4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4- Yep Operation Notes: ------------------- Dot Translation: =============== When Yep runs you will see it announce itself, and then a series of coloured dots. (This behaviour can be turned off in the YEP.CFG if undesirable). Each dot tells which operation Yep has just completed during it's scanning and filtering activities. In this way you can tell how long certain operations take, as well as possibly debug certain problems; not to mention it's a form of cheep entertainment if you are tired of watching television. Yep begins by announcing itself as "Yep...". This just tells you the shell has started. After that dots follow: LIGHTBLUE - an user defined header line has been inserted. LIGHTGREEN - a substitution action has taken place. GREEN - A random line (RNDL) has been fetched (BLUE if it fails). BROWN - Yep has successfully imported a text file (IMPF/IMPR). YELLOW - Yep has attempted to import a text file but failed. GRAY - this is a potentially important dot: it indicates that yep is about to execute (EXEC) a program. A DARK grey dot means it is attempting to execute the program directly, a LIGHT gray dot means it is executing through your OS shell. This dot also shows up immediately before the Editor is called, so the user can see how quickly Yep pre-processes the file, and calls the editor (depending on system speed). PINK - YPDec has decrypted a code, or a random number generated. BLUE - is a general error, and an error usually is given. After you finish editing your message Yep scans the message for any new processing instructions. The above colours apply. When it is finished it signs off with "...Yep" and returns you to Yarn. Mailing Lists: ============= Rather a cheap hack, but one could, if one wanted, create a file with a comma separated list of addresses. Then create a substitution code which loads that file, something like: "{list1}"::"{IMPF:c:\yarn\MailLst1}" With this set up you only need to type {list1} in the Bcc: or Cc: field of your message and the list of addresses will be imported/substituted, and therefore mailed to everyone. Alternately you can just define a substitution that has your "mailing list" in it, and avoid having to import a file. "{L2}"::"someone@somewhere.edu,another@addr.com" Note: addresses are separated by commas. In the above example if you entered {l2} in the To:, Cc: or Bcc: field of a message then it will be substituted with the comma delimited list. SIG-gy Tricks: ============= Note: Yep does not append a SIG file, but relies on Yarn to append the SIG file. Yep however interprets whatever it finds in Yarn's SIG file allowing for many tricks. Using various substitution codes you can do quite flexible things with your SIG file. Not only can you have complete randomly chosen SIG files, and link external files, but individual elements inside your SIG can be randomized via the RNDL tag. For example, my current SIG file looks like this (this is just one small example of the possibilities): {rndl:c:\osu\yarn\sig1top.lst} Tim Middleton {rndl:c:\osu\yarn\sig1luv.lst} as544@torfree.net {rndl:c:\osu\yarn\sig1red.lst} {rndl:c:\osu\yarn\sig1end.lst} What it does is gets a random top element from a list, then prints my name, inserts another random element from a different list, and then my email address. Furthermore, it then inserts another randomly chosen line, and finally a randomly chosen bottom element. The finally output might look like this (call me crazy, I love randomness!): .+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+. Tim Middleton -with love and tomato sandwiches- as544@torfree.net -=-= brace yourself and read The Idiot by Fyodor Dostoyevsky =-=- ~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~ -5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5- Of Conditional Tags: ------------------- The idea here is to give the user even more automated customization of their messages. For example, with conditional tags you can implement different SIGs based on the newsgroup being posted to. Or custom header lines based on who the message is To. This seemed like a good idea to me when I started working on it. Now I'm not sure if it's worth the trouble. You can safely ignore it if it doesn't sound useful to you. The way these tags work is that if the condition in them is met (ie. if it is true) then the rest of the line will be filtered through, otherwise the rest of the line will be discarded. If the conditional tag begins in column one and returns false then the entire line will be skipped. The new tags are: {IFTO:any text} If the text specified in the "any text" is found in the To: field of the header then the rest of the line is processed. {IFSUBJ:any text} Same as above, only the Subject: field is checked. {IFDATE:any text} Same as above, only the Date: field is checked. Perhaps you want special text automatically inserted into your messages on Fridays. I have no idea why! {IFNG:any text} Same as above, only the Newsgroups: field is checked. This one is possibly the most potentially useful; allowing custom headers or footer messages to be inserted when posting in certain newsgroups. Maybe. (For an example of how to use specific SIGs on individual newsgroups see IFFLAG below). {IFXN:any text} Same as IFNG except this one checks the X-Newsgroups: field. {IFCC:any text} Same as IFTO except this one checks the Cc: field. {IFBCC:any text} Same as IFTO except this one checks the Bcc: field. {IFRT:any text} Same as IFTO except this one checks the Reply-To: field. {IFFLAG:true/false} This tag needs a little more explanation. Consider the following example Yarn SIG file (explanation to follow): {IfNG:comp.os2}{ImpF:c:\yarn\os2.sig} {IfNG:comp.windows}{ImpF:c:\yarn\wind.sig} {IfNG:alt.books}{ImpF:c:\yarn\book.sig} {IfFlag:false}{IfTO:peri strange}{ImpF:c:\yarn\peri.sig} {ifFlag:false}{ImpF:c:\yarn\default.sig} As you have hopefully noticed, this example sig tests to see if the user is posting in the various newsgroups: comp.os.*, comp.windows.*, and alt.books.*; and if so then imports the appropriate SIG file you have created. There is a global "FLAG" which begins always set to "false". Whenever a conditional tag returns a "true" status the global flag is set to "TRUE". Therefore in line four of the above SIG example, you are first testing to see if any of the above conditions have already been met. If they have then the rest of line four is skipped. If a sig has not yet been imported (so the global flag is still False) then it is checked to see if the message is to your good friend "Peri Strange"-- who gets his own sig to amuse him. Finally on the last line it is checked again if no other conditions returned true this line will use the "random file" tag to import a default SIG file with the name as specified. (see the {IMPF:filename} tag in section 3). Lines beginning with an "if" tag as the first thing on the line will not output anything (ie. will not leave a blank line) if any conditions being tested fail before any text is printed. {SETFLAG:true/false} There might be some circumstance, however unlikely, where you need to set or reset the global flag. An example would be if you have custom headers that test for certain dates or newsgroups, and then at the bottom of the message have a SIG that does more tests. To reset the global flag to FALSE simply put the following tag on a line starting in column one: {SetFlag:false} The line will be skipped in the message output, but the flag will be set to False at that point. -6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6- Capturing Your URLs ------------------- This feature is disabled by default. To enable it uncomment the UrlLog = "c:\path\filename" line in the yep.cfg, and specify the path/filename you want to use. Once enabled, when Yep is scanning any message it will attempt to detect all URLs (Uniform Resource Locator, i.e. http://) and make a record of them to the log file specified. Along with the URL address it will record the date of the message, who it is from (if available), and/or the newsgroup(s) it was posted to. There is a new section in the yep.cfg labeled beginning with [URL EXLUCLUSIONS] (see the yep.cfg comments for more info). You can specify up to 25 URLs which commonly occur in your reply messages, so Yep will not keep capturing them each time. For example, you might want to put any URL which you have in your SIG into this list to keep it form being captured over and over and over and over and over again. If you want to capture the URLs in a message you are reading you will have to press Shift-R, as if you were going to reply. The URLs will be captured, and then exit your editor and press Escape, or C, to cancel the reply. A bit awkward, but it's the only way Yep gets an opertunity to scan the message. There are several tools provided to help manage your captured URLs. They are all REXX scripts with filenames beginning with YepU. Please see the YepU.DOC for details on each of them. Briefly, they include tools which will count, trim, filter and eliminate duplicates, as well as convert to HTML or Web Explorer URL Objects on your OS/2 WPS desktop. There is no special format to the Yep URL Capture Log. It is a plain text file which you are free to edit or modify as you wish. The entries for each record can be anything, and in any order. The only rules are that there must be at least one blank line between each URL record (and no blank lines in a record), and at least one blank line at the bottom of the Log File. In your YEP.CFG file there is a section where you can specify URLs to ignore -- so they won't be logged over and over again. This is useful especially if you have your web page(s) listed in your SIG! See the [URL EXLUSIONS] section of YEP.CFG. -7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7- UUencoding with Yep! -------------------- Have you ever reflected on the irony of how Yarn provides excellent built in support to attach a file to your message via MIME encoding. Yet to decode a MIME message you need an external program which can be finicky to set up. Yarn, on the other hand, has a very quick and easy built in method to extract and decode a UUencoded file found within a message at the touch of a button... yet Yarn has no way built in to UUencode a message! With one method you get easy encoding, but not decoding; with the other you get easy decoding, but not encoding! Yep provides a very quick and easy way to UUencode a file into your messages. When you are at the point in your message where you want to UUencode a file and insert it simply type the following code: {uuen:filename} The "filename" portion of the code would be, of course, the filename (and path if needed) of the file you want to insert. As soon as you exit your text editor Yep will notice the UUencode command tag and load the file, and using internal UUencoding routines, inject it into your message at that point. No fuss, no muss. Quick and easy. You will see a brown capitol "U" while Yep is importing and UUencoding the file, just to let you know it found the instruction and is attempting to preform it. -8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8- Of Specialized Tags ------------------- There were a few external programs being used which I decided to bloat Yep up a bit by making internal. The small external programs are still included in the package for backward compatability and flexibility; but if you use any of them it will be much faster to take advantage of the new internal routines. They are as follows: {EXPD:#} This tag will create a usenet timestamp # number of days in the future. This is useful for creating "Expires:" headers on your messages, if you so desire. An Expires: header, if you are not aware of them, specifies an expirey date at which time your message should be removed from news servers. There is no guarentee that they will be on that day, or before that date, but it gives you a chance at some control, at least. There are two reasons you may want to use this tag. The first reason is that perhaps you feel uncomfortable that there are searchable databases of news messages going back YEARS out there: anyone stalking you could track your usenet movements! I don't know if DejaNews and others will honour the Expires header, but they might. The other possibility is if you want distant future expiry date for your messages to make them last (perhaps annoyingly) long on news servers. I won't go into further details about how news servers expires messages. To create an Expires header in your messages you need to create a custom header that might look like this: Expires: {ExpD:7} With the above custom header all of your messages will be set to expire in one week (seven days). If you want to set up expiry dates for only certain newsgroups then you may want to use the conditional {ifNG:string} tag. For example, if you want all silly questions in the comp.* hierarchy to expire after five days you could make a header like this: {ifng:comp.}Expires: {ExpD:5} Note: the hard coded upper limit for your number of days possible until expiry is 1000. {DATE:string} (Note: This is a "special precedence" tag, see the section below on special precedences for more details) This is an implementation of the "DateTime" program. The "string" you give to this tag may contain a wide array of special substitution codes which allow you astonishing flexibility to output the current date and/or time any way you please, wherever you please (and also some other strange things, like the percentage of the year or day that has past so far, and other things. For example, the simplest way to print the entire current date and time in long form would be: {Date:It is now @t on @d.} This would print: It is now 4:21 am on Monday, February 16th, 1996. With different substitutions any format is possible. The complete table of possible date/time substitutions follows: @d - the full date (Monday, February 16, 1996) @t - 12 time of day (4:21 am) unit no lead ld zero ld spce Nth ---- ------- ------- ------- ---- month number - @m1 @m2 @m3 @m4 day of month - @d1 @d2 @d3 @d4 12 hour - @h1 @h2 @h3 @h4 24 hour - @H1 @H2 @H3 @H4 minute - @n1 @n2 @n3 @n4 second - @s1 @s2 @s3 @s4 hundredths - @u1 @u2 @u3 @u4 day of year - @a1 @a2 @a3 @a4 @y - year @y1 - 2 digit year @i - am/pm @i1 - AM/PM @i2 - Am/Pm @i3 - morning/afternoon/evening @M - month name @M1 - 3 letters @M2 - 2 letters @W - weekday name @W1 - 3 letters @W2 - 2 letters @W3 - num @W4 - Nth @p1 - % day gone @p2 - % year gone @t1 - tenth/Second {POM:#} The ever popular *new* Phase of the Moon program (POM.EXE) is now internal to yep. You may use this tag in headers or wherever. The # should be a value between 0 and 12, and represents how many decimal places of the moon's current phase should be shown. For example {PoM:4} would yield: The Moon is a Waxing Crescent (49.0512% of Full). {YPDEC:code} (Note: This is a "special precedence" tag, see the section below on special precedences for more details) This tag decrypts the given YP-Encrypted code and inserts it into your message. The YPEnc program to generate the encrypted codes is included with the Yep package, and has it's own little documentation file which you should refer to if you think you may use this feature. In a nutshell it is to make the storage of passwords (such as for use in tags with anonymous remailers) slightly safer (but not much more safer) from prying eyes. You would use the YPEnc program to generate the code and then save the code with this tag in your Yep.Cfg. See the YPEnc.Doc. {RNDN:#:#} This tag replaces itself with a random number in the given range. For example {RndN:2:6} will be substituted with a number between 2 and 6 (inclusive). Although I'm sure you may just want to generate random numbers in your messages for absolutely no reason except to admire the dazzling creative beauty of them, there are also some possible practical applications. This is a "special precedence" tag (see the section below on special precedences for more details). {RNDC:string} This tag replaces itself with a random character out of the given string. For example {RndC:aeiou} will be substituted one of the five vowels randomly. Who knows what you might use this for. I know what I use it for. (-: {Header:name} This tag prints out the current value of the 'named' header. The headers supported by this function are: To, From, Subject, Date, Newsgroups, X-Newsgroups, References, Reply-To, Sender. For example {header:subject} would be replaced by the current subject line. {header:newsgroups} would be replaced by the value of the "newsgroups:" header (if it exists). And so on. Special Precedence ------------------ A few of the tags above are given special precedence when a line of your message is scanned. What this means is that those special tags will be processed first, before any other tags. Yep is not recursive when it scans lines. What this means is that normally you can't include Yep tags inside other yep tags-- the inner tags will not be processed. However a few tags have been given the special ability to be used inside other tags. Namely: RNDN, RNDC, DATE, and YPDEC. Say, for example, you want to use a different SIG file for each day of the week. In your main SIG file you could put this tag: {ImpF:{Date:@W1}.sig} The DATE tag inside the IMPF (import file) tag will be processed first, and replaced with the @W1 date code (see the DATE tag for more details on date codes), which is the first three letters of the day of the week. So in the above example, on Monday the import tag would become {ImpF:Mon.sig}, on Tuesday it would then be {ImpF:Tue.sig}, and so on. You could also use other Date or Time codes to do other tricks like this. You could use the RNDN (random number) or RNDC (random character) tag to import random filenames which contain a range of numbers. Or you could import a random line from a file within a certain range of line numbers. YPDEC could be used to hide a filename in your sig, so it is not readable. I have no idea why you might want to do it-- but you could if you wanted to! -9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9- Block Processing & PGP, and More -------------------------------- Block processing is a procedure you can set up where you create your own tags that will identify blocks of text in a message. When you exit your text editor Yep will search for any "Blocks" enclosed by these tags and run a user defined process on them. The most common possible usage for this technique is for encrypting (ie. PGP, or another text encryption program) portions of your message. Other more whimsical uses can be left to your imagination. To set up block processing with Yep you need to edit the YEP.CFG. Specifically you define block process in the section labeled: [BLOCK PROCESSING DEFINITIONS]. There can be up to 15 blocks defined. For example to set up a block processing tag to run PGP one might use the following definition: "{pgp}"::"pgp -seat *i -o *o *p " This is more simple than it looks. Basically there are two sections to the line (the structure is the same as the "substitutions" section of the CFG). The first defines the tag, which in this case is {pgp}. This will mean that with this definition enabled whenever Yep is post-processing your message and sees the {PGP} (case doesn't matter) tag in the first column it will then process the rest of that block using the command given in the second half of the definition above (which will be explained in detail below). The command that is executed on the block must contain at least two substitution codes: *i and *o. These will be replaced by yep with the "input" and "output" filenames to be used. The third, optional substitution code you may use in your block command line is *p. *P will be replaced by any "parameters" you want to pass to your text processing program (please, keep reading for further explanation of how this works). So a detailed breakdown of the "pgp -seat *i *p -o *o" command above becomes more clear. The block will run the program "PGP" with command line options "-seat" (which tells PGP to sign and encrypt a text file with ascii output). The filename will be given to pgp in place of the *i, and the output of pgp will go to *o using pgp's "-o" switch. the *p in the line will be any additional parameters. you can use this to specify who you want to encrypt the message to right in your block command. So, how this works in the message you are writing is as follows. Let us assume there is a block of text you want to encrypt in your message you are writing to your friend George, you might write your message like this: Dear Peri, the weather here in Tibet is lovely. A llama spat in my eye yesterday (i mean the animal, not a buddhist monk, this time). And oh yes, by the way the secret word of the tetragrammaton is: {Pgp peri} well, i'll tell you when i get back. I fear the U.S. government may have paid off Zimmerman to get a back door put into PGP! {TheEnd} Wish you were here. Your Pal, Tim. So now you can see, the portion of text between the {pgp} tag and the {theend} tag (case does not matter), will be sent to the PGP program as you defined it. It will be encrypted. Note, all blocks terminate with the tag {TheEnd}, or at the end of the message. If you want the whole remaining portion of the message encrypted you do not need to include {theEND}. Note also that i did not simply use the tag: {Pgp}. In this example was used {Pgp Peri}. All text after the block tag, but before the closing of the tag, is considered "parameters". These are the mysterious parameters that will be sent to the program through the *p substitution in the block command definition. So in this case "peri" will be sent. In this case it is convenient to send the ID of the person you want to encrypt the file to that way, instead of being prompted for it by PGP if it is not included. The benefit of doing it this way is that you can encrypt a message to multiple recipients this way. For example if i wanted to encrypt that portion of the text to Peri, Joe, and myself, I could have called the block as: [pgp peri tim]. *TIP* Another good hint for using PGP blocks is to define the command like so: "pgp -seat *i -o *o tim *p". Notice I put my own name (a PGP ID really) in there. This will make every message I encrypt also be encrypted to myself (which means I will be able to decrypt my own encrypted messages if I should need to-- believe me, it has come in handy before!) Hopefully the above information gives you a good basic understanding of how the block processing works, and how to set it up. Following will be a few more details which are not necessary to know-- so if you are confused already you may want to read the above section over again, and skip the below section altogether. Details About Brackets or Tag Enclosures: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Blocks do not have to use square brackets to enclose them, you can use anything you want. You could have defined the pgp block as "[pgp]". But the essential thing to know about this technicality is that whatever characters you use to enclose your block command you must use the same characters to terminate your block. What i mean is that if you defined pgp with curly braces then to terminate the block in your message you also must use curly braces around "TheEnd", like so: [TheEnd]. Blocks May be Nested: ~~~~~~~~~~~~~~~~~~~~ Blocks can be nested inside blocks. I don't think I want to explain that except to say that it is allowable. (-: A possible use would be if you are sending a PGP encrypted message though the alpha.c2.org anonymous remailer. The remailer requires your message be encrypted to it, but also you want the message it sends inside that encrypted message to be encrypted. You following what I mean? You could have a message something like this... wait! Another thing about the alpha.c2.org remailer is that it does NOT want you to "sign" your encryption with PGP. So with Yep block definitions you could define two different PGP encryption tags which use different PGP command line options. For example, in addition to the definition shown above you might also do: "[pgpns]"::"pgp -eat *i -o *o *p " Notice the "s" option is missing from the command line. So in this case "pgpNS" might stand for PGP No Signing. ANd so you might encrypt your message like this: [pgpns alpha] header: your alpha-style required headers [pgp your_friend] Dear my_friend, i'm not sure if this is exactly how the alpha.c2.org anonymous remailer works, having never used it; but it is something like this so I thought i'd use it for an example anyhow. Notice that the first block uses the [pgpns] tag so that PGP envelope is not signed, but the pgp inside the pgp is signed, so to authenticate to your friend that the message is indeed from you. No [theend] is used because in this case we want the entire rest of the text encrypted, so it is not necessary. This is not a full description of how to use alpha.c2.org anonymous remailer; you will have to be creative and figure out how to apply these techniques yourself. (If anyone figures out a good procedure for this and wants to write it up, step by step, I'll include it in my docs). A Few More Details ~~~~~~~~~~~~~~~~~~ Any text on the same line following a block tag or a block terminal tag is ignored. -10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10- Anonymous Remailers ------------------- I have been having some discussion with one of the users of Yep about adding some support for automating posting messages through an anonymous remailer (specifically anon.penet.fi -- send a blank message to help@anon.penet.fi if you want more info about this service). (see the end of the section on block processing for more hints on how to use alpha.c2.org remailers) We were brainstorming a scheme to do this (well, i was more confused than anything), when it was realized that it turns out to be as simple as this: Set up the newsgroup you wish to regularly post annoymously in the same as you would set up a "pseudo-newsgroup" with Yarn. That is, run Yarn's NEWGROUP utility something like this: NEWGROUP rec.books.misc 7 30 rec.books.misc@anon.penet.fi Notice you are setting up this newsgroup to keep messages a default of 7 days, and a maximum of 30 days, and at the end you are telling Yarn that all posts to this newsgroup are to be E-MAILED to the anonymous remailer. Now if you are familiar with this remailer service then you will know (and if you aren't familiar with it you are probobly confused by now) that you usually need to use a password on your messages. This is done by adding a header like this: X-Anon-Password: your_password Yep can detect that the message being written is addressed to the anonymous re-mailer and add the password header line automatically if you set up a custom header like this: {ifto:anon.penet.fi}X-Anon-Password: password There, with Yep and Yarn you now have pretty much automated the task of coresponding in a newsgroup via this anonymous remailer. This could be useful, for example, if you are Salman Rushdie, hiding out from certain Iranians, but still want to be active in rec.books.misc! For a bit (but not much) more security Yep provides a way to "encrypt" your password in your Yep.Cfg so someone browsing the file won't be able to read it. See the {YPDec:code} tag somewhere above. Thanks to C.B. (now who could that be?!) for getting most of this figured out. -11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11- Of Finding Problems -- Troubleshooting -------------------------------------- Critical Errors ~~~~~~~~~~~~~~~ If there is any sort of critical error, Yep will create a file called "yep.err" with some details of the problem which you can email to me to report the bug. Other Problems ~~~~~~~~~~~~~~ If you have having problems with a filter or condition, or other Yep function, to test out your configuration I suggest creating a test message and running YEP from the command line on that message. This is the fastest way to run Yep and try to find out what is going wrong. The easiest way to create a test message is to go into Yarn and reply to a message. Then when in your editor save this reply to some text file to use for testing. (Keep a backup of this text file because if Yep is messing you up you will need to make more copies of it as you continue testing. Make sure the test message has a file extension of .msg or Yep will not interpret. As a last resort send me your configuration file and a test message (preferably zipped up), and an explanation of what you are trying to do, and i'll try and see what's going on for you. -12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12- History of Revision: ------------------- Version 1.6 - Nov ??, 1996 (this is a beta document) ----------- + Definable filename extentions, so YEP can be used with other mailers/newsreaders. See "Process=" in the YEP.CFG and the "Yep But Not Yarn" section of chapter 2 above. + Yep now STOPS on some tag errors (mostly file importing) and after printing an error message waits for you to press a key to continue. No more too-fast-to-read errors messages! + New tag: {RNDC:string}. Random characters! See chapter 8 above under "Special Tags", and also "Special Precedence". + Major new feature: Block Processing. See section 9 above. A few sample filters have been included for testing out this feature, including: pigsay - simple pig latin filter, rev-rexx - reverses each line of text, rep-rexx - replace letters or paterns with other letters or paterns. These are in the YX-*.ZIP archive included with the YEP archive. + Yep now searches your %HOME%\yarn\ directory for a yep.cfg file FIRST. If none is found there, then the directory yep.exe is executed from is searched (as earlier version do). Easier for multi-user to have individual config files in their home\yarn directories. (No changes necessary to your setup). + New tag: {RNDN:#:#}. Random number generator! See chapter 8 above under "Special Tags", and also "Special Precedence". + Certain tags now have "special precedence" and can be nested in other tags (only one level deep). See the section entitled "Special Precidence" (section 8) above. + New tag: {header:name}. This will print the value of certain specified headers. For example {header:subject} will print the value of the "Subject:" header. Headers supported are: To, From, Subject, Date, Newsgroups, X-Newsgroups, References, Reply-To, Sender. (this is intended for use with a possible kludge support for the alpha.c2.org anonymous remailer) + New support to reflow quotes which would normally go beyond the specified right margin. Still can be messy (as it's not FULL reflow support, but only reflows individual lines), but better yarn's usual (lack of) treatment. See the "RightMargin" and "QuoteChar" in the yep.cfg. Note: a RightMargin="0" disables this feature. + Along with the quote reflow support I've made made yep NOT interpret any lines beginning with the specified quote character, as it use to do on every single line before... This should speed up processing of LONG quoted replies significantly. + New small "trouble shooting" section of this doc + more conditional tags IFCC, IFBCC, IFRT. - the url grabber didn't recognize a tab as the end of an url. - cleaned up (restructured) a few routines - another minor extremely rare bug too complicated to explain. - Completely revamped the way all the File I/O channels were handled. This fixed an obscure bug that occured if you inserted a file import tag AFTER entering the text editor. It also increases memory use slightly, but should be more stable. - Increased stack size, just for a little more elbow room during file import recursions - UrlLog="" in the Yep.cfg would crash YEP - Uninitialised variable when exporting URLs caused instability. Version 1.5 - March 4, 1996 ----------- + New tag for automatically adding "Expires:" headers in case you want to specify how long your message should live out in cyberspace. See the {ExpD:#} tag in section 9 above. + A new feature: Automatic URL Logging. See the all new section 6 of this doc for details. No, not section 8, section 6! + new tag "Import Line Starting-With" {ImpLS:"string"::"filename"} see details in section 3. + scary new uuencode tag! You can now uuencode a file into your message with the ease of typing {uuen:filename}. As soon as you exit your editor the file will be uuencoded like lightning... right into your message; for those not partial to MIME. + Emacs header mode?? (see yep.cfg) [req. by huug@telebyte.nl] + The mysterious ImpLR (import line range) tag. + Added an {IfXN:string} conditional tag for testing the X-Newsgroups: header. [req. of Cheryl Buzzell] + Moved the Phase of the Moon program into Yep so it can be called with the tag {POM:#} where # is the number of decimal places. + Moved the "DateTime" utility into Yep so formatted date/time strings can be added to SIG's or whatever, without shelling. This subroutine can print other weird stuff like the percentage of the day used up so far, and so on... see the docs somewhere. + Added the YPEnc word encryptor into the package. It can be used to encrypt (sort of) passwords in the Yep.Cfg. See YPEnc.Doc. + Devoted a chapter of the doc to using Yep/Yarn and Anonymous Remail services (anon.penet.fi, anyhow). See the table of contents. ? Skipped version 1.4 for religious reasons. - bug bug where most "if" tags didn't work correctly if you had "cleanheader" turned on. Ouch. [Figured out by Han Willemsen J.Willemsen@Inter.NL.net] - some people were experiencing duplicate headers appearing when re-editing messages. Not sure why, but think it's fixed anyhow! [first reported by Jani Patanen (jpatanen@hit.fi)] - Custom headers were being stripped of leading spaces, which was not good for multi-line headers (where the lines after the first were indented... fixed (hopefully not breaking anything else). [alerted raised by Morten Frederiksen (mortenf@login.dknet.dk)] Version 1.3 - February 13, 1996 ----------- + new tag "Import Line Number" {ImpL:#:filename} - will import a specified line number of a text file. See section 3. + added a few more meaningful, english, error messages. (-; + faster, faster, faster. Yep should be noticeably faster (modified scanning routines), especially on long messages. - a bug in the "IfFlag" logic found and fixed [thanks to cherylb@tiac.net (Cheryl Buzzell) for help finding this one]. - the bug that almost killed me! Many thanks to the longsuffering tsawchuc@kestrel.punk.net (Tim Sawchuck) who reported the strange and mysterious "teh"::"the" substitution bug. After many, many trials and tribulations that could fill a long novel, suffice it to say-- it turned out to have nothing to do with that substitution (the symptom just shows up for Tim during it, but the bug (corruption) happens earlier), and this bug is officially (i hope) squashed, thank God, it nearly killed me. The problem, precisely, occurred if you used substitutions *IN* a custom header *AND* the replacement text was longer than the original text. I hope that clears it up for everyone! - andrews@jolt.mpx.com.au (Andrew Shipton) finally noticed that Yep wasn't allowing Yarn 'score' files to get passed through to the editor. Doh! Fixed now, more or less! Sorry about that. - better handling of {IfFlag:} and {SetFlag:} so that blank lines are not left in a situation like this: {ifflag:false}{ifng:yarn}This is the yarn mail list. Previously if this "yarn" was not found in the newsgroups: header then an awkward blank line would have been left behind. No more. Should work much better with long lists of conditions in SIGs or headers. Version 1.2 - February 4, 1996 ----------- - very unfortunate bug that kept version 1.1 from running AT ALL with the default yep.cfg due an error and bad parsing of the [substitutions] section of yep.cfg. Fixed. Sorry! (If you removed all blank lines from the yep.cfg it would work) Version 1.1 - January 31, 1996 ----------- + the old 255 character per line limit is now 50,000. + new yep.cfg directive: CleanHeader = "No"/"Yes" (see yep.cfg) [thanks to suggestion by someone whom I lost the email of] + new yep.cfg directive: ShowDots = "Yes"/"No" (see yep.cfg) + $l (lower case L) in yep.cfg Editor= statement sets cursor line number to the first line after the quotes in a reply. [thanks to suggestion by lennart.carlson@mailbox.swipnet.se] + bizarre new experimental conditional tags: please see section 5 of this document above for details if interested. + custom header lines increased from 12 to 50 + maximum substitutions raised from 25 to 100 + new yep.cfg directive: CursorAdjust (see yep.cfg) Version 1.0 - December 31, 1995 ----------- ? Released. Sort of. -13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13- Credits: ------- Yarn off-line news/mail reader of DOS and OS/2 (the reason we are gathered here today, dearly beloved) is by Chin Huang. (http://www.vex.net/yarn) Yes (Yarn Editor Shell) is by Per Goetterup and is a very good DOS program. You can check it out as well at... http://www.vex.net/yarn And lastly and leastly there's me: Tim Middleton (as544@torfree.net) Well gee, I guess I'll join the party at http://www.vex.net/yarn too! Sorry if this documentation is a bit crappy and not explained well. (-: Just email me if you need help, or post to the Yarn mailing list. ----------------------------------------------------------------- Yarn/2 Bells and Whistle's on the WWW http://www.vex.net/~x/bells2.phtml More good Yarn related Stuff!!! -----------------------------------------------------------------