ASPL

Design the bilingual website and documentation

Archived MVP specification. For ASPL 0.7.0, see the current reference and native HTTP guide.

Type: prototype Status: resolved Blocked by: 06, 12, 13, 14 Parent: Find the ASPL MVP specification

Question

What information architecture, language-switching behavior, bidirectional layout, learning path, reference structure, C interoperability guide, installation flow, accessibility bar, and representative examples should the Arabic-default website and equivalent English content use for its systems-programmer audience?

Comments

Answer

Use the Guided line structure shown as variant B in the bilingual website and documentation prototype. The website is an Arabic-default route through one runnable program, not a generic project landing page. Its first meaningful interaction is the canonical Arabic source and its Run control. Learning, reference, C interoperability, and Linux installation follow as named stations on the same line.

The visual language is a bilingual civic route board: off-white reading surfaces, enamel blue for stable routes, green for active or successful states, amber for decisions, square sign geometry, and Alexandria lettering. Color never carries route or execution state by itself.

Entry and route order

The first viewport on desktop and a 390 by 844 pixel mobile screen must contain token-aware Arabic source and the real Run control. A short title may introduce it, but no account prompt, installation step, abstract feature grid, or long product argument may precede it. The source board shows the example vocabulary, atom-order control, Run, Stop, the current execution state, and the permanent browser boundary Bytecode only · No Linux libraries · No ELF execution.

Running advances one visible, programmatically announced line through source snapshot, checking, browser execution, and the exact main status. The website entry uses the worker and state contract from Design the browser playground behavior; the prototype's timed transition is only interaction evidence.

The global route order is:

  1. Try: run the canonical Arabic program;
  2. Learn: understand the program through four short systems-programmer concepts;
  3. Reference: open the exact contract from any concept;
  4. C interoperability: cross the explicit unsafe boundary on native Linux; and
  5. Install: verify the supported host, obtain the one tool, put it on PATH, and check the first file.

The header exposes these five routes at every width. On narrow screens it may scroll horizontally, but the active route, language control, and keyboard focus remain visible. Each learning section links forward to its exact reference page, and each reference page links back to a runnable example. The site must not split explanatory guides and normative reference into disconnected trees.

Arabic and English behavior

Arabic is the default at / and the canonical locale under /ar/. English has an equivalent tree under /en/. Every published page has a one-to-one locale counterpart, the same stable ASCII anchor identifiers, and localized titles, descriptions, navigation, control names, status announcements, and diagnostic prose. The locale URL is authoritative. An explicit switch is remembered for later visits to /, but browser or source language never silently changes the interface.

The العربية / English control preserves the current page, semantic anchor, selected source example, atom order, execution snapshot or result, keyboard focus, and scroll position. It changes interface and documentation prose only. It never translates source keywords, identifiers, strings, comments, paths, symbols, commands, or diagnostic fields. Arabic, English, and mixed source are selected independently. A copied or shared locale URL must reproduce the selected interface without relying on stored preference.

Arabic pages set lang="ar" and dir="rtl"; English pages set lang="en" and dir="ltr". Layout uses logical block and inline properties so route order and reading chrome mirror with the page. Commands, paths, ABI signatures, version strings, stable reason keys, route codes, and other opposite-direction fields are isolated with bdi, dir, or an equivalent semantic boundary. DOM and keyboard order remain logical rather than being visually reversed.

Source uses the token-aware display contract from Design the bilingual source notation. The renderer isolates every lexical atom, keeps numeric atoms LTR, gives comments content-sensitive direction, and applies the selected RTL or LTR order to keywords, identifiers, strings, operators, and neutral punctuation. A plain RTL pre or textarea is not sufficient. Changing interface language or atom order never changes stored source bytes. C interoperability examples retain their own Arabic RTL source state even when another example uses English LTR source.

Learning path

The learning route assumes basic C or systems-programming knowledge. It is not a beginner curriculum. Its four stations are:

  1. one file, top-level functions, the reserved entry function, and the exact process status;
  2. the five storable types plus unit, immutable and mutable bindings, conditions, loops, return, and the safe اطبع or print output builtin;
  3. declared function signatures, structured diagnostics, mapped source locations, traps, and classified failures; and
  4. explicit foreign declarations, operation-local unsafe calls, supported C adapters, and host restrictions.

Each station is short, ends with a runnable or checkable program, and links to the matching normative material. Examples state whether they run in the browser, native Linux, or both.

Reference structure and publishing template

Arabic and English use the same reference tree:

Every reference page contains, in this order, the exact contract, accepted and rejected forms, a canonical Arabic example, its checked English equivalent when vocabulary is relevant, named diagnostics or failure outcomes, host applicability, and a link to run or check the example. Arabic is canonical, but page parity is a release requirement: the locale trees, anchors, examples, version labels, and normative meaning ship together. English content may be clearer idiomatic English; it may not weaken or add a rule.

C interoperability guide

The C guide begins with the exact limit rather than a broad compatibility claim. On native x86-64 Linux with glibc, the MVP supports only int(const char *) and double(double) adapter profiles. It documents literal library and symbol names, eager loading, exact type matching, the call-scoped C-string loan, return conversion, every stable load or foreign failure, and the required explicit unsafe declaration and call.

The main walkthrough calls puts from libc.so.6 with Arabic ASPL source, then shows the equivalent English vocabulary separately. A warning gate says that the example is native-Linux-only and that the browser rejects every foreign import. The guide never says that ASPL can call arbitrary C functions, parse headers, use variadic calls, or run shared libraries in the browser.

Installation flow

The installation page is a four-step user path:

  1. state the supported architecture, operating system, libc family, and exact compatibility floor before download;
  2. present the versioned release file, size, license notices, and checksum together;
  3. install the single aspl executable under ~/.local/bin or another explicit location and verify PATH; and
  4. verify the version, run aspl check hello.aspl, then link to run and build.

Upgrade, rollback, and uninstall remain on this user-installation page. Contributor build instructions live elsewhere and must not appear in the first-install flow. Define distribution and installation owns the exact archive name, versioning policy, checksum format, glibc floor, and release commands; the website must populate this fixed structure from that decision rather than invent provisional values.

Accessibility release bar

Top-level routes end with a compact accessibility release bar naming four verifiable properties: correct page and field direction, a complete keyboard path, announced check/run/result state, and human testing with mixed Arabic and Latin text. The release target is WCAG 2.2 AA. This is a target and publishing gate, not a compliance badge.

A release must verify keyboard and visible focus behavior, skip navigation, localized accessible names and landmarks, live execution states, contrast without color-only meaning, reduced motion, reflow at 320 CSS pixels, text zoom, screen-reader reading order in both locales, and mixed-direction source, paths, commands, and diagnostics. The direction implementation follows the W3C guidance to declare page direction and isolate opposite-direction inline content rather than inserting invisible control characters in generated markup.

References:

Representative examples and release evidence

The entry example sums the integers from 1 through 10. When the result is 55, it calls اطبع("55\n") and returns status 0; its failure path returns a nonzero status without printing success. Publish the canonical Arabic program, a normalized-target-equivalent English program, and a deliberately mixed-alias program. The counterparts use print where selected but preserve the exact "55\n" string bytes and expected output fixed by Choose the MVP builtin environment.

The documentation set also includes one diagnostic correction example, one configured-limit failure, the native puts example, the browser rejection of that same foreign import, and the single-file installation check. Every example records its expected check result, run status or failure class, supported host, and source vocabulary. CI checks Arabic and English examples against the same compiler version and fails the documentation build when a counterpart, anchor, expected outcome, or host label drifts.

Conformance evidence must cover the Arabic-default first visit, the English locale counterpart, all five routes at desktop and narrow widths, persistent language and example state, token-aware Arabic, English, and mixed source in both atom orders, keyboard-only Run and Stop, exact live "55\n" output and the announced status, safe rendering of non-printing output, locale-parity checks, correct browser/native capability labels, the C warning gate, and every item in the accessibility release bar.