X16 INFO marked-up document viewer

[Xiphod]

X16EDIT is an existing on-system text file reader/view and does that job very well (including large files, copy buffer, and mouse support w/ highlighting!).

But there is also a need to have a kind of on-system "manual" or "help" system that can read a plain-text document but also show highlights/colors (mark-up), and also support some concept of document linking to quicky transition from one topic to another.

The main challenge is: this viewer needs to be adaptable to the various text modes of the system. Typically, there is 80 and 40 column modes, but various users may choose to use the other modes that are 22, 32, 64 (especially users of CRT screens). This avoids needing multiple versions of the same help-text. Mainly this means supporting word-wrap feature.

X16EDIT does support word-wrap. But this other-needed-utility also needs to support document-linking, and word-wrapping will cause the x/y location of links to move around (i.e. in terms of having the program know where to click and what to transition to when doing so). So the program needs some smarts to be adaptable to that.


There are lots of existing formats for this - with each one having challenges to adapt to 6502, PETSCII, and the X16 system.


Here is a proposed approach called XINFO that I've put together using cc65.

The "mark up language" is kept simple:

<CONTROL:xx> xx is a hex code that corresponds to a non-printable PETSCII code (i.e. foreground color changes). I chose this since that list is well known and documented. But we can refine this later to an easier set of codes if that helps users. like CONTROL:WH for white, etc) <XLINK:path,title> path is something like "./SYSHELP/INDEX.X16" (i.e. can be a relative or absolute path) and title is what is shown in the document (using "reverse color" text) <TLINK:tag,title> tag is a brief tag reference within the current document, so when users click on this title the viewer will automatically move to where the specified tag is located. <TAG:tag> user defined tags (target locations within the same document file)

These control commands can be abbreviated by the first three characters, so you can use "con" "xli" "tli" and "tag". If you need to show an actual "<" (open angle bracket), you can specify << and only a single bracket will appear.

NOTE: cc65 supports specifying "command line arguments" by using the REM statement when running your PRG. So for example: RUN:REM <filename> is used to pass the input filename to the X16MANUAL.PRG demo program here.


One point here is that no elaborate document editor/creator is needed. Essentially any editor (including X16EDIT) can be used to create a document, and just follow these few simple control tokens as described above. The only slight complexity is users have to mentally keep in mind that the tokens aren't shown (except the title portion of links), and so need to format the content accordingly. Someday maybe a kind of "WYSIWYG" editor could be made.


Given this same input file, below is an example of what the viewer looks like at the various resolution.

I also chose to have the program enter into ISO mode during startup. I feel this makes it easier for folks to build up their document off-system in the PC environment editors. Note that CR or LF/CR don't matter - they are ignored during parsing - the way this program works is the text is treated as a kind of "streamed text blob" and won't new line unless you specify a <CON:0D> (PETSCII code for ENTER). The intent is users would active this viewer, stay in their current text resolution mode, and use ESCAPE to exit the viewer and return to their previous PETSCII mode.

Word-wrapping across the text mode resolution is working. I've not finished the "hyperlink" stuff - they are being parsed and collected into an in-memory data structure. The program works like this:

- When reading the text input, the program first prints things to a "virtual output" buffer. It keeps track of printable and non-printable characters. Like <CON:05> becomes the non-printable character to change the console into WHITE text. During this virtual printing, it is keeping track of if the current row is full - and if so, then proceed to actually print out that row. (when a "paragraph break" or EOF is encountered and the line is not yet full, a "forced output" is used to flush out the current row buffer)

- It keeps track of the total rows written, and will have a pause once the screen is full. For now it is a "press any key" prompt, but longer term this pause would be a little loop to manage mouse operations, link clicks, and offer things like PGUP to go back. The point is, the program doesn't buffer up the entire input file at once, it just reads in a few lines of the input file to fill in the current screen. They can press ESC to exit the viewer and get back to their normal CMDR-DOS.

- Links will be managed by knowing when the "real output" has happened. Tentatively I'm planning on using the other set of non-printable characters (non color codes) as invisible markers, and when those are encountered I know where a link is being written, and I store that to the link-structure. Then from that I have resolved positions to work with and can manage changing the mouse cursor shape when users move over links.

- Tag links will basically reset back to the start of the file, search for the specified tag. I may cache the tag offsets as they are encountered, to make that faster - but I'm not expecting these ".X16" files or manual files to be massive. (fseek isn't available yet in the X16lib for cc65, so may have to build our own .s for that).

- External links will change to the linked folder and just restart the program with that linked file.

NEW feature complete:
https://www.youtube.com/watch?v=XdRnSadECiY

ABOVE: a video on the various resolution used to present the same input file.

Added AUTOBOOT.X16 and XINFO loads index.x16 by default, making it easier to demo in TryItNow. So give it a try!

Try It Now!
NOTE: the TryItNow is "flickering" about 10 times during startup in the web emulator, I'm not sure why yet. Doesn't do it anywhere else. it might be that my mousebutton query isn't cleared at startup, so it thinks right click is pressed and so that is the same as holding space down for awhile until the emulated system clears that out. That's my only guess. Sorry for the flickering, not intended and won't be in the final for sure (and doesn't happen on h/w or system emulators).

[Xiphod]

Updated PRG and files in the first post.

- Corrected a few bugs (things that wrapped exactly with a space at last column would have an issue; now fixed)
- adding more inline assembly to be less dependent on the C standard library.
- Added support of non-printable codes to mark where links are being output
- Also adding the .c source
- Initial mouse support

Now that we know where the link text is being wrapped and written to (in x/y screen coordinates), and combined in the mouse support, next step is adding in the actual link logic.

[Xiphod]

New updates and now "feature complete" - word wrapping and both external and tag links are working.

TryItNow doesn't support passing command line arguments (at least not in a way that cc65-based projects expects). The TryItNow will work, but if you just RUN, it will crash to monitor. You must start the program yourself and pass the initial filename input, since the program has no file selector built in. To do this:

- click TryItNow (link in the first post)
- reset the emulator with CTRL+ALT+R
- Type command: LOAD "XINFO.PRG"
- Type command: MOUSE 1 (necessary, or the link click stuff won't work)
- Type command: SCREEN 11 (or try some other resolution)
- Type command: COLOR 1,0 (optional, just to set a background color to what you like)
- Type command: RUN:REM BASIC.X16

To experiment with margins, do:
RUN:REM BASIC.X16 5 5 3 3
(the numbers after the filename are margins, in the order of top bottom left right)

(the "REM BASIC.X16" is important since it tells the cc65 built PRG executable the first command line argument that is the initial filename to start with). BASIC.X16 is just a reference example - it could also be used for like a game quick instruction manual, or feature-specific tutorial.


The main known limitations/problems are:

- cc65 built programs aren't "re-entrant" -- you DON'T have to reset the system, but you do have to reload XINFO.PRG after you exit it in order to run it again
- not sure how do a cleaner or intuitive way to pass the command line argument. But X16EDIT can do this, so we know there are possible ways this can be done (with a pure asm project)
- There are limits to the total number of links that can fit within a single page (the memory usage had to be bounded, I avoided using malloc; I could make use of BANKs, such as external links in one bank and tag links in another bank-- can address that if any complex manuals/infos get built); the current limit is 30 (which is a bit more than the full alphabet)

[ current version is the ZIP file in first post of this thread ]

or see github:
https://github.com/voidstar78/XINFO

[Xiphod]

New features added:

- user defined margins on all sides (defaults to 2)
- CON:FF can be used to toggle word wrap [edit: word wrap now only disabled only for current row, until 0x0D/ENTER]
- CON:FE can be used to do a divider-line (sequence of dashes all the way across the current row)


ZIP in the first post with PRG and .c source and set of .x16 examples, see also the github link.

[Xiphod]

Few adjustments/fixes for the 1.1 version (ZIP at github or in first post here).

- Turning word wrap OFF now only applies to the current line. Word wrap switches back to ON when it encounters the next 0x0D (ENTER). This is because of an issue where if the user hits a page pause before the next word-wrap toggle control code, the "view state" ends up being opposite of what the writer probably intended (having two separate codes for on vs off doesn't help in all cases, and this just happens depending on the users text mode resolution). Disabling Word Wrap was intended for brief list of items or code, and just having this code repeated for each line was the best compromise I could come up with (as I'm trying to avoid reading the entire file and having to "parse far ahead" to find major "paragraph blocks" and make decisions on far-away codes).

- When word wrap is OFF, the end of line will now have a ">" arrow indicating that for the current text mode resolution, there is more content past the end of the line (so the ">" is a reminder that this content is not being shown since we're currently not in word-wrap mode -- but if you go to a larger resolution and view the document again, then you might see that content)

- Right click is now like pressing space at the menu (i.e. go to next page). But I found it is slightly sensitive, like the KERNAL code to get mouse button state lingers a tad longer than it should (in contrast to actually pressing SPACE).

- Added a "force menu" control code 0xFD. If you're at a large resolution (80x60), it sometimes can look silly to have a content and then a bunch of tag content already shown below it. "Force menu" is a way to have stops or pauses in what is being displayed, like for showing a menu or description and having tag-links to supporting information about it (like code examples). "force menu" is ignored when the program is searching for a tag, so you generally have large-descriptive content at the top, then a force menu somewhere, then all your supporting links somewhere past the force menu spot.

[Xiphod]

Got long filename support figured out. So it is useful software, moving out of WIP and over into Apps

viewtopic.php?p=30281