Document Text2Guide documentation Text2Guide Documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~ Release 03.10 © Stephan Sürken 1994 Closed 31 Oct 1994 0. Important ============= I have not done much testing with this new version - just some of my own files, and with them, this version did well. So please give me details about the fabulous crashes it produces on your machine. The program obviously had some problems on some machines...eh, I mean it did not work and produced some mysterious errors (mostly, the program seems not to do anything). However, I am quite sure to have located & fixed that bug (though it never occured on MY machine, so I could not test it). If you try to produce the output file in RAM:, the program will not work if the file does not exist already. Simply use Control-C to break the program, and use it again -- as text2guide will then have produced a zero-length output file of that name. Please DON'T ask me why it behaves like that :))) :-) (misplaced smily). See `:-)' for silly things. 0.1. Copyright & legal stuff ----------------------------- Text2Guide 02.XX, 03.XX is © Stephan Sürken 1993, 1994. Text2Guide is PUBLIC DOMAIN, that means you may copy and use it freely, but any gifts are welcome :-) For any comments, bug reports or similar stuff, contact me (see `The Author'). Note the following: o If you copy it, you MUST copy the whole original archive. o You may include this copy on any Public Domain Series, but you MUST NOT include it on any disk that is selled for more than 5 US Dollar (or an equivalent in other currencies). o The program must neither be used nor copied by any extremely right wing organisations or persons. 1. Installation ---------------- Well, it's a CLI-Tool. Copy it anywhere you like, perhaps to "c:". 2. Documentation ================= Text2Guide converts plain ASCII text into AmigaGuide (c) format. Sticking to some simple organisation of the text file one can simply realize a well structured guide file while still having a well readable text file at hand. 2.0. Introduction ------------------ After searching for a progam of this kind in various ftp sites for quite a time (without success), I decided to write it myself. Here it is! 2.1. Usage ----------- Text2Guide is a CLI-Tool. Type "Text2Guide" in a Shell and you'll get something like: --- Text2Guide 03.10 (31 Oct 1994) © Stephan Sürken Failed: Can't open input text file! SYNTAX: Text2Guide {+|-uwitoc} u: ignore Underline of units, default on. w: show Warnings, default on. i: show progress Information, default off. t: perform node Test, default on. o: force Overwrite of output file, default off. c: write table of Contents, default on. --- That's rather self-explaining, isn't it?? See `Options' for exact meaning of the options. 2.2. Text file organization ---------------------------- There are following rules for the text file: o The document starts with the keyword "Document" at the beginning of the first line. The rest of this line will be taken as name of the AmigaGuide database. In the document you are reading this is in the first line (where it MUST be). o You have to divide your text document in units. These units must start at the beginning of a line, and consist of arabic numbers divided by dots. Whole hierarchical relations are recognized. The rest of the line after this unit number will be taken as title of this unit. Examples: 1. Einleitung -> unit number: "1", title : "Einleitung" 4.2.1. Das Spiel beginnen -> unit number: "4 2 1", title : "Das Spiel beginnen" o Lines that are neither the first document line nor start with a unit number are texts. In texts, there may be links to other units, e.g. like `Test Link'. Such links start with an "`"-character and end with an "'"-character, containing the title of the required unit. Such links must be in one line. Example: Please look at this document as example! ~~~~~~~~ 2.2.1. Test Link ----------------- You have clicked on the test link, so you are now in this chapter. Simply retrace or click `Text file organization' to get back. 2.3. Options ------------- These options can be supplied to Text2Guide as arguments after the input and output file name. "-" will put off an option, "+" will put it on. Option u: ignore underline lines, default on. ~~~~~~~~~ If this option is on, lines directly following to lines with unit numbers are ignored. That is to let you underline such units in the plain text file. For example this unit is defined in the text file by these two lines: 2.3. Options ------------- If option u would be off, you would see the "-------------" at the top of the window in the guide document... Option w: out warnings, default on. ~~~~~~~~~ If this option is on, warnings are written, else not. You should normally not put this off. Option i: show progress information, default off. ~~~~~~~~~ If this option is on, evrey scanned resp. written unit title will be printed while the convertion is in progress. Option t: test for multiple nodes, default on. ~~~~~~~~~ If this option is on, Text2Guide will perform a test for multiple defined nodes (->units) after scanning, and produce warnings if multiple nodes are found. Since version 3.00, two tests will be performed: for multiple node ids (the unit numbers, e.g. "1.2.") and for multiple node titles (e.g. "Introduction"). Due to the intern test routine, the warnings will be printed as often as the multiple id's (resp. titles) appear in the text file... NOTE that with "t" on and "w" off the test will be performed but no warnings written. (310) Option c: write table of contents, default is on. ~~~~~~~~~ If this option is on, Text2Guide will produce a table of contents and place it in the guide file. Example: Text2Guide Text2Guide.doc Text2Guide.guide -wt +u ~~~~~~~~ This will recompile this document; no warnings will be written and not multiple node test will be performed; underlines of units will be omitted ("+o" is obsolete as its default is on). 3. History =========== 3.1. Release 01.00 ------------------- Initial Release. A one-night-work. Undocumented. Included on the VideoMaxe Release 04.12. 3.2. Release 02.00 ------------------- Major update. o improved whole program structure... o can now convert links in texts o multiple node test o argument line `options' 3.3. Release 02.01 ------------------- o made lines Text2Guide can process bigger: from 80 chars to 160 chars. (had some problems with longer links...) o nodes were NOT prolonged by " ", text links were; this should be the other way round and is now. 3.4. Release 03.01 ------------------- Date: 25 Apr 1994 Major Update. o Now all strings are dynamic - no more fussing about with line length, no more limitations. Please allow it to be somewhat slower therefore! o Now the process is divided into three main parts: (i) Scanning the text file. (ii) Testing integrity. (iii) Writing guide file. o Nodes are now identified with the unit number, no longer with its title. E.g.: "1. Introduction" used to become "@{" Installation " Link Installation}" [klick no use!] will now become "@{" Installation " Link 1.}" [please klick!] Thus, the guide file will be somewhat smaller and you might address a node by its number - no matter what label it has. Useful for example if you have two similar guide files in two different languages and you want to address the "Introduction" or the "Einleitung", respectively. You can now adress it via "1.", no matter what file is used. o Added options "i" (-> progress information) and "o". (jo!). Will now automatically overwrite existing output file only if "o" is set - else you will be requested. Just as it should be! o Program can now be interrupted via "ctr-c". o Better testing, better output, better warnings. 3.5. Version 03.02 ------------------- Date: 14 May 1994 Private Update. o Slightly changed the info output. 3.6. Version 03.10 ------------------- Date: 31 Oct 1994 Minor Update. o Removed an odd bug that would hinder Text2Guide to work on some machines. o Added "table of contents"-feature. o Spaces at the end of a unit name are now ignored. o Scanning speed increase (about 40%). 4. The Author ============== The author is me and I am the author. Send your gifts to: |-----------------------------------------------------------| | ADDRESS | |···························································| | Stephan Sürken | | Kurt-Schumacher-Str. 34 A 161 | | D-67663 Kaiserslautern | |-----------------------------------------------------------| |-----------------------------------------------------------| | E-MAIL (InterNet) | |···························································| | suerken@student.uni-kl.de | | s_suerke@informatik.uni-kl.de | |-----------------------------------------------------------| |-----------------------------------------------------------| | BANK ACCOUNT | |···························································| | o Stadtsparkasse Kaiserslautern, FRG | | o Bankleitzahl (BLZ) : 540 501 10 | | - Bildschirmtext (BTX) : *966750# | | - SWIFT-Code : KLTS DE 55 BiC | | o Account-Number/Konto-Nummer: 128 029 758 | |-----------------------------------------------------------| Enjoy, -Stephan 5. :-) ------- [ ] Der viereckige Hai. Hat er ja selbst so gewollt. ^ Da ist er drin.