
                                                     /\
                 gUTTER!eLEKTRONIKmAGAZINE?      ___|  |___
      __________      ______________,--,_______,-\   oO   /_____      ____
      \         '-----\             _          _      -    ____ '----'   _\
     __\____  \        \    \       /  \       /  \__/` ____/____   /  _/___
 ////      /     /__   /    /______/   /______/    __  /        /          ////
    \_________     /_____     /_____     /_____     /_____     /_____/    jp!
             /____/     /____/     /____/     /____/     /____/     /____/

While I've mentioned REFDoor being particularly well suited for e-mags and the
like, I decided to put my money where my mouth is and provide an effective
example of how a full featured e-mag can be created in REFDoor. Since I
originally worked on Gutter, and Natedogg and I publicaly released the full
source code for issue #11 with Demonic, it seemed like the most logical choice
to use as a base, allowing me to focus more on the conversion process and not
on making new content, or having to try to capture it out of a different issue.

That said, it was quite a lot more work than I'd imagined, or should I say
remembered, as it took me back to assembling the original 12 issues in 1998 and
1999. Combined with re-reading some of these old articles, this was quite a
nostalgia trip!

Fortunately, having completed this work almost immediately after releasing
REFDoor 1.3, I didn't find any major bugs while working on this. I did find
myself having to workaround numerous quirks and shortcomings, however. Some
amount of this was totally expected - after all, with its origins as an
RTReader clone, itself quite a quirkly program, I knew I'd run into at least
*some* oddities. Here's a quick rundown on some of these issues as well as
general notes on what I did to put GUTTER11.REF together:

* While REFDoor has a page reader (line reader in memory mode) via SHOW SCROLL,
  scrolling ANSIs up and down leaves a lot to be desired and is anything but
  "smooth". Instead, since this is intended to be a conversion to a BBS door, I
  decided to opt for a simple BBS style scroll by of the ANSI using DISPLAY
  with a pause prompt at the end.

* Beyond the obvious negative of not being able to scroll up and down the ANSI
  to really check it out, the other issue with using the DISPLAY (and
  DISPLAYFILE) commands is that the ANSI renders far, far too quickly on
  anything resembling a modern machine. The routine I made for displaying ANSIs
  already includes an output speed parameter, but this isn't implemented in
  REFDoor.

* I needed to trim most of the menus down to 23 lines and even leave out the
  last character on the last line to display properly without scrolling locally
  in REFDoor. This is a shame given how nice this artwork is, but overall I'm
  satisfied enough with the results and this limitation can be easily worked
  around in any new projects.

* SHOW SCROLL assumes that text is preformatted and doesn't do any sort of
  wrapping or otherwise graceful handling of long lines. In fact, it'd be more
  accurate to say it fucking HATES lines over 79 characters (after parsing.)
  It'll mangle and sometimes break output completely. To compensate, I had to
  edit some of the articles to wrap text at the 79th instead of 80th column.
  Not a big deal.

* Even worse, SHOW SCROLL can only read 255 characters per line. This wreaks
  total havoc with more complicated ANSIs which can sometimes span several
  hundreds of characters on a single line. Saving an ANSI with shorter line
  lengths (255 or less) is an inadequate workaround because the scrolling
  routines cannot compensate for ANSI up and down cursor movements (and cursor
  up, ESC[xA, is used by ANSI editors to compensate for breaking lines apart.
  This can cause all kinds of funky rendering issues, particularly when
  scrolling backwards/up.

  What I ended up doing for this was simply not showing ANSI artwork with SHOW
  SCROLL - the only articles in #11 that had embedded art of any complexity
  were the two "funny shit" articles which I decided to combine into a single
  article (which is how they were originally intended) and move the ANSIs
  themselves to separate menu items which are shown using DISPLAY. This works
  well enough, but isn't ideal, as I'd like people to be able to embed ANSI
  here if they want to.

* Another issue with SHOW SCROLL is some funky color behavior when scrolling
  backwards/up. This is a consequence of parsing line by line - if a color is
  only set at the beginning of a paragraph, for instance, then scrolling up
  will cause the text to temporary output using the default SHOW SCROLL color
  since the reader doesn't know what color its supposed to be.

  My workaround for this was simple - make sure the color is set at the
  beginning of every line. In doing this, I ended up converting all of the
  articles to text using SethCodes for coloring. While you could do the same
  thing with ANSI codes, this felt easier to ensure proper formatting and is
  quite a bit easier to read and make adjustments to in the REF itself.

* When using DISPLAY to display from a label, REFDoor is EXTREMELY aggressive
  when it comes to looking for the end of section designator - it'll assume the
  section is over the instant it finds an "@" character literally anywhere.
  This makes displaying text which intentionally uses that character
  impossible. To compensate, I simply edited out any "@" character from
  artwork and text. Who needs email addresses anyway? :P

* REFDoor 1.3 added the "NOCODE" parameters to several commands, but notably
  absent is the ability to turn parsing on and off at will. The review of
  Poffelipoff #19 in this issue is a perfect example of why this is a problem -
  the newschool ASCII DIZ shown at the top of the review absolutely destroys
  the output of the article, but if I use "SHOW SCROLL NOCODE" I won't be able
  to display the article with SethCodes for coloring. It seems like the best
  fix would be a SethCode that can be used to enable and disable parsing at at
  will.

  For now, similar to the above issue, I simply edited out any reference to "`"
  (usually replacing it with a normal apostrophe, "'" instead.) Another
  possible workaround would be to use NOCODE in combination with ANSI coloring.

* A much smaller but still annoying issue is that I made the LIGHTBAR command
  treat the escape key the same as enter. You can't really abort a lightbar
  menu without knowing what the expected fallback will be, so I think it was
  logical to make it simply go to the currently selected item. Unfortunately,
  this breaks the navigation flow of Gutter pretty terribly. That is, in Gutter
  proper, you can use ESC to backout of any and every screen until the entire
  program exits. You cannot do this in the REFDoor version, forcing you to
  manually navigate to the back/exit option on its various lightbar menus.

* I decided to build this script as a single file because, while I prefer to
  structure my projects in multiple files just to keep things organized and
  clean, I also see the appeal of being able to distribute the whole thing a
  single file in a similar manner as the original RTNEWS02.REF. The downside is
  that with all of the included ANSI, the end result is an over 600KB, 5400+
  line text file. Unfortunately, if using the 16-bit version of REFDoor with
  memory mode, this is very likely too big to fit into memory.

  Both to workaround this issue AND as a demonstration of how to break scripts
  apart by using things like the DISPLAY and ROUTINE commands, I've included a
  second "LITE" version of the script which keeps the main core of the door,
  including all of the menus and their relavant display files, in one script,
  while putting all of the articles and all of the topx ANSIs into two separate
  "library" scripts. Since memory mode releases memory when calling its other
  scripts, these should each be small enough to fit into memory on most
  reasonably optimized systems.

* Finally, the only legitimate bug I encountered in this project was when
  working on the above "LITE" version. It seems that ROUTINE and RUN are the
  victims of a bit of an unexpected snafu with the main parsing routine in
  which if the supplied script filename doesn't end with ".REF" it will be
  appended. The idea was to allow the user to leave the extension off when
  running REFDoor from the command line, but because of how it was implemented,
  scripts with different extensions won't work. This makes naming REF scripts
  you're using as "libraries" (I.E. the LITE version's G11ART.REF file") with a
  .LIB extension, for example, impossible.

* While most of the development of this script was done locally, I noted in
  final testing that some terminals still sometimes struggle with ANSIs that
  wrap on the 80th column, particularly when saved at a shorter line length,
  and scrolling. My terminal of choice in Windows, NetRunner, seems to have
  difficulties with some of the long ANSIs in Gutter #11, while they display
  fine locally and via SyncTERM, for example. This is arguable not an issue
  with REFDoor or this script - while I could have put more work into trying to
  optimize the ANSIs, ultimately if you want to be safe and save yourself alot
  of annoying work, you should consider removing the 80th column on any long
  ANSIs that don't seem to render properly.

With all of that, I've decided that REFDoor 1.4 will be coming very shortly to
address almost all of these issues with some fixes, changes, and new features.
With that, expect a version 2 of these scripts!

EOF?!