8bitfiles.net/archives

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

/ 8bitfiles.net/archives / archives.tar / archives / genie-commodore-file-library / C128Toolkit / INDEXER.ARC / INDEXER.DOC next >

Wrap

Text File | 2019-04-13 | 16.4 KB | 702 lines

┼.╟. ┬ELL ╔NDEXER ╧VER THE YEARS, THE MOST FREQUENT COMPLAINT ╔ HAVE SEEN ABOUT SOFTWARE IS IN REGARD TO THE DOCUMENTATION. ╟OOD DOCUMENTATION PLAYS A LARGE PART IN THE SUCCESS OF A PROGRAM. ╨EOPLE HAVE TO KNOW HOW TO USE IT. ┴T BEST, A POORLY DOCUMENTED PROGRAM WILL NOT BE FULLY UTILIZED. ┴T WORST, IT WILL NOT BE USED. ╙UCCESSFUL DOCUMENTATION INVOLVES FAMILIARITY WITH THE PROGRAM AND ABILITY TO EXPRESS THE FEATURES, FUNCTIONS, AND REQUIREMENTS CLEARLY. ┴ CERTAIN AMOUNT OF STYLE GOES A LONG WAY TOWARD MAKING IT INTERESTING ALSO. ╘HOUGH STYLE AND THE ABILITY TO CONVEY THE INFORMATION REST WITH THE DOCUMENTER, THERE ARE TWO FEATURES YOU WILL FIND IN VIRTUALLY ALL GOOD DOCUMENTATION WHICH ANYONE CAN DO PROFESSIONALLY, AND WITH ╔NDEXER, EASILY. ╘HESE FEATURES ARE A TABLE OF CONTENTS AND AN INDEX OF KEY WORDS WHICH SERVE AS A QUICK REFERENCE TO THINGS COVERED IN THE TEXT. ─OCUMENTATION IS TEDIOUS AT BEST, EVEN FOR THE PERSON WHO CREATED THE PROGRAM. ├REATING A TABLE OF CONTENTS MAY PROVE TO BE A RELATIVELY PAINLESS TASK FOR SHORTER DOCUMENTS OR THOSE WHICH DON'T CHANGE OFTEN, BECAUSE YOU ARE USUALLY DEALING WITH A LIMITED NUMBER OF ENTRIES. ┴N INDEX, ON THE OTHER HAND, IS A ╔NDEXER / ┼.╟. ┬ELL / 2 POTENTIAL NIGHTMARE FOR A SIZABLE PROJECT. ╘HIS IS A NIGHTMARE ╔ FACED. ─OCUMENTATION FOR ONE OF MY PROGRAMS IS IN EXCESS OF 190 THOUSAND BYTES, AN 85 PAGE DOCUMENT. ╔T IS DIVIDED INTO 39 SECTIONS, EACH REFERENCED IN MY TABLE OF CONTENTS. ╘HERE IS AN INDEX OF 102 WORDS AND PHRASES WHICH SERVE AS QUICK REFERENCES TO VARIOUS FEATURES AND FUNCTIONS DOCUMENTED IN THE TEXT. ╔T IS MADE UP OF SIX LINKED FILES, THREE OF WHICH EACH CONSUME THE WHOLE BUFFER IN ╘HE ╫RITE ╙TUFF. ╔ WANTED A PROFESSIONAL MANUAL. ═Y DECISION, MY METHOD, WAS TO 'PRINT' THE WHOLE DOCUMENT TO DISK AS ╧╬┼ SEQUENTIAL FILE. ═Y DOCUMENTATION, IN THIS FORMAT, TAKES UP 700 DISK BLOCKS. ╚OW WOULD YOU LIKE TO INDEX THAT? ╔ SELECTED THIS SEQUENTIAL FILE FORMAT BECAUSE IT ALLOWED ME TO IGNORE CONTROL AND ESCAPE SEQUENCES PARTICULAR TO VARIOUS WORD PROCESSORS AND CONCENTRATE ONLY ON THE TASK ╔ REALLY NEEDED PERFORMED. ╘HE FILE WAS ON DISK EXACTLY AS IT WOULD BE ON PAPER, IN ONE PACKAGE, READY TO YIELD THE INFORMATION ╔ WANTED. ╔N ADDITION, THIS MADE THE PROCESS AVAILABLE TO ┴╬┘ WORD PROCESSOR ABLE TO 'PRINT' DATA TO DISK IN SEQUENTIAL FORMAT. ╔N THIS REGARD, THERE IS ONE CAUTION. ╔F YOU HAVE MADE USE OF FORMATS A DISK CAN'T RECOGNIZE, ITALICS, UNDERLINING, AND SUCH, MAKE A COPY OF THE FILE WITHOUT THESE BEFORE CREATING YOUR ─OCUMENT FILE. ╘HINGS LIKE CENTERING, MARGINS, PAGE LENGTH, ETC. REQUIRE NO SUCH CONSIDERATION HOWEVER. ╔N ADDITION, OBVIOUSLY FOR FILES THE SIZE OF MY DOCUMENTATION FILE, YOU'LL ╔NDEXER / ┼.╟. ┬ELL / 3 NEED A 1571 OR 1581. ┬UT FOR FILES UP TO 664 BLOCKS, YOU CAN USE A 1541. ╔NDEXER PROCESSED MY 720 BLOCK DOCUMENTATION FILE IN ONLY SEVEN MINUTES. ╘HAT INCLUDED THE 39 ENTRY TABLE OF CONTENTS AND OVER 750 PAGE-REFERENCES FOR THE 102 WORDS/PHRASES. ╘HE SEARCH WORDS SPANNED A WIDE SPECTRUM, FROM ╥┼╒ TO ═ODEM ╙ELECTION. ┘OUR RESULTS WILL BE DIFFERENT, AFFECTED BY THE LENGTH AND FORMAT OF YOUR DOCUMENT, THE WORDS AND PHRASES YOU SPECIFY, ETC. ╧NE THING, HOWEVER, WILL BE THE SAME. ┘OU'LL BE PLEASED WITH THE RESULTS! *** ╫HAT ┘OU ╟ET ╘HE OUTPUT CAN BE IN ├┬═ ┴╙├╔╔, ╨ET ┴╙├╔╔ [AS USED BY ╙PEEDSCRIPT AND ╘HE ╫RITE ╙TUFF], OR ╘RUE ┴╙├╔╔, IF THAT IS REQUIRED. ╘HIS WAS TO ALLOW EASY FORMATTING OF THE FINISHED FILES WITH A WORD PROCESSOR IF DESIRED. ╔F YOU SELECT ├┬═ [BY NOT SELECTING ╘RUE OR ╨ET] OR ╘RUE ┴╙├╔╔, YOU CAN ALSO USE ╔NDEXER TO DUMP EXISTING ╔NDEX AND ├ONTENTS FILES TO PRINTER. ╩UST FOLLOW THE PROMPTS. *** ─OCUMENT ╨REPARATION ╔ ORIGINALLY CONSIDERED DOING ALL OF THIS SEARCHING IN ╥┴═ BUT, AS ╔ MENTIONED PREVIOUSLY, SOME OF MY FILES WERE JUST TOO LARGE. ╔N ADDITION, THIS WOULD HAVE REQUIRED PROCESSING OF LINKED FILES, FORMAT COMMANDS, ETC. ╔ FELT THIS WOULD BE TOO MUCH ╔NDEXER / ┼.╟. ┬ELL / 4 WORK, DUPLICATING FUNCTIONS THE WORD PROCESSOR ALREADY PERFORMED. ╘HUS, THE INDEX AND THE TABLE OF CONTENTS ARE CREATED FROM A DOCUMENT FILED ON DISK. ╘HIS CAN BE AS LARGE AS A DISK WILL ALLOW, UP TO 3160 BLOCKS FOR A 1581 DRIVE. ╘HE TEXT FILE TO BE PROCESSED MUST BE CALLED ─OCUMENT. ┴S STATED PREVIOUSLY, ╔NDEXER REQUIRES THIS FILE TO BE IN SEQUENTIAL FORMAT, LITERALLY PRINTED TO DISK INSTEAD OF THE PRINTER. ╞OR EXAMPLE, IF YOU ARE USING ╙PEEDSCRIPT, FIRST PRESS ╙HIFT-├ONTROL-╨. ╘HEN, AT THE STATUS LINE PROMPT, PRESS '─' FOR DISK. ├ALL THE FILE ─OCUMENT. ╔F YOU USE ╘HE ╫RITE ╙TUFF, USE THE ^ TO PUT THE CURSOR ON THE STATUS LINE, THEN MOVE THE BLOCK CURSOR OVER ╨RINT. ┴T THE NEXT MENU, MOVE THE BLOCK CURSOR OVER ─ISK AND, AGAIN, CALL THE FILE ─OCUMENT. ╔F YOU ARE PROCESSING A GROUP OF LINKED FILES, ANSWER '┘┼╙' WHEN ASKED. ╒SING THIS METHOD, ALL CONTROLS AND WORD-PROCESSOR-SPECIFIC FUNCTIONS ARE TAKEN CARE OF BY THE PROGRAM DESIGNED TO TAKE CARE OF THEM. *** ╨REPARING THE ╙EARCH ╞ILE ╘HE SEARCH FILE MUST BE CALLED ╫ORDFILE ON THE DISK AND CONSISTS OF UP TO 254 WORDS OR PHRASES. ╘HEY SHOULD BE SORTED BEFORE BEING USED TO SEARCH. ╘HEY CAN BE UP TO 20 CHARACTERS IN LENGTH, LETTERS, NUMBERS, PERIODS, OR HYPHENS, AND CAN INCLUDE EMBEDDED SPACES. ╘HE PERIOD AND HYPHEN ARE THE ONLY TWO ╔NDEXER / ┼.╟. ┬ELL / 5 PUNCTUATION CHARACTERS NOT STRIPPED OUT WHEN THE FILE IS READ IN. ╔F YOU USE A WORD PROCESSOR TO CREATE THIS FILE, YOU SHOULD SET YOUR LEFT AND TOP MARGINS TO ZERO, AND PAGE LENGTH TO 255. ╘HIS CUTS OUT SOME PRELIMINARY WORK STRIPPING SPACES. ├UTTING WORK CUTS TIME. ┘OU COULD JUST AS EASILY USE A SEQUENTIAL FILE EDITOR TO CREATE THIS FILE, BUT SORT IT BEFORE USING IT. ╘HE ORDER IN WHICH THE WORDS OCCUR IN THE FILE IS THE ORDER IN WHICH THEY WILL OCCUR IN THE INDEX. ╘HE LAST CHARACTER IN THE FILE MUST BE AN ASTERISK '*' CHARACTER. ┘OU CAN HAVE AS MANY AS YOU LIKE. ╔ USE A WHOLE LINE OF THEM. *** ╧UTPUT ─RIVE ╙PECIFICATIONS ╔NDEXER CREATES 2 FILES, ONE CALLED ├ONTENTS AND THE OTHER CALLED ╔NDEX. ╘HE FIRST SPECIFICATIONS YOU MUST MAKE ARE THE FOUR DEVICE NUMBERS FOR THE INPUT AND OUTPUT FILES. ┘OU MAY CHOOSE EITHER EIGHT OR NINE FOR ANY OF THE INPUT OR OUTPUT FILES. ╞OR EXAMPLE, YOU COULD HAVE BOTH OF YOUR INPUT FILES ON DRIVE NINE AND BOTH OF YOUR OUTPUT FILES ON DRIVE EIGHT. *** ╧UTPUT ╞ILE ╞ORMAT ╙PECIFICATIONS ┘OU HAVE SOME FLEXIBILITY IN THE OUTPUT FORMAT OF THE FILES. ┘OU MAY SPECIFY ╨ET ┴╙├╔╔ [╙PEEDSCRIPT, ╘HE ╫RITE ╙TUFF, ETC.], ╘RUE ┴╙├╔╔, OR SEQUENTIAL IF YOU DON'T SELECT EITHER ╨ OR ╘. ╔NDEXER / ┼.╟. ┬ELL / 6 ╔F YOU SELECT '╨' FOR ╨ET ┴╙├╔╔, YOU WILL ALSO HAVE TO SELECT THE ├ARRIAGE ╥ETURN CHARACTER YOUR WORD PROCESSOR USES. ╞OR EXAMPLE, ╙PEEDSCRIPT AND ╘HE ╫RITE ╙TUFF USE ├╚╥$(31). ╨LEASE NOTE! ╘HIS SETTING IS ONLY FOR OUTPUT, ╬╧╘ INPUT. ╘HE ─OCUMENT FILE MUST BE IN ├┬═ [OR ╘RUE] ┴╙├╔╔. ┘OU SHOULD BE ABLE TO READ IT NORMALLY WITH A SEQUENTIAL FILE READER. ╔T IS THE ├ONTENTS AND ╔NDEX FILES WHICH WILL BE WRITTEN IN ╨┼╘ [OR ╘RUE] ┴╙├╔╔. *** ╨AD ├HARACTER ┘OU WILL SELECT THE PAD CHARACTER FOR THE INDEX LINES. ┘OU CAN CHOOSE BETWEEN A SPACE CHARACTER AND A PERIOD. ╞OR EXAMPLE: ┬UFFER ................... 1,3,4,5,7,10,11 OR ┬UFFER 1,3,4,5,7,10,11 *** ╠INE AND ╨AGE ╙PECIFICATIONS ┘OU WILL SELECT THE STARTING PAGE NUMBER. ╨LEASE NOTE! ┘OU WILL ALWAYS READ FROM THE BEGINNING OF ─╧├╒═┼╬╘ TO THE END. ┘OU ARE JUST BEING ASKED HERE TO INITIALIZE THE PAGE COUNTER. ╔N THE '┬UFFER ...' EXAMPLE ABOVE, IF YOU SELECTED 7 AS THE STARTING PAGE NUMBER, ALL OF THE PAGE NUMBERS WOULD HAVE BEEN SIX PAGES HIGHER. ╟ET IT? ╨AGE ONE WOULD HAVE BEEN PAGE SEVEN, ETC. ┘OU WILL SPECIFY THE FIRST LINE TO SEARCH ON EACH PAGE. ╘HIS IS THE LINE ON THE PAGE WHERE SEARCHING ACTUALLY BEGINS. ╘HE DEFAULT IS LINE FIVE, WHICH IS A COMMON TOP MARGIN FOR WORD ╔NDEXER / ┼.╟. ┬ELL / 7 PROCESSORS. ╘HIS LETS YOU SKIP HEADERS, A GREAT TIME-SAVER. ┘OU WILL SPECIFY THE LINES PER PAGE. ═EASURE YOUR PAPER FROM TOP TO BOTTOM AND MULTIPLY THAT FIGURE BY SIX. ─EFAULT IS 66, FOR STANDARD 8.5 BY 11 INCH PAPER. ┘OU WILL SPECIFY THE LINE ON WHICH TO STOP THE SEARCH OF A PAGE. ╘HE DEFAULT IS LINE 61, A COMMON BOTTOM MARGIN SETTING. ╘HIS ALLOWS YOU SO SKIP FOOTERS. ╞INALLY, SPECIFY THAT YOU WANT TO SEE OR NOT SEE THE LINE NUMBER PROCESSING. ╘HIS IS THE DISPLAY OF THE LINE NUMBER BEING SEARCHED. ╔T IS PRACTICALLY USELESS, BUT DOES GIVE THE IMPRESSION OF GREATER SPEED WHEN YOU SEE IT. ╧DD, HUH! ╫HEN IT IS OFF, YOU ACTUALLY SHAVE TIME FROM OVERALL PROCESSING BUT IT ╙┼┼═╙ TO TAKE LONGER. *** ╘HE ╘ABLE OF ├ONTENTS ├REATING AN INDEX WAS A SIMPLE MATTER OF PARSING EACH LINE FOR OCCURRENCES OF SPECIFIED WORDS. ├REATING A TABLE OF CONTENTS IS JUST A LITTLE TRICKIER. ╚OW DO YOU SPECIFY A LINE AS DIFFERENT FROM ANOTHER. ╘HIS IS THE LONE SPECIAL REQUIREMENT OF ╔NDEXER. ╘HE TABLE OF CONTENTS IS CONSTRUCTED OF LINES WITHIN THE BODY OF THE DOCUMENT. ╘HESE LINES MUST HAVE THREE ASTERISKS AND A SPACE AS THE FIRST PRINTING CHARACTERS OF THE LINE. ╞OR EXAMPLE: ╔NDEXER / ┼.╟. ┬ELL / 8 *** ╙ECTION ╔╔╔ ╙AWDUST ╔SN'T ─IRT ╘HIS WHOLE LINE, EXCLUDING THE FIRST THREE ASTERISKS, WOULD MAKE UP THE TABLE OF CONTENTS ENTRY, PRECEDED BY THE PAGE NUMBER. ╙O IF THIS LINE APPEARED ON PAGE TEN, THE TABLE OF CONTENTS ENTRY WOULD BE: 10 ╙ECTION ╔╔╔ ╙AWDUST ╔SN'T ─IRT ╔ CHOSE NOT TO INDEX WORDS IN THESE ENTRIES BECAUSE THEY ARE INDEXED, IN EFFECT, IN THE TABLE OF CONTENTS. *** ╞AST AND ┼VER ╞ASTER ┘OU MAY BE ABLE TO IMAGINE WHAT A TASK IT IS TO PARSE EACH CHARACTER OF EACH LINE, SEARCHING FOR MATCHING CHARACTERS IN EACH SEARCH WORD. ╙OME METHODS HAD TO BE DEVELOPED TO EXPEDITE THE PROCESS, AND YOU MAY FIND IT INTERESTING TO KNOW WHAT IS GOING ON DURING THE SEARCH. ╙PACES AND MOST PUNCTUATION ARE STRIPPED FROM THE INCOMING ─╧├╒═┼╬╘ LINES, AND FROM THE SEARCH FILE AS WELL. ╘HIS ELIMINATES POTENTIALLY THOUSANDS OF COMPARISONS IN EACH LINE. ╘HERE IS ONE POSSIBLE SIDE EFFECT OF THIS OF WHICH YOU SHOULD BE AWARE. ╔F YOU ASK FOR ALL OCCURRENCES OF THE WORD '╞ORMAT', ╔NDEXER WILL FIND IT IN 'IN╞╧╥═┴╘ION', AND '... THE LINES ╞╧╥═ ┴╘ THE CORNER.' ╘HIS SHOULD CAUSE NO PROBLEM THOUGH, BECAUSE ╔NDEXER / ┼.╟. ┬ELL / 9 AN INDEX BY NATURE IS COMPRISED OF VERY SPECIFIC WORDS AND PHRASES, NOT JUST COMMON, EVERYDAY LANGUAGE. ┼XAMPLES LIKE THIS SHOULD BE VERY INFREQUENT. ┴LL THE ONES YOU WANT WILL STILL BE FOUND. ╔NDEXER MAY JUST PROVIDE YOU WITH AN ODD FEW WHICH YOU DIDN'T REALLY ASK FOR. ┼VERYTHING IS CONVERTED TO LOWER CASE AT THE VERY START. ╘HIS ENABLES ME TO LOCATE ┴╠╠ OCCURRENCES OF SPECIFIED WORDS OR PHRASES WITHOUT HAVING TO TEST FOR UPPER AND LOWER CASE. ╫HEN THE ENTRIES ARE WRITTEN TO THEIR RESPECTIVE FILES, THEY ARE WRITTEN AS THEY ARE FOUND IN THE ORIGINAL FILES . ┴S THE LINES ARE READ IN, IN ADDITION TO BEING PURGED OF SPACES, PUNCTUATION, AND UPPER CASE CHARACTERS, ╔ BUFFER THE POSITION IN THE LINE OF THE FIRST OCCURRENCE OF EACH LETTER OF THE ALPHABET IN THAT LINE. ╫HAT THAT MEANS IN SIMPLE LANGUAGE IS THAT IF THE LETTER 'E' FIRST APPEARS IN POSITION 15 OF THE LINE, ╔ RECORD THAT. ╘HEN WHEN SEARCHING, ANY WORD STARTING WITH AN 'E' STARTS THE SEARCH AT POSITION 15. ╔F THERE ARE NO WORDS IN A LINE STARTING WITH THE FIRST LETTER OF THE CURRENT SEARCH WORD, ╔ DON'T SEARCH FOR IT. ┴S THE WORD FILE IS READ INTO MEMORY, ╔ RECORD THE LENGTH OF THE SHORTEST WORD. ╫HEN READING IN EACH LINE, ╔ RECORD THE NUMBER OF CHARACTERS IN THAT LINE. ╔F THE LINE IS SHORTER THAN THE ╔NDEXER / ┼.╟. ┬ELL / 10 SHORTEST WORD/PHRASE IN THE SEARCH FILE, ╔ MOVE TO THE NEXT LINE. ╫HEN LOADING THE 'SEARCH BUFFER' WITH THE WORD TO BE LOCATED, ╔ RECORD THE LENGTH OF THAT WORD. ╘HEN, WHEN SEARCHING THE LINE, ╔ ONLY SEARCH TO THE FARTHEST POSSIBLE POINT IN THE LINE WHERE THAT WORD COULD OCCUR. ╞OR EXAMPLE, IF THE WORD ╔'M SEARCHING FOR IS TWELVE CHARACTERS LONG AND ╔ ONLY HAVE ELEVEN MORE POSITIONS LEFT IN THIS LINE, ╔ MOVE TO THE NEXT WORD. ╔ KEEP A SET OF REGISTERS TO FLAG WHEN A WORD HAS BEEN FOUND ON A PAGE. ╔F ╔ FIND IT ON A PAGE, ╔ DON'T LOOK FOR IT AGAIN UNTIL THE NEXT PAGE. ╔F ╔ FIND ALL SEARCH WORDS ON A PAGE, ╔ FORCE PROCESSING TO THE NEXT PAGE. ┴S ALREADY MENTIONED, ╔ PROVIDED A MEANS OF SETTING THE STARTING LINE FOR EACH PAGE, THE NUMBER OF LINES PER PAGE, AND THE LAST LINE TO SEARCH. ╘HIS ALLOWED ME TO AVOID SEARCHING HEADERS OR FOOTERS. ╘HE DEFAULTS ARE LINE FIVE TO START AND LINE SIXTY-ONE TO STOP. ╘HE INDEX IS WRITTEN AFTER THE SEARCH FROM A TABLE CREATED BY THE SEARCH. ╘HIS ELIMINATES ═┴╬┘ ╦ERNAL CALLS OPENING CHANNELS, WRITING CHARACTERS, CLEARING CHANNELS, ETC. ╘HE TABLE OF CONTENTS FILE, ON THE OTHER HAND, IS WRITTEN DURING THE EXECUTION OF THE SEARCH. ╔T IS INVARIABLY LESS TO WRITE. ╔NDEXER / ┼.╟. ┬ELL / 11 ╨ERHAPS THE MOST DRAMATIC INCREASE IN SPEED WAS ACHIEVED BY ELIMINATING THE SCREEN DISPLAY OF THE LINES AND SEARCH WORDS DURING THE SEARCH. ╬OW ALL YOU SEE IS THE LINE NUMBER [IF SPECIFIED], THE PAGE NUMBER, AND THE NUMBER OF ENTRIES LOCATED. ┴ 'WRITING' MESSAGE WILL TOGGLE BETWEEN NORMAL AND REVERSED CHARACTERS EACH TIME A TABLE OF CONTENTS MESSAGE IS DISPLAYED. ╬ONE OF THESE IS NECESSARY TO ╔NDEXER, BUT WERE PROVIDED STRICTLY AS A MONITOR TO LET YOU KNOW SOMETHING IS HAPPENING. *** ╘HE ╨AYOFF ╔NDEXER WILL GIVE YOUR DOCUMENTATION A PROFESSIONAL TOUCH YOUR WORK DESERVES, QUICKLY AND EASILY. ╔T WILL MAKE YOUR DOCUMENTATION, AND YOUR PROGRAMS, EASIER TO USE... MORE FULLY- USED... PERHAPS MORE WIDELY USED. ╘RY IT! ┘OU'RE GONNA LOVE IT! EGB