Full-book reader: per-chapter text extraction, word-wrap, pagination. More...

#include <string.h>
#include "ra8_gfx.h"
#include "ra8_gfx_font.h"
#include "sh_app.h"

Include dependency graph for sh_reader.c:

Data Structures
struct	sh_fold_t
	One typographic-Unicode -> ASCII substitution. More...

Enumerations
enum	sh_u8_t : uint32_t { k_sh_u8_ascii = 0x80U , k_sh_u8_lead2 = 0xC0U , k_sh_u8_lead3 = 0xE0U , k_sh_u8_lead4 = 0xF0U , k_sh_u8_mask2 = 0xE0U , k_sh_u8_mask3 = 0xF0U , k_sh_u8_mask4 = 0xF8U , k_sh_u8_data2 = 0x1FU , k_sh_u8_data3 = 0x0FU , k_sh_u8_cont = 0x3FU , k_sh_u8_repl = 0xFFFDU }
	UTF-8 lead/continuation masks. More...
enum	sh_u8_shift_t : uint8_t { k_sh_u8_sh6 = 6U , k_sh_u8_sh12 = 12U }
	Continuation-byte shifts. More...
enum	sh_content_const_t : uint32_t { k_sh_content_min = 1200U }
	Front-matter skip threshold. More...

Functions
static size_t	sh_utf8_decode (const uint8_t s, size_t n, uint32_t cp)
	Decode one UTF-8 sequence at `s`; sets `cp`, returns bytes consumed.
static const char *	sh_fold_lookup (uint32_t cp)
	ASCII replacement for code point `cp`; "" to drop it.
static void	sh_ascii_fold (void)
	Fold sh_state_t::text in place from UTF-8 to ASCII.
static size_t	sh_skip_word (size_t i)
	Skip the next word in the text at `i`; returns the index past it.
static size_t	sh_wrap_line (size_t i, int32_t chars, size_t ls, size_t le)
	Wrap one line from `i`; store [ls,le); return the next index.
static void	sh_reader_wrap (int32_t chars)
	Greedy word-wrap sh_state_t::text into sh_state_t::lines.
static uint32_t	sh_lines_per_page (void)
	Reader lines that fit on one page.
void	sh_reader_load_chapter (uint32_t chapter)
	Load + wrap a chapter into the reader working set.
uint32_t	sh_reader_first_content (void)
	First chapter with substantial prose (skips title/imprint front matter).
void	sh_reader_render (void)
	Render the current reader page.
bool	sh_reader_turn (int32_t dir)
	Turn the reader page by `dir` (-1/+1) across chapters; returns changed.
void	sh_reader_prefetch_adjacent (void)
	Read-ahead warm the adjacent chapters into the page cache (#207).

Variables
static const sh_fold_t	k_sh_fold []
	Punctuation the ASCII bitmap font cannot draw, folded to ASCII.

Detailed Description

Full-book reader: per-chapter text extraction, word-wrap, pagination.

Reads the open book chapter by chapter. For the current chapter it pulls the plain text (book_chapter_text), folds typographic Unicode the bitmap font cannot draw to ASCII, greedily word-wraps to the panel width, and paginates. Page turns advance within a chapter and cross chapter boundaries in either direction, so the whole book reads continuously – not just one chapter.

[Ring 6 / App] {World: NS}

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file sh_reader.c.

Enumeration Type Documentation

◆ sh_content_const_t

enum sh_content_const_t : uint32_t

Front-matter skip threshold.

Enumerator
k_sh_content_min	Min chars to treat a chapter as readable prose.

Definition at line 194 of file sh_reader.c.

◆ sh_u8_shift_t

enum sh_u8_shift_t : uint8_t

Continuation-byte shifts.

Enumerator
k_sh_u8_sh6	One continuation byte.
k_sh_u8_sh12	Two continuation bytes.

Definition at line 59 of file sh_reader.c.

◆ sh_u8_t

enum sh_u8_t : uint32_t

UTF-8 lead/continuation masks.

Enumerator
k_sh_u8_ascii	Below this: bare ASCII.
k_sh_u8_lead2	2-byte lead prefix.
k_sh_u8_lead3	3-byte lead prefix.
k_sh_u8_lead4	4-byte lead prefix.
k_sh_u8_mask2	2-byte lead mask.
k_sh_u8_mask3	3-byte lead mask.
k_sh_u8_mask4	4-byte lead mask.
k_sh_u8_data2	2-byte payload bits.
k_sh_u8_data3	3-byte payload bits.
k_sh_u8_cont	Continuation payload bits.
k_sh_u8_repl	U+FFFD replacement.

Definition at line 44 of file sh_reader.c.

Function Documentation

◆ sh_ascii_fold()

void sh_ascii_fold ( void )

static

Fold sh_state_t::text in place from UTF-8 to ASCII.

Definition at line 97 of file sh_reader.c.

References g_sh, k_sh_u8_ascii, sh_fold_lookup(), and sh_utf8_decode().

Referenced by sh_reader_load_chapter().

◆ sh_fold_lookup()

const char * sh_fold_lookup ( uint32_t cp )

static

ASCII replacement for code point cp; "" to drop it.

Definition at line 86 of file sh_reader.c.

References k_sh_fold.

Referenced by sh_ascii_fold().

◆ sh_lines_per_page()

uint32_t sh_lines_per_page ( void )

static

Reader lines that fit on one page.

Definition at line 172 of file sh_reader.c.

References k_sh_bar_h, k_sh_fb_h, and k_sh_line_h.

Referenced by sh_reader_load_chapter(), and sh_reader_render().

◆ sh_reader_first_content()

uint32_t sh_reader_first_content ( void )

First chapter with substantial prose (skips title/imprint front matter).

Definition at line 198 of file sh_reader.c.

References g_sh, k_ra8_ok, k_sh_content_min, and sh_book_chapter_text().

Referenced by sh_start_reading().

◆ sh_reader_load_chapter()

void sh_reader_load_chapter ( uint32_t chapter )

Load + wrap a chapter into the reader working set.

Definition at line 177 of file sh_reader.c.

References g_sh, k_ra8_ok, k_sh_fb_w, k_sh_pad, sh_ascii_fold(), sh_book_chapter_text(), sh_cells(), sh_lines_per_page(), and sh_reader_wrap().

Referenced by sh_reader_turn(), sh_start_reading(), and sh_tap_toc().

◆ sh_reader_prefetch_adjacent()

void sh_reader_prefetch_adjacent ( void )

Read-ahead warm the adjacent chapters into the page cache (#207).

Called in the reader's flush-idle window (after the panel flush, before the next input poll): a within-chapter page turn reads no new cache bytes (the chapter text is pre-extracted into sh_state_t::text), so the only demand faults happen when a turn crosses a chapter boundary. This warms chapter N+1 (forward reading) and N-1 (a back-flip) via book_src_prefetch_chapter() so that crossing finds them resident. Best-effort and transparent (warming never changes rendered output); a no-op unless a demand-paged .rabook is open.

Precondition: The reader screen is active (g_sh.screen == k_sh_screen_reader).; A book is open (or the call is a no-op).

Postcondition: No cache frame is left pinned by this call.; Rendered output and g_sh reader state are unchanged.

Since: 0.1.0

Definition at line 282 of file sh_reader.c.

References book_src_prefetch_chapter(), g_sh, and k_sh_fmt_rabook.

Referenced by sh_present().

◆ sh_reader_render()

void sh_reader_render ( void )

Render the current reader page.

Definition at line 210 of file sh_reader.c.

References g_sh, k_sh_bar_h, k_sh_card_pad, k_sh_col_card, k_sh_col_ink, k_sh_line_h, k_sh_linebuf, k_sh_pad, memcpy(), ra8_gfx_clear(), ra8_gfx_font_8x16, ra8_gfx_text_out(), sh_fmt_uint(), sh_lines_per_page(), and sh_titlebar().

Referenced by sh_present().

◆ sh_reader_turn()

bool sh_reader_turn ( int32_t dir )

Turn the reader page by dir (-1/+1) across chapters; returns changed.

Definition at line 254 of file sh_reader.c.

References g_sh, and sh_reader_load_chapter().

Referenced by sh_demo_step(), sh_handle_button(), and sh_tap_reader().

◆ sh_reader_wrap()

void sh_reader_wrap ( int32_t chars )

static

Greedy word-wrap sh_state_t::text into sh_state_t::lines.

Definition at line 154 of file sh_reader.c.

References g_sh, k_sh_max_lines, and sh_wrap_line().

Referenced by sh_reader_load_chapter().

◆ sh_skip_word()

size_t sh_skip_word ( size_t i )

static

Skip the next word in the text at i; returns the index past it.

Definition at line 117 of file sh_reader.c.

References g_sh.

Referenced by sh_wrap_line().

◆ sh_utf8_decode()

size_t sh_utf8_decode	(	const uint8_t *	s,
		size_t	n,
		uint32_t *	cp )

static

Decode one UTF-8 sequence at s; sets cp, returns bytes consumed.

Definition at line 65 of file sh_reader.c.

References k_sh_u8_ascii, k_sh_u8_cont, k_sh_u8_data2, k_sh_u8_data3, k_sh_u8_lead2, k_sh_u8_lead3, k_sh_u8_lead4, k_sh_u8_mask2, k_sh_u8_mask3, k_sh_u8_mask4, k_sh_u8_repl, k_sh_u8_sh12, and k_sh_u8_sh6.

Referenced by sh_ascii_fold().

◆ sh_wrap_line()

size_t sh_wrap_line	(	size_t	i,
		int32_t	chars,
		size_t *	ls,
		size_t *	le )

static

Wrap one line from i; store [*ls,*le); return the next index.

Definition at line 126 of file sh_reader.c.

References g_sh, and sh_skip_word().

Referenced by sh_reader_wrap().

Variable Documentation

◆ k_sh_fold

const sh_fold_t k_sh_fold[]

static

Initial value:

                                 = {
  {0x2014U, "--"}, {0x2013U, "-"},  {0x2012U, "-"},  {0x2010U, "-"},   {0x2011U, "-"},
  {0x2018U, "'"},  {0x2019U, "'"},  {0x201AU, "'"},  {0x2032U, "'"},   {0x201CU, "\""},
  {0x201DU, "\""}, {0x201EU, "\""}, {0x2033U, "\""}, {0x2026U, "..."}, {0x00A0U, " "},
  {0x2007U, " "},  {0x2009U, " "},  {0x202FU, " "},  {0x200AU, " "},   {0x2002U, " "},
  {0x2003U, " "},
}

Punctuation the ASCII bitmap font cannot draw, folded to ASCII.

Definition at line 35 of file sh_reader.c.

Referenced by sh_fold_lookup().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ sh_content_const_t

◆ sh_u8_shift_t

◆ sh_u8_t

Function Documentation

◆ sh_ascii_fold()

◆ sh_fold_lookup()

◆ sh_lines_per_page()

◆ sh_reader_first_content()

◆ sh_reader_load_chapter()

◆ sh_reader_prefetch_adjacent()

◆ sh_reader_render()

◆ sh_reader_turn()

◆ sh_reader_wrap()

◆ sh_skip_word()

◆ sh_utf8_decode()

◆ sh_wrap_line()

Variable Documentation

◆ k_sh_fold