ARM Club 3/TheARMClub_PDCD3.iso/hensa/help/strongtest_1/ReadMe

Text File | 1996-02-27 | 9.9 KB | 218 lines

 .##.  #                      #####            #        .#         .#  .##.
 #.`#  #                        #              #        ##        .##  #'`#
 `#.  ###  ###. .##. ###. .###  #   .##. .### ###        #       .#'#    .#
  `#.  #   # `# #'`# # `# #' #  #   #'## ##.   #         #       #####  .#'
 #.`#  #.  #    #..# #  # .##'  #   ##.   `##  #.       .#.   ..    #  .#'
 `##'  `## #    '##' #  # #.    #   `##. ###'  `##      ###   ##    #  ####
 27 February 1996         `###                          © Musus Umbra, 1996


ReadMe file for StrongTest 1.42 (27-Feb-1996)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

What is StrongTest?
~~~~~~~~~~~~~~~~~~~
     Well, put simply, StrongTest is a simple utility that
attempts to test whether a stronghelp manual is internally
'consistent'. By 'consistent' I mean that all the links to pages
can actually get to the pages they're supposed to, and that there
are no pages that can't be reached.

     The StrongTest distribution consists of the following
files/applications:
          StrongTest     the executable
          c.strongtest   the ANSI C source code
          !strongtst     a DDE frontend for the executable
          ReadMe         this file
     I (Musus Umbra) retain copyright in the program at all
times. Permission is granted for unrestricted use. Permission is
granted for distribution provided that no profit is made and that
the distribution is supplied whole and unaltered.

But what if I patch a bug?
~~~~~~~~~~~~~~~~~~~~~~~~~~
     Then send me a bug report (with your patch if possible) and
I'll fix the master version & re-release it.

How does it work?
~~~~~~~~~~~~~~~~~
     Basically, it scans a stronghelp manual and records the full
filename and pagename of each page the manual contains. The code
then runs through all the pages, scanning each for links. When a
link is found, the list of pages is consulted to see if the page
the link refers to actually exists. If the page doesn't exist, an
error is reported. If the page does exist, then it is marked as
'reachable'.
     When all the pages have been scanned, each page's
'reachable' status is examined, and any that are unreachable are
reported.


How do I use it?
~~~~~~~~~~~~~~~~
     Either with the DDE front end supplied, or from the command line
or in a taskwindow, or whatever.
     The syntax is:
         *strongtest [-t] [-v] [-w] <manual>

The -t flag enables throwback (you'll need the DDEutils module & a
text editor that supports throwback, DDEUtils is supplied with both
DDE & Beebug's Easy C (& C++); any decent editor supports throwback).

The -v flag enables 'verbose' operation. Normally, very little output
is genrated, just the diagnostic messages. With the -v option, all
errors are detailed and warnings displayed.

The -w flag is used to unsuppress (enable) warnings when external links
(ie. to pages in other manuals), or 'conversion' pages (eg. "strtol>sttrod")
are encountered.

There is also a -d option that enables debugging mode. In debugging mode,
lots (and I mean *lots*) of output is generated. Some of it may be useful
if you're trying to modify my code :-)

Oh, the options -t & -v are independent. If you use -t, you'll get all the
warnings & errors thrownback, even if you don't use -v.


What *can't* it do?
~~~~~~~~~~~~~~~~~~~
     At the moment, there are a number of restrictions (some more
serious than others). For my purposes none of these restrictions
matter, but if you want me to update the code, let me know and
I'll see what I can do.  Many more facilities have been implemented
in this release than in the previous release.
     Currently StrongTest can't cope with:
         #Includes          These directives are currently ignored.
                            This is a possible inclusion for the
                            next release. This probably isn't too
                            important, unless the #include has subpages
                            that the page needs, or defines prefixes or
                            postfixes for simple links.
         External Links     Links to other manuals are not tested.  Again,
                            this is a possibility (at least partially) for
                            the next release.  You can use the -w flag to
                            enable/disable reporting of these links.

What's new in this release?
~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Well, after some thoughtful email and a request for partial links (ie.
a page PROC.sendfile accessed through the link <PROCsendfile>), the following
have been added:

    * Partial links : Links of the form <a=>xy> where the target page is x.y
                      are now checked correctly for all cases, rather than
                      just the limited subset in the last release.

    * Prefix & Postfix : The pages are now scanned for #prefix & #postfix
                         directives (just as StrongHelp does), and these are
                         now taken into account when processing simple links
                         (ie. those of the form <xyzzy>).

    * Subpages : Subpages (#Subpage y and <x=>.y>) are now tested.  In the
                 previous release, they would have been reported as failed
                 links.

    * Conversion Pages : By using the new -w flag, it's now possible to
                         prevent strongtest from raising 'unreachable page'
                         warnings for 'conversion' pages (ie. those of
                         the form strtol>strtod that are empty and simply
                         serve to direct stronghelp to a different page when
                         a word is being looked up (eg F1 in StrongEd)).

    * Warning suppression : By default, warnings about external pages and
                            conversion pages are *not* generated.  If you
                            want these warnings, use the -w flag (or warn
                            external in the front end).

    * Missing \ : I came across this one in the SWI manual, (in the context
                  "R0 <> 0").  Strongtest now reports <>'s without the
                  necessary \ (ie. \<>) as missing \s, rather than link <>
                  failed.

    * Front end : The front end has a new 'Warn External' option button that
                  contols the -w flag.


Sadly, all these extra gadgets (except the frontend) mean that strongtest
now runs slower than it used to... Sorry, it has to do a *lot* more work
(mainly in the partial link testing stage).


So, why did you write it?
~~~~~~~~~~~~~~~~~~~~~~~~~
     Well, 'Two Witches & A Moogle' are working on a manual on
aromatherapy, and the 'Moogle' thought that he'd knock up a
little proggy to make sure that we don't leave any links
'dangling' in our manual. So, I knocked up some beautiful C one
night (resisting the urge to hack it together in ½hour in BASIC)
and tried it. Didn't work - stronghelp's image filing system
doesn't support OS_GBPB 9. I deleted everything in a fit of pique.
Then, to my utter embarassment, I found out that it does support
OS_GBPB 10, so I had to re-write the whole **&%*#&$(* thing. From
scratch. Bastard.

     However, re-write it I did, and the result is that which is
sat before thee. The reason that the features above are missing
is that I simply don't need them, and for a simple manual they're
certainly extraneous.

So why did you release it?
~~~~~~~~~~~~~~~~~~~~~~~~~~
     Just in case anyone might find it useful. Hey, for all it's
limited, it is still quite good at what it does. And anyway, it's
free - what have you lost? And if it's that bad, let me know, or
better yet, patch it and let me know :-)

     Since the above was written, strongtest has been improved to the point
that it isn't so limited anymore.  For instance, it can now (just about)
cope with the 'standard' StrongHelp manuals - I've found all sorts of
errors in them in the development of strongtest.  It just goes to show
how hard it is making sure a manual is 'consistent' without some sort
of automatic tool... Hence strongtest.

    Strongtest has been released in the hope that people developing manuals
will find it useful in the endless search for perfection :-)

About the author
~~~~~~~~~~~~~~~~
     StrongTest was written by The Musus Umbra, known in slightly
more real life as Andy. e-mail to [e-mail], or
snail mail c/o 23 Baronsway, Whitkirk, Leeds, LS15 7AW, ENGLAND.

     Although this is 'free' ware, don't be put off if you want to
send me a donation!


History (releases)
~~~~~~~~~~~~~~~~~~
     v0.00 - ?? Dec 95 - First version. Didn't work, deleted in fit of pique.
     v1.00 - 13 Jan 96 - Rewrite having found out what went wrong.
                         RELEASED 14 Jan 96
     v1.42 - 27 Feb 96 - Added #prefix & #postfix capability
                         Added subpage capability
                         *Much* better partial link capability
                         Added -w flag (& changed front end)
                         Introduced 'missing \' error
                         Added 'activity' messages
                         Tidied messages
                         RELEASED 28 Feb 96


Disclaimer & Licence
~~~~~~~~~~~~~~~~~~~~
Use of this software is completely at your own risk. The author can accept no
responsibility for any damage/loss arising from the use, or inability to use
this software. No warranty, express or implied, applies to this software.
This is not PD: the Copyright in this software belongs at all times to the
author. However, permission is granted for unrestricted distribution
prodividing that *no* charge is made for the distribution [a charge may be made
for handling/media] and that the whole of the software is supplied intact and
unaltered. Permission is also granted for unrestricted use and alteration of
the software [but if you fix a bug / add anything nice, let me know so I can
patch the 'master' version].

Bug reports / comments / etc to:
Musus Umbra c/o 23 Baronsway, Whitkirk, Leeds, LS15 7AW, England.
(until Sept-ish '96: [e-mail])