book.html

---
layout: book-combined
permalink: /book.html
sitemap: false
---
{%- comment -%}
  The inter-span whitespace patterns the chapter-body transform
  needs for pagedjs (each whitespace run between adjacent code
  spans wrapped in a `<span class="w">` so the page splitter
  doesn't collapse it) used to be declared here as Liquid variables
  and consumed by `_includes/book-chapter-body.html`. They now live
  inline in `_plugins/book-chapter-transform.rb`'s
  `WHITESPACE_PATTERNS` constant -- see that plugin's header
  comment for the longest-first rationale.
{%- endcomment -%}

{%- comment -%}
  Roman numerals for part numbering. Liquid has no built-in; a flat
  array keyed by `forloop.index0` is the cheapest implementation and
  covers up to 20 parts.
{%- endcomment -%}
{%- assign roman = "I,II,III,IV,V,VI,VII,VIII,IX,X,XI,XII,XIII,XIV,XV,XVI,XVII,XVIII,XIX,XX" | split: "," -%}

{%- comment -%}
  2.1 / 2.2 cross-reference rewrites now live in `_plugins/book-href-rewrite.rb`
  -- the post-render Ruby pass walks each `<article id="ch-...">` block,
  resolves relative-path hrefs against the chapter's URL parent, and
  rewrites in-book absolute hrefs to `#ch-...` anchors. Doing the work
  in Ruby (one URI.merge + one Hash lookup per href) eliminates the
  per-(chapter * permalink) Liquid filter dispatch the in-template
  version paid.
{%- endcomment -%}

{%- comment -%}
  1.3: title page. Front-matter page 1 -- book title, subtitle, build
  provenance (Jekyll's site.time + the git commit captured by the
  build-info plugin into site.data.build), copyright. CSS pins it to a
  named `title` page so the running header and page number are
  suppressed (see print.css).
{%- endcomment -%}
<section class="title-page" id="title-page">
  <div class="title-block">
    <h1 class="book-title">twinBASIC Documentation</h1>
    <p class="book-subtitle">Reference Manual &amp; Tutorials</p>
  </div>
  <div class="title-footer">
{%- assign build_commit = site.data.build.commit | default: 'unknown' -%}
{%- assign build_commit_date = site.data.build.commit_date | default: 'unknown' -%}
{%- if build_commit != 'unknown' -%}
{%- if build_commit_date != 'unknown' -%}
    <p class="build-info">Built {{ site.time | date: "%-d %B %Y" }} from commit {{ build_commit }} ({{ build_commit_date }}).</p>
{%- else -%}
    <p class="build-info">Built {{ site.time | date: "%-d %B %Y" }} from commit {{ build_commit }}.</p>
{%- endif -%}
{%- else -%}
    <p class="build-info">Built {{ site.time | date: "%-d %B %Y" }}.</p>
{%- endif %}
    <p class="copyright-line">{{ site.footer_content }}</p>
  </div>
</section>

{%- comment -%}
  Front matter sections (book.yml `front_matter:`). Each entry emits
  its chapter(s) inline -- no part divider, no part number, no running
  header (CSS suppresses the latter via `.front-matter` styling).
  Entries use the same per-chapter rendering pipeline as numbered
  parts (markdownify if needed, whitespace fix, heading shift, 1.5b
  id uniqueness) but skip the sub-page state machine, since front
  matter is conceptually flat.

  Each entry has either a single `page:` (one absolute URL) or
  `prefixes:` (URL-prefix list, same shape as a numbered part). The
  fm.title is used for the root URL's chapter anchor: `/` collapses
  to an empty path under the default derivation, so `ch-introduction`
  (slugified title) is the fallback.
{%- endcomment -%}
{%- if site.data.book.front_matter -%}
{%- for fm in site.data.book.front_matter -%}
  {%- comment -%}
    Chapter list precomputed in `_plugins/book-resolve-chapters.rb`
    at `:site, :pre_render`. The Liquid `include book-collect-matches`
    + `where_exp` + `sort_by_nav_order` chain that used to live here
    folded into the Ruby resolver -- see the plugin's header comment
    for the savings rationale.
  {%- endcomment -%}
  {%- for chapter in fm._chapters -%}
    {%- if chapter.url == '/' -%}
      {%- assign fm_anchor = 'ch-' | append: fm.title | downcase | replace: ' ', '-' -%}
    {%- else -%}
      {%- assign fm_anchor = nil -%}
    {%- endif -%}
    {%- include book-chapter-body.html
        chapter=chapter
        article_class_override='front-matter'
        chapter_anchor_override=fm_anchor
        skip_sub_page_detection=true -%}
  {%- endfor -%}
{%- endfor -%}
{%- endif -%}

{%- for part in site.data.book.parts -%}
<article class="part-divider{% if part.no_outline_entry %} silent{% endif %}" id="pt-{{ forloop.index }}">
  <span class="part-title-string">{{ part.title }}</span>
  <p class="part-number">Part {{ roman[forloop.index0] }}</p>
{%- if part.no_outline_entry %}
  <p class="part-title-silent">{{ part.title }}</p>
{%- else %}
  <h1 id="pt-{{ forloop.index }}-title">{{ part.title }}</h1>
{%- endif -%}
{%- if part.subtitle -%}
  {%- assign subtitle_html = part.subtitle | markdownify | remove: '<p>' | remove: '</p>' | strip %}
  <p class="part-subtitle">{{ subtitle_html }}</p>
{%- endif -%}
{%- if part.intro %}
  <div class="part-intro">{{ part.intro | markdownify }}</div>
{%- endif %}
</article>
  {%- comment -%}
    Flat-part chapter list precomputed in
    `_plugins/book-resolve-chapters.rb` at `:site, :pre_render`.
    The plugin applies the same selector schema (page / pages /
    nav_page / nav_pages / no_descent + landing_page-first ordering
    + sort_by_nav_order) the Liquid chain used to drive, in one Ruby
    pass per entry. Chaptered parts (`part.chapters`) get their
    chapter lists resolved separately under `part.chapters[*]._chapters`
    -- the part itself has no _chapters in that case.
  {%- endcomment -%}
  {%- assign chapters = part._chapters -%}
    {%- comment -%}
      1.6a: state for sub-page detection. Index pages (URL ending in `/`)
      sort before their siblings under ASCII order, so a single-slot
      state tracking the most recent index URL plus its kind / display
      name is enough -- when we hit a non-index URL we just check whether
      it starts with that prefix.
    {%- endcomment -%}
  {%- comment -%}
    Foreword (1.9). When the part has `foreword_page:`, emit that page
    as a `<article class="part-foreword">` between the part divider
    and the first chapter. No running header (CSS suppresses the
    chrome via the `front-matter`-style named page). The foreword's
    URL anchor is derived in the include the same way as any other
    chapter so cross-references like `[Packages](/tB/Packages/)`
    resolve naturally to `#ch-tB-Packages`.
  {%- endcomment -%}
  {%- if part.foreword_page -%}
    {%- assign fw_chapters = site.pages | where: "url", part.foreword_page -%}
    {%- for chapter in fw_chapters -%}
      {%- if part.no_heading_shift -%}
        {%- include book-chapter-body.html
            chapter=chapter
            article_class_override='part-foreword'
            skip_sub_page_detection=true
            skip_base_heading_shift=true -%}
      {%- else -%}
        {%- include book-chapter-body.html
            chapter=chapter
            article_class_override='part-foreword'
            skip_sub_page_detection=true -%}
      {%- endif -%}
    {%- endfor -%}
  {%- endif -%}

  {%- comment -%}
    Part landing: a regular page article emitted between the part
    divider (and any foreword) and the first chapter. Renders with
    normal page styling -- unlike `foreword_page` which gets the
    `part-foreword` named-page treatment -- and the plugin strips
    its source H1 so the part divider's H1 stays the part's only
    top-level outline entry. `skip_sub_page_detection=true` keeps
    the landing's trailing-slash URL from making subsequent chapter
    dividers / chapter pages look like its sub-pages. Supported
    for both flat parts (handled below in the flat-part loop) and
    chaptered parts (emitted right here, before the chaptered
    loop).
  {%- endcomment -%}
  {%- if part.chapters and part.landing_page -%}
    {%- assign ld_chapters = site.pages | where: "url", part.landing_page -%}
    {%- for chapter in ld_chapters -%}
      {%- if part.no_heading_shift -%}
        {%- include book-chapter-body.html
            chapter=chapter
            skip_sub_page_detection=true
            skip_base_heading_shift=true -%}
      {%- else -%}
        {%- include book-chapter-body.html
            chapter=chapter
            skip_sub_page_detection=true -%}
      {%- endif -%}
    {%- endfor -%}
  {%- endif -%}

  {%- if part.chapters -%}
    {%- comment -%}
      Chaptered part (1.9). Each chapter entry gets its own
      `<article class="chapter-divider">` title page followed by the
      chapter's pages (landing first, then prefix-matched content in
      URL order). The sub-page state machine is reset between
      chapters so each package's class / module folders nest only
      against their own siblings.
    {%- endcomment -%}
    {%- for ch_entry in part.chapters -%}
      {%- if ch_entry.landing_page -%}
        {%- assign ch_url_path = ch_entry.landing_page | replace: '/', '-' -%}
        {%- assign ch_first_char = ch_url_path | slice: 0, 1 -%}
        {%- if ch_first_char == '-' -%}
          {%- assign ch_url_len = ch_url_path.size | minus: 1 -%}
          {%- assign ch_url_path = ch_url_path | slice: 1, ch_url_len -%}
        {%- endif -%}
        {%- assign ch_last_char = ch_url_path | slice: -1, 1 -%}
        {%- if ch_last_char == '-' -%}
          {%- assign ch_url_len = ch_url_path.size | minus: 1 -%}
          {%- assign ch_url_path = ch_url_path | slice: 0, ch_url_len -%}
        {%- endif -%}
        {%- assign chapter_divider_id = 'chd-' | append: ch_url_path -%}
      {%- else -%}
        {%- assign chapter_divider_id = 'chd-' | append: ch_entry.title | downcase | replace: ' ', '-' -%}
      {%- endif -%}
<article class="chapter-divider{% if ch_entry.no_outline_entry %} silent{% endif %}" id="{{ chapter_divider_id }}">
{%- if ch_entry.no_outline_entry %}
  <p class="chapter-title-silent">{{ ch_entry.title }}</p>
{%- else %}
  <h2 id="{{ chapter_divider_id }}-title">{{ ch_entry.title }}</h2>
{%- endif -%}
{%- if ch_entry.subtitle %}
  <p class="chapter-subtitle">{{ ch_entry.subtitle }}</p>
{%- endif %}
</article>

      {%- comment -%}
        Chapter page list precomputed in
        `_plugins/book-resolve-chapters.rb`: landing_page first (if
        set), then prefix-swept rest with landing filtered out, sorted
        by `sort_by_nav_order`. See the plugin's header comment for
        the selector schema and the savings rationale.
      {%- endcomment -%}
      {%- assign ch_chapters = ch_entry._chapters -%}

      {%- assign current_index_url = '' -%}
      {%- assign current_index_kind = 'class' -%}
      {%- assign current_index_name = '' -%}
      {%- for chapter in ch_chapters -%}
        {%- if part.no_heading_shift and ch_entry.no_heading_shift -%}
          {%- include book-chapter-body.html chapter=chapter skip_base_heading_shift=true -%}
        {%- elsif part.no_heading_shift -%}
          {%- include book-chapter-body.html chapter=chapter skip_base_heading_shift=true extra_heading_shift=true -%}
        {%- elsif ch_entry.no_heading_shift -%}
          {%- include book-chapter-body.html chapter=chapter -%}
        {%- else -%}
          {%- include book-chapter-body.html chapter=chapter extra_heading_shift=true -%}
        {%- endif -%}
      {%- endfor -%}
    {%- endfor -%}
  {%- else -%}
    {%- assign current_index_url = '' -%}
    {%- assign current_index_kind = 'class' -%}
    {%- assign current_index_name = '' -%}
    {%- comment -%}
      The part landing is the part's intro content, not an index for
      its sibling chapters -- pass `skip_sub_page_detection=true` so
      its URL ending in `/` doesn't make subsequent top-level chapters
      look like its sub-pages. Sub-page detection still kicks in for
      the per-chapter folder indexes that arrive later in the
      iteration (each gathered together with its leaves by
      `sort_by_nav_order`'s folder grouping).
    {%- endcomment -%}
    {%- for chapter in chapters -%}
      {%- assign is_part_landing = false -%}
      {%- if part.landing_page and chapter.url == part.landing_page -%}
        {%- assign is_part_landing = true -%}
      {%- endif -%}
      {%- if part.no_heading_shift and is_part_landing -%}
        {%- include book-chapter-body.html chapter=chapter skip_base_heading_shift=true skip_sub_page_detection=true -%}
      {%- elsif part.no_heading_shift -%}
        {%- include book-chapter-body.html chapter=chapter skip_base_heading_shift=true -%}
      {%- elsif is_part_landing -%}
        {%- include book-chapter-body.html chapter=chapter skip_sub_page_detection=true -%}
      {%- else -%}
        {%- include book-chapter-body.html chapter=chapter -%}
      {%- endif -%}
    {%- endfor -%}
  {%- endif -%}
{%- endfor %}