XINFO (bespoke) mark-up text-document viewer

[Xiphod]

XINFO is a "text file viewer" with three other special features:

- Interprets control codes to adjust the color of the displayed text

- Supports designating document links (both internal-tags and external to other documents) that viewers can click on and navigate to those other links using the mouse. Between each "page worth" of text shown, the viewing is paused and a "menu" appears. Users can move the mouse to select links, the target of the link appears next to the menu word. Users can also just press SPACE (or right click) to proceed or ESCAPE to exit the viewer.

- Will word wrap the document based on the current text-mode screen resolution (so the same document input file can be conveniently viewed on both VGA/flat panel type displays and also CRTs).


The input files are expected to be on-system tutorial type files, "how to" documents, or helpful supporting info for a PRG. As a convention, the XINFO "standard file extension" is .NFO (but they are regular text files, intended to normally have been created on a Mac/PC, or using X16EDIT). [apologies that the old screenshots are showing .x16 extension instead of the preferred .nfo]

In addition to colors (using the standard PETSCII color codes), several other special control codes are supported:

Code: Select all

FF = disable word wrap for the current line (useful during code examples or bulleted listings)
FE = place a line divider across the current row (useful for making dividers that work across any text mode resolution)
FD = "force menu" causes a pause, so users can make a link choice without revealing the rest of the document just yet (allows a cleaner presentation of choices, especially at 80x60 text mode)
FC = center the content of the current row

8E = enter PETSCII mode (upper/grx, this is the X16 startup default)
0F = enter ISO mode (cc65 defaults to this, but if enter a PETSCII mode this is a way to come back to ISO mode)
0E = enter PETSCII mode (lower/upper chars)
0D = newline ("hard return")
01 = inverse text

Other features:
- default margin of 2 spaces on all sides, but each top/bottom left/right margin can be user adjusted (so if you want to overlay your own content on the screen, you could then "steer" XINFO into a smaller sub-region of the text mode screen)

- file parameters are also user adjustable (default is index.nfo in the CWD as FN #1 on DEVICE 8 / SUB 6).

- ESC to exit
- F1 for some brief help/reminders
- 1-9 and 0,-,= change screen modes (quick jump for when you know exactly what mode you want)
- [ or ] cycle through the screen modes
- HOME to go back to the top
- TAB to cycle through links
- RETURN to select a link (or mouse button click)
- SPACE to go to next page (or right mouse button)

These parameters are adjustable either on command line when running XINFO, or can be read from the "free memory area" by a structure defined at address $0400.

Example:

Code: Select all

LOAD "XINFO.PRG"
RUN:REM INDEX.NFO 2 2 2 2 1 8 6

To minimize the memory usage, XINFO does not read the entire input file into memory. It only buffers about two rows of display content. The link targets also do require some memory, so about 2KB is reserved for that (altogether for external and tag links).

This is a cc65-based project and it may take a while for me to figure out a way to make it ROMable. But long filenames are supported as link targets.


See the github project link for more details about how to use XINFO.
https://github.com/voidstar78/XINFO

NOTE the TryNow.zip is good for TRYING, but it is not the newest version of PRG. The V1.6.ZIP is more complete examples.


Try It Now!



VERSION 1.8 updates:
- some bug fixes related to word wrapping
- improved exiting ISO mode when transition to the PETSCII modes
- restores SHIFT+ALT PETSCII mode swapping when you exit
- updates to the F1 help

[Stefan]

Some first impressions:

- I think that navigation by links that you may click with the mouse is the killer feature of this program. It works really well, and it's easy to see how you could build a nice document library that is convenient to use.

- ROMability and/or restarting the program are known issues. I don't know what can be done.

- Screen drawing is a bit slow. Could it be faster?

[Xiphod]

Thanks for the notes!

Most of my "testing" has been with SCREEN 7 and SCREEN 11, so things feel pretty quick there. But you're right, at the large resolutions (full 80x60), I suspect a full page could be slow.

The main slow-ness is probably that it is checking for a word wrap case at each individual visible output. Could probably be smarter about that. I'll put together some larger sample docs and try to optimize that a bit better.



And thanks, yes the linking came together more easily than I thought. There are some inefficiencies (like a "tag link" goes clear back to the start of the file to search for the target tag- each time, there is no cache about it). But it's all a compromise of keeping the code small and simple. From past experience, I know cc65 PRGs have about a 1K overhead of "boilerplate" code (things like handling bytes and integer multiply, stack management), then printf is about 2K (even if you just use "%d", but it has all that code for all the other format handling still there) -- which is currently only used for convenient parsing error reporting (if the .nfo input is malformed in some way). [i.e. the PRG is currently 11KB, but I think getting to just the essentials we can get it back under 8KB]



SOME TECHNICAL BACKGROUND INFO...

The program works in basically two phases: it reads one character at a time, looking for tokens. If a token is found, it is parsed and the appropriate action of that token is put into a virtual buffer (action like change color). These are "non-visible" but just effect changes on subsequent output. If no token is found, then it is also written to the virtual buffer and marked as "visible" output. Then the virtual buffer is assessed on if enough visible characters have been buffered to fill the current row (at whatever the text mode resolution is), or if a visible character touches the last column then a wrap is assumed necessary (unless wrap mode is disabled).

Once the row is determined full, that starts the second phase of physically printing the buffer. The original .NFO tokens have already been processed into appropriate PETSCII codes. But to make the linking work, I've also "converted" the links into other non-printable codes (and a record of the corresponding target link and description length). So during this output phase, when those non-printable tokens are encountered, I replace them with the link description (and update the record to note the physical x/y location of where that clickable description is being written to). This x/y location and the stored description length is used later in the menu-loop to know what region is a clickable area (as appropriate to the current text mode resolution).


I think others may envision a full graphical viewer, with things like the H1/H2/H3/etc tags for different font sizes or maybe bold and italics, or being able to underline. I thought about maybe a custom font to do underline for links. But I found the "hidden" PETSCII code $01 that does reverse -- I didn't see this documented in the C64 PETSCII charts, but came across it noted in the X16 tech refs. A full graphical viewer would be neat, but I think maybe too slow (I mean parsing and drawing at same time could be slow and using a lot more system resources).


I'll look more into ROMability next, which shouldn't impact the format or content decided of these .NFO files. Like maybe more careful assessment of where and why I'm using an integer instead of just char type. And maybe the link-buffers can go to a specific bank (that's about 3KB of RAM the program reserves)?

[Xiphod]

Here is a screenshot to try to explain the mark-ups.

Some rules:
- all mark-up command tokens must be upper-case
- all spaces in the target description will be ignored (so you can still use spacing to help align things, but they won't appear in the presented output)
- any \n or \r in the input .nfo are ignored. The output will only newline when it encounters the CON:0D code (as shown below).

<TAG:xxx> defines a tag target starting location that are the target of TLI (TLINK, TAG LINK) commands. "xxx" name can be up to 40 characters.

<CON:yy> defines a control character output. These are hex values and can be PETSCII color codes, or there are a few "special codes" that are interpreted on display. FF = disable word wrap (until newline), FE = make a divider line across the current row, FD = force a menu pause (to enable link selection).

<XLINK:target,description> is a link to an external file, target is the absolute or relative path (relative to the CWD from where XINFO was RUN from). Target can be up to 80 chars, description up to 60 chars. Spaces in this description are ignored on output (so use a dash).

<TLINK:target,description> is a link to another tag within the same document. Note that for both external and tag links, the same style of "REVERSE COLOR" is used to highlight that they are left-clickable link regions. And also in either style of link, the link target is shown at the bottom by the menu (at least the portion of the target that can fit on the width of the screen).


In the example below (which is using SCREEN 11 32x25 mode), word wrap is disabled (CON:FF) for the list of items. If any of the strings on that row goes beyond the current screen width, a ">" arrow is shown at the edge of the screen automatically. In most cases that content won't be critical to the users, but they can be aware it exist and switch to a wider text mode if they wish.

screenshotB.png (76.52 KiB) Viewed 10561 times

[Xiphod]

Adding two features into XINFO:

- You'll be able to "pass" parameters to the startup by POKING values into the $0400 "unused" RAM area. This will have a small string header and footer, to help verify that this memory region has been setup for this purpose. This addresses an issue where you can't pass parameters using the cc65 REM conventions while using the "BOOT" command. So the alternative will be that in the autoboot.x16 you can POKE the startup settings you need.

- I've "refactored" (cleaned up) code so that stdio.h is no longer need (that provided printf and scanf). This brings the PRG down to ~7K. I've also ensured all the types can be "char" (since luckily no text mode is beyond 255 chars in either x/y dimension), except that I do need two unsigned ints (to keep track of the file parsing location). Well, there is also one spot when the mouse x/y is converted to a text screen coordinated that also needs a 10-bit value temporarily.

NOTE: without printf, parsing errors are now output in the data structure mentioned above in the $0400 region.


- Few cleanup issues when the margins are set back to 0 (none), couple minor wrapping issues on that (since you get "free newline" by the ROM text mode screen management as you encounter the physical right edge of the text mode screen). Will get those sorted out for next build.

The above should be done by this weekend.


- Pondering a "mouse wheel" support to scroll text up and down. While it can be technically done, I don't think I'll do it. I'm trying to avoid buffering much of the file, just a line or so. So the only other way for mouse wheel is to abuse the file system, and re-scan/parse the file from the start, just to move up/down a line. That might be ok for very small files. But as I may need to overhaul the file io (to ween off from cbm_open) and use KERNAL LOAD to just load the while file into BANKs anyway, maybe I'll come back to this idea.

[Xiphod]

Other todo feature reminders:

- Tab to cycle through links so they can be accessed by keyboard and not just mouse

- Standardize on having the "menu" be at the bottom of the current screen ("last line") and not just "somewhere in the center"

- Additional LinkTypes to support linking to a "PETSCII diagram" or even a "graphical diagram" (like a popup image). But do so without changing resolution (if possible) -- in the smaller resolutions, may have to use arrow keys to pan the image around. Point is to be able to provide simple diagram references to the text.

[Xiphod]

XINFO 1.3 uploaded in first post (.ZIP download, not part of TryItNow).

- the menu is now consistently always at the bottom (last row, but including user defined margin)

- can now tab/shift tab (or use up/down arrow keys) to use keyboard to cycle through the available links.

- ENTER will select the current link (priority is on the link under the mouse cursor; if mouse not on a link, then the currently tab'd indicat link is used; indicator is * asterick)

- "golden RAM" starting at $0400 can now be used to configure XINFO. Load the XINFOCFG.PRG program to see how that is done. Since you can't pass arguments using the BOOT command, this is a way to configure XINFO without needing to depend on the "command line arguments."

- fixed some issues related to wrapping. Or rather, avoid the issues by requiring the right side margin to be at least 1. The issues are between wrap and non-wrap modes at various screen resolutions, so the easiest "temporary solution" is to just avoid writing to the list column. All the other margins can be 0.

[Xiphod]

TryItNow for this is a little more stable on this.

XINFO-V1.4.zip is the package to download if want to use it locally. (see first post)

XINFO-V1.4 updates:

- Can now press [ or ] at the menu to change text mode resolution (so you don't have to restart XINFO to find a resolution that works for you and the current NFO content)

- The menu will now say "more" if there is more content to be displayed, or "stop" if the end of the NFO file has been reached (subtle difference, "stop" means the file is closed and you can edit it in another program and the new content will be displayed as soon as you press space; "more" means the file is still held open and pressing space will display the next section)

- minor word wrap fixes

[Xiphod]

XINFO 1.5 updated in first post

- Fixes issue where mouse can't fully move across screen after changing video modes (have to turn it off and then back on to reset the bounds after screen mode changes)

- Added a "page count" index next to the pause-menu (helps to remind where you were on a page, so if you go to a tag then back to the top and want to get that page again)

[Xiphod]

XINFO 1.6 Lots of updates!!

Bug fix:
- Minor bug where in "large resolutions" (like those VIC-20 modes) it could end up possible for a link x/y position to actually be off the screen (such as if word wrap is off). So then it become unpredictable on what would happen. Cleaned this up (so that links that end up off to the right, such as when no wrap mode.
- Sometimes very long lines that had no spaces would eat up multiple rows, potentially end up in the same row as the menu. Cleaned this up.


Control codes:
- PETSCII control code is now supported so you can enter into PETSCII and use those available fonts. When in PETSCII mode, the DIVIDER will become an actual line instead of ashes.
- Also a control code to enter back into ISO mode if you do exercise going into PETSCII mode.
- NEW "CENTER ROW CONTENT" control code; little proud of this one, took me awhile to think of an easy way to pull it off and it finally came to me.
EDIT: forgot to also mention NFO files can now have comments in the style of
<! comment >


(new) Keyboard commands:
- HOME and T to go back to the Top (and with this, now you don't have to add links back to top throughout the NFO file)
- F1 help!! Uses printf so it bloats the PRG back up to 12K. Briefly reminder about the hot keys and also a reference guide of the control codes supported in the NFO files. This help is also centered in the current screen mode.

V1.6.zip download in the first post.