home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / s / strongtest / ReadMe next >
Text File  |  1996-01-14  |  7KB  |  146 lines
  1. ReadMe file for StrongTest 1.00 (13-Jan-1996)
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. What is StrongTest?
  5. ~~~~~~~~~~~~~~~~~~~
  6.      Well, put simply, StrongTest is a simple utility that 
  7. attempts to test whether a stronghelp manual is internally 
  8. 'consistent'. By 'consistent' I mean that all the links to pages 
  9. can actually get to the pages they're supposed to, and that there 
  10. are no pages that can't be reached.
  11.  
  12.      The StrongTest distribution consists of the following 
  13. files/applications:
  14.           StrongTest     the executable
  15.           c.strongtest   the ANSI C source code
  16.           !strongtst     a DDE frontend for the executable
  17.      I (Musus Umbra) retain copyright in the program at all 
  18. times. Permission is granted for unrestricted use. Permission is 
  19. granted for distribution provided that no profit is made and that 
  20. the distribution is supplied whole and unaltered.                    
  21.  
  22. But what if I patch a bug?
  23. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  24.      Then send me a bug report (with your patch if possible) and 
  25. I'll fix the master version & re-release it.
  26.  
  27. How does it work?
  28. ~~~~~~~~~~~~~~~~~
  29.      Basically, it scans a stronghelp manual and records the full 
  30. filename and pagename of each page the manual contains. The code 
  31. then runs through all the pages, scanning each for links. When a 
  32. link is found, the list of pages is consulted to see if the page 
  33. the link refers to actually exists. If the page doesn't exist, an 
  34. error is reported. If the page does exist, then it is marked as 
  35. 'reachable'.
  36.      When all the pages have been scanned, each page's 
  37. 'reachable' status is examined, and any that are unreachable are 
  38. reported.
  39.  
  40.  
  41. How do I use it?
  42. ~~~~~~~~~~~~~~~~
  43.      Either with the DDE front end supplied, or from the command line
  44. or in a taskwindow, or whatever.
  45.      The syntax is:
  46.          *strongtest [-t] [-v] <manual>
  47.  
  48. The -t flag enables throwback (you'll need the DDEutils module & a
  49. text editor that supports throwback, DDEUtils is supplied with both
  50. DDE & Beebug's Easy C (& C++); any decent editor supports throwback).
  51.  
  52. The -v flag enables 'verbose' operation. Normally, very little output
  53. is genrated, just the diagnostic messages. With the -v option, all
  54. errors are detailed and warnings displayed.
  55.  
  56. There is also a -d option that enables debugging mode. In debugging mode,
  57. lots (and I mean *lots*) of output is generated. Some of it may be useful
  58. if you're trying to modify my code :-)
  59.  
  60. Oh, the options are all independent. If you use -t, you'll get all the
  61. warnings & errors thrownback, even if you don't use -v.
  62.  
  63.  
  64. What *can't* it do?
  65. ~~~~~~~~~~~~~~~~~~~
  66.      At the moment, there are a number of restrictions (some more 
  67. serious than others). For my purposes none of these restrictions 
  68. matter, but if you want me to update the code, let me know and 
  69. I'll see what I can do.
  70.      Currently StrongTest can't cope with:
  71.           Subpages       sub pages are ignored. This is quite
  72.                          easy to implement, but I don't think
  73.                          anyone uses subpages, so there :-)
  74.           Links to other manuals   Links to other manuals (eg.
  75.                          <OS_File=>SWI:OS_File> will always fail.
  76.                          Again, this is probably quite easy to
  77.                          implement, but lies outside my current
  78.                          requirements. Currently external links
  79.                          are raised as warnings.
  80.           Simple Links   the #prefix & #postfix directives are 
  81.                          ignored. This is a little harder to 
  82.                          implement, but, guess what, I don't need
  83.                          it so I haven't provided it.
  84.           Directory_     eg. in the SWI manual. This is badly handled
  85.                          at the moment. Links of the form <a=>a_b> where
  86.                          b is a page in a subdirectory a_ will be tested
  87.                          properly, but the full subdirectory facilities
  88.                          aren't tested (eg. <a=>Wimp_Poll8a> where the page
  89.                          is Wimp_.Poll.8a).
  90.           probably all sorts of other stuff. Let me know...
  91.  
  92.  
  93. So, why did you write it?
  94. ~~~~~~~~~~~~~~~~~~~~~~~~~
  95.      Well, 'Two Witches & A Moogle' are working on a manual on 
  96. aromatherapy, and the 'Moogle' thought that he'd knock up a 
  97. little proggy to make sure that we don't leave any links 
  98. 'dangling' in our manual. So, I knocked up some beautiful C one 
  99. night (resisting the urge to hack it together in ½hour in BASIC) 
  100. and tried it. Didn't work - stronghelp's image filing system 
  101. doesn't support OS_GBPB 9. I deleted evrything in a fit of pique. 
  102. Then, to my utter embarassment, I found out that it does support 
  103. OS_GBPB 10, so I had to re-write the whole **&%*#&$(* thing. From 
  104. scratch. Bastard.
  105.  
  106.      However, re-write it I did, and the result is that which is 
  107. sat before thee. The reason that the features above are missing 
  108. is that I simply don't need them, and for a simple manual they're 
  109. certainly extraneous.
  110.  
  111. So why did you release it?
  112. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  113.      Just in case anyone might find it useful. Hey, for all it's 
  114. limited, it is still quite good at what it does. And anyway, it's 
  115. free - what have you lost? And if it's that bad, let me know, or 
  116. better yet, patch it and let me know :-)
  117.  
  118. About the author
  119. ~~~~~~~~~~~~~~~~
  120.      StrongTest was written by The Musus Umbra, known in slightly 
  121. more real life as Andy. e-mail to A.J.Holdsworth@ncl.ac.uk, or 
  122. snail mail c/o 23 Baronsway, Whitkirk, Leeds, LS15 7AW, ENGLAND.
  123.  
  124.      Although this is 'freeware', don't be put off if you want to
  125. send me a donation!
  126.  
  127. Disclaimer & Licence
  128. ~~~~~~~~~~~~~~~~~~~~
  129. Use of this software is completely at your own risk. The author can accept no
  130. responsibility for any damage/loss arising from the use, or inability to use
  131. this software. No warranty, express or implied, applies to this software.
  132. This is not PD: the Copyright in this software belongs at all times to the
  133. author. However, permission is granted for unrestricted distribution
  134. prodividing that *no* charge is made for the distribution [a charge may be made
  135. for handling/media] and that the whole of the software is supplied intact and
  136. unaltered. Permission is also granted for unrestricted use and alteration of
  137. the software [but if you fix a bug / add anything nice, let me know so I can
  138. patch the 'master' version].
  139.  
  140. Bug reports / comments / etc to:
  141. Musus Umbra c/o 23 Baronsway, Whitkirk, Leeds, LS15 7AW, England.
  142. (until Sept-ish '96: A.J.Holdsworth@ncl.ac.uk)
  143.  
  144.           
  145.  
  146.