TO: SCSI-2 Editors RE: Editing Conventions for Proposals and SCSI-2 Document 1. File Name Conventions The editor's have adopted the following conventions regarding naming of files. These conventions are in use on the SCSI-BBS. Your co-operation in complying with these conventions when submitting proposals is appreciated. The SCSI-2 working draft is named as follows: S2R2-01.___ | | -- | | |- section number (01 to 17) | |--- revision level of this file |----- version level of this scsi draftrevision The proposal documents are named as follows: 87-xxxRy.___ | | | | | |- revision of file | |---- document register number |------- year document submitted 1.1. File Extensions The following file extension conventions are in use. filename.ws - indicates file is in Wordstar format filename.txt - indicates an ASCII text file (i.e. no high order bits or WordStar formating) filename.prn - indicates a file that is formatted output of Wordstar. These files can be copied (redirected) to a printer to produce a hardcopy output. filename.arc - This is a compressed file or files. The 'arc' utility is necessary to uncompress the file if you have an MS-DOS or PC- DOS operating system. If you have a Macintosh computer see Area 2 of the SCSI-BBS for utilities to handle WordStar and compressed files. filename.exe - these are self-decompressing files. They are only used for floppy disks to distrubute the SCSI-2 document. 2. StarIndex The 'filename.ws' files are the source files for the STARINDX program. STARINDX automatically numbers sections, tables, and figures. This is done by using dot commands before each of these items: .ia - Next major section (1.0) .ib - Next 2nd-level section (1.1) .ic - Next 3rd-level section (1.1.1) .id - Next 4th-level section (1.1.1.1) [Maximum depth is 4] .ie - Next Figure in section .it - Next Table in section Unfortunately, STARINDX has several limitations: (1) The worst limitation is that it will not handle references to sections, tables, or figures. Larry and I have been using underscores "_" (e.g., see 8.1._) or leaving the reference unchanged from X3.131-1986. Another approach I used in a couple places is to use an underscore reference plus a mnemonic reference (e.g., see section 7.1._ [new section on unequal block sizes]). (2) The section numbers are not in the source files. This can make searching for sections awkward. You will probably need a hard copy handy to find other nearby unique strings. (3) On the line immediately following the dot command, the name of the section, table, or figure must appear without any other text. This means that we must deviate somewhat from the ANSI style. (4) While a file with the STARINDX dot commands can be printed, it will not have any section, table, or figure numbers. A better way to print such a file is to use STARINDX to make an indexed file (see below). (5) The maximum depth is 4 levels. Try to avoid going deeper than 4 levels. If you must go deeper than 4 levels, you will have to number these sections manually and they will not appear in the table of contents (probably shouldn't appear there anyway). Filename conventions used by StarIndx: S2Rr-nn.TXT - source file for section nn (00 - 15, A) [r is the revision] S2Rr-nn.SI - output file of STARINDX for section nn S2R2r-nn.TOC - Table of Contents file for section nn (output of STARINDX) It is fairly important to use the DOS DATE and TIME directives so that files will have the correct date and time. This is the only easy way to determine which file is the most recent version of the SCSI-2 draft standard. 2.1. STARINDX USAGE Included are two batch jobs (S1.BAT and STARSCSI.BAT) to STARINDX a section or the entire SCSI-2 draft standard. To use S1.BAT, make sure that the files STARINDX.COM, STARINDX.OVR, and SCSI.FMT are in the current directory along with the .TXT file to be indexed. Type: C> S1 S2Rr-nn.TXT (where nn is the section number) This will produce two new files SCSI2_nn.SI and SCSI2_nn.TOC. Both files need minor editing (using WordStar) before printing. STARINDX inserts a spurious .FO dot command near the beginning of the file in the .SI file (it is in uppercase - the "good" .fo dot command is in lowercase). You will need to delete the extra .FO dot command or else the footers will only have the page number. Also, the .TOC file is full of bold (^B) commands. I use a global replace command to delete all of these bold commands. If you want to STARINDX the entire SCSI-2 draft standard, use the STARSCSI batch job (first make sure that the same 3 files as above are in the current directory). It also produces a file named SCSI2ALL.TOC that includes all of the .TOC files. This file needs to be edited to remove the excess bold commands plus to put all of the sections together in the proper order. After fixing all of this, I insert this file into the proper place in SCSI2_00.SI. (Don't forget to remove the extra .FO dot commands from the SCSI2_nn.SI files.) The files are now ready to be printed. 3. STYLE CONVENTIONS Larry and I have adopted a few new style conventions to save trees and to improve readability (I'm sure someone will disagree). (1) Multiple-byte table entries are named only once and the hyphens do not go completely across the table between bytes in these fields (see the hard copy). If some bytes in a table entry have been omitted, the hyphens alternate with spaces. (2) Operation code values (and other constant values) are included in the table entry after its name (e.g., Operation Code (00h) ). The line above the CDB table for the operation code has been deleted. (3) We are making liberal use of "editors comments" within the text to remind us issues and work remaining to be done. These editors comments are in bold type to catch the reader's eye and they use square brackets for ease in WordStar searching [like this]. We really should write a detailed SCSI-2 style manual. (By the way, ANSI has a style manual for writing ANSI standards. I can make you a copy of mine if you want it.) 4. COMPRESSING FILES Uploading files to the SCSI-BBS can be less time consuming if you compress them first. There are two compression programs in use 'arc' and 'pkarc'. To compress a file follow the example below. Both programs accept wildcards for the 'filename' or 'ext' if you have multiple files to compress into one file. Example: A> arc a arcname filename.ext A> pkarc -otc a arcname filename.ext Please specify the `-otc` option if you are using 'pkarc' so that the compressed file can be decompressed using 'arc'. 5. USING ARC TO UNCOMPRESS FILES If you enter 'ARC' at the prompt with no parameters the minimal documentaion will be displayed on your screen. This disk contains the latest source files for SCSI-2 in compressed format. It also contains the achieve program to uncompress the files (ARC.EXE). Unpacking the SCSI-2 files can be accomplished in several ways: 1. If you have a hard disk (C:) and want to unpack all of the SCSI-2 files (about 900K bytes), put this disk in drive A: and type: A> ARC X SCSI2 C:*.* 2. If you want to extract a single file on a dual-floppy system, put this disk in drive A: and a formatted disk in drive B:. Type: A> ARC X SCSI2 B: A list of filenames in the archive file can be obtained by typing: A> ARC V SCSI2 ARC can do a lot of other valuable functions. It is a "freeware" program. If you continue to use it, the authors request a modest payment. There is not enough space on this disk to also give you the complete documentation on ARC (it's good, but it can't work miracles). 6. SCSI Bulletin Board System (316-688-8700) The SCSI Bulletin Board System (SCSI-BBS) is organized into areas. The contents of the areas are listed below. Area 1: X3T9.2 General Information. This area contains information on ANSC, CBEMA, X3, X3T9, and X3T9.2. Area 2: Communications Software. This area contains programs and information related to accessing the SCSI-BBS, and the utility programs for decompressing files. Area 4: NBS SCSI Verification Tests. This area contains the test suites developed by the National Buruea of Standards for testing compliance with SCSI. The use of these programs requires an SDS-1 or SDS-2 test system. Area 6: Miscellaneous. This area contains stuff that does not fit under another area. Area 7: SCSI Revision 17b. This area contains the files from the last public (i.e., not copyrighted) SCSI document. These are not exactly the text in the SCSI-1 ANSI standard, but they are close. Area 8: SCSI-2 Draft Standard. This area contains the draft working files for the SCSI-2 document. Area 14: IPI. This area contains files and information related to the IPI standards.