Onboard Manual Mode

[dylwhich]

Summary
What is the feature all about? Is it a game, a utility, an enhancement, or something else?
Onboard Manual Mode is pretty much the online/paper swadge manual, but on the swadge itself.

Users should be able to:

• Read the manual
• Jump between chapters with a side menu
• Perform a text search
• Follow hyperlinks leading to anchors elsewhere in the manual

Technical Spec
How will this be implemented?
What peripherals will be used, and how?

Much of the work would be porting / rewriting the existing prototype implementation that was created for the 2023 swadge. This contains just the main functionality of parsing and rendering markdown-ish files.

Perhaps the touchpad can be used for smooth scrolling too.

The prototype contains a full markdown parser that supports basic standard markdown (headers, horizontal rules, bold/italic/underline/strikethrough, single-vs-double-newline break behavior), and also escape sequences for things which aren't possible in pure markdown, like color changes (\c000), alignment changes (\lCCentered Text\L). It also supports parsing standard markdown image tags (and alt text), but not loading or rendering images. We could modify the existing parser to better fit the needs of the final version of the manual. If you want to see what the markdown-ish format actually looks like, compare this file to the screenshot below.

Technical info about the existing markdown parser

The parser itself builds a tree (apparently it's called a "left-child right-sibling tree") structure from the text. Each node in the tree has a child, sibling, and parent (just for faster traversal in reverse) pointer, a unique index, and then the node data itself. The node data depends on the type, but it's generally just an enum value, and maybe pointers to within the main text. The main text never gets copied since we can fake having substrings by having an end-pointer for all strings within the text. Overall, each node is around 32 bytes and represents either a continuous text span of any length, a "decoration" (non-text node), or the start of a new text style.

The text only needs to be parsed once to generate a markdown tree, which can then be rendered within bounds and continued just like the normal word-wrap text functions do. The markdown renderer just uses an opaque pointer as a "continue" point, which internally just has a pointer to the both the text and the markdown node. The existing mode has some code that pre-paginates the pages and caches the result, but that's likely (though untested) to be unnecessary now that the billion printfs have been removed from the rendering process and it's actually fast on the real swadge.

In whatever state it ends up in, any markdown/rich text support that's used for the manual can be made into a library that could be used by other swadge modes too.

UI
What are the display screens & menus (if applicable)?
What user inputs are there for each screen?

Not sure if there would be an overall main menu or not. If so, it would just be a bigger version of the main menu.

Aside from the main reading area, there would be some sort of collapsible side pane, or maybe an entire screen, that would let the user scroll between chapters/subchapters quickly.

There would also be a search feature, on a pane/screen similar to the chapter select pane. First it would show the text entry dialog, then once text was entered it would go to a page which lists the results, which the user could scroll through to select and navigate to the text in its place, or the user could go back to the text entry screen to modify the search.

Mockups
Paste any mockups of screens or anything else here.

How to Test
How can we verify the feature is working?

Read manual, make sure doesn't look wrong?

[dylwhich]

Some more thoughts:

In the previous manual implementation, most of the existing library code that was updated was for the purpose of adding bold/italic support to the text functions. Those could instead be added, if at all, by just using a different font without having to change anything, I think.

[AEFeinstein]

Yep, different fonts would work for bold or italic text.

Text search and hyperlinks sound nice, but feel like way overkill. If the modes are so complicated that text search is required, we already did something wrong. Also text input with a d-pad is pretty meh. Hyperlinks are more feasible, but I still don't see them getting used.

I'm also gonna bet now that when the post-mag survey comes, back, the usage stats for the manual are gonna be slim.