LittleSisPro - Ami Pro successor for Linux
==============================================
Version 0.3.5.0- All Features build
Native format: ODF (.odt) - ISO/IEC 26300
Interchange:   OOXML (.docx) - ISO/IEC 29500
Language:      Vala / GTK3 (native Linux binary, no Electron, no web)
Author:        Mark (with Meta AI)
Project home:  LittleSisPro/  (this folder is one level up - see Makefile)

----------------------------------------------------------------
1. WHAT IS THIS?
----------------------------------------------------------------
LittleSisPro is a native, low-resource, 64-bit word processor for
Linux, built as a successor to Lotus Ami Pro 3.0 (OS/2 / Windows).

Ami Pro was famous for being:
  - fast - it started instantly and never got in your way,
  - style-first - you picked a style (Body Text, Heading 1, Title),
    and the document looked right, instead of fiddling with fonts,
  - keyboard-friendly - everything reachable without a mouse,
  - no ribbon - a small toolbar, a format bar, SmartIcons, and a
    clickable status bar, nothing more.

LittleSisPro brings that back, with modern open formats:
  - Native: ODF (.odt) - the open ISO standard, native in
    LibreOffice / Apache OpenOffice / Collabora.
  - Interchange: OOXML (.docx) - import and export, so you can
    exchange documents with Microsoft Word / ONLYOFFICE.
  - Internal document model is isolated from both formats.
    The UI never talks directly to ODF or OOXML.

What it is NOT:
  - Not a web app. Vala compiles to a native Linux binary.
  - Not LibreOffice. It is deliberately small: one job, done fast.
  - Not a clone of Ami Pro's copyrighted bitmaps. Icons are
    mimicked with GTK stock icons in the same order/grouping.

----------------------------------------------------------------
2. QUICK START
----------------------------------------------------------------
You need the LittleSisPro/ folder next to this Makefile:

  ./
    Makefile              <- this build system
    README.txt            <- this file
    LittleSisPro.desktop  <- desktop entry (installed by make install)
    LittleSisPro/         <- Vala sources
      meson.build
      compile.sh
      src/*.vala
      data/

Build and run:

  make                    # meson setup + ninja, binary at:
                          #   LittleSisPro/build/littlesispro
  ./LittleSisPro/build/littlesispro

  make run                # build + run

  make check              # verify no placeholder stubs / known Vala errors

Install (system-wide, needs sudo):

  sudo make install       # binary -> /usr/local/bin/littlesispro
                          # desktop -> /usr/local/share/applications/org.littlesispro.desktop

Install for one user, no sudo:

  make install PREFIX=$HOME/.local
                          # binary -> ~/.local/bin/littlesispro
                          # desktop -> ~/.local/share/applications/...

Remove:

  make uninstall
  sudo make uninstall     # if you installed system-wide

Packages:

  make deb                # dist/littlesispro-0.2.0_amd64.deb
  sudo dpkg -i dist/littlesispro-0.2.0_amd64.deb
  sudo apt remove littlesispro

  make pet                # dist/littlesispro-0.2.0.pet (Puppy Linux)
                          # click the .pet in the file manager

  make source             # dist/littlesispro-0.2.0.tar.gz + .zip (source only)

  make clean              # remove LittleSisPro/build + dist/
  make help               # list all targets

Dependencies (Ubuntu 24.04, tested):
  valac 0.56.16, GTK 3.24.41, Gee 0.8 0.20.6, libxml 2.9.14,
  Meson 1.3.2, gcc 13.3.0, gdk-pixbuf 2.42.10, ninja 1.11.1

  sudo apt install valac libgtk-3-dev libgee-0.8-dev libxml2-dev \
    meson ninja-build libgdk-pixbuf-2.0-dev

----------------------------------------------------------------
3. THE LOOK - AMI PRO
----------------------------------------------------------------
Menu order (like Ami Pro 3.0):
  File Edit View Text Style Page Frame Tools Theme Window Help

Toolbar row 1 - SmartIcons (GTK stock icons, Ami Pro order):
  New Open Save Print | Cut Copy Paste | Undo Redo |
  Table Frame Link | Bold Italic Underline | Spell Zoom

Toolbar row 2 - Format bar:
  [B] [I] [U] [L] [C] [R] [J]
  [Times New Roman v] [12 v] [Body Text v] [Font...] [Theme: System]

No double title bar. No left sidebar on startup (full-width
document, like Ami Pro). Sidebar and SmartIcons are hidden by
default - show them with View > Navigator / SmartIcons.

Status bar (segmented, Ami Pro style):
  Style: Body Text | Times New Roman | 12 | D:\littlesis\docs | INS | Ln 7, Col 1 - 33 words

Icons: GTK stock icons are used, not Lotus bitmaps (copyright).
Order and grouping mimic Ami Pro.

----------------------------------------------------------------
4. FEATURES - WHAT WORKS IN 0.2.0
----------------------------------------------------------------
REAL (not placeholders):

  File:
    - New / Open / Save (ODT) / Export DOCX / Print
    - Open: .odt and .docx, paragraphs, styles, tables, images (ODT)
    - Save ODT: paragraphs, styles, tables, images embedded as
      Pictures/imageN.png + draw:frame + manifest entry
    - Print: Gtk.PrintOperation + real print dialog, draws text
      to Cairo context

  Edit:
    - Undo / Redo - REAL. Snapshot stack (last 200 states).
      Edit > Undo/Redo, toolbar, SmartIcons.
    - Cut / Copy / Paste - GTK clipboard
    - Insert Hyperlink - dialog (Text + URL), blue underlined
      link tag, stored as Run.link in the model

  Text / Style:
    - Bold / Italic / Underline - on selection, real GTK tags
    - Align Left / Center / Right / Justify - REAL GTK justification
      tags. Format bar L/C/R/J, Text menu, toolbar.
    - Style-apply - REAL. Title 28pt bold, Heading 1 20pt bold,
      Heading 2 16pt bold, Heading 3 13pt bold, Quote italic+indent.
      Style menu, format-bar dropdown, sidebar Styles, status-bar
      Style dropdown. Reapplied on render / load.
    - Font family / size - format-bar dropdowns + Text > Font...
      (Gtk.FontChooserDialog). Applies to selection, or sets the
      editor default if nothing is selected.

  Page:
    - Page Setup - REAL dialog: page size A4/Letter/Legal,
      orientation Portrait/Landscape, margins top/left (cm).
      Saved in Document, applied to editor margins.

  Frame:
    - Insert Frame / Image - PNG/JPG file chooser, scaled Pixbuf
      (320px wide, keeps aspect), caption support, ODT embed.
    - Insert Table - dialog Rows x Columns, renders as a
      box-drawing grid in the editor:
        +----------------+----------------+
        | Cell           | Cell           |
        +----------------+----------------+
      Saved as table:table in ODT, w:tbl in DOCX.
      Note: grid is display-only in the editor (Gtk.TextView
      has no editable cell grid).

  Tools:
    - Spell Check - REAL counting check against
      /usr/share/dict/words if present, else built-in list.
      Tools > Spell Check shows a dialog + unknown-word count.
      Full interactive Ignore/Replace/Add-to-dictionary is NOT
      yet in this build. Install aspell-en for a bigger dictionary.
    - Word Count - status bar + Tools > Word Count

  Theme (new menu):
    - System GTK Theme (Default) - no CSS provider, your normal
      Ubuntu/Yaru theme. This is the default on startup.
    - Ami Pro Grey - Classic (#C0C0C0, beveled, blue hover)
    - Ami Pro OS/2 Grey (#BFBFBF)
    - Ami Pro Dark (dark chrome, dark document)
    - Ami Pro Blue (light blue chrome)
    - Ami Pro Paper White (warm paper chrome)
    - Live switching, no restart. apply_theme() removes the old
      CssProvider and adds the new one at APPLICATION+100.
      Quick toggle: [Theme: System] button in the format bar
      cycles System -> Grey -> Dark -> Blue -> Paper -> System.

  View:
    - Layout / Draft - changes margins (Layout 36px, Draft 12px)
    - Navigator - Show/Hide - Outline + Styles sidebar.
      Uses set_no_show_all(true) so show_all() cannot un-hide it.
      This was a real bug: show_all() in activate() used to undo
      hide(). Fixed.
    - SmartIcons - Show/Hide - second toolbar row
    - Zoom In / Out / 100% - REAL. Scales editor font AND image
      width, 50%-300%. Status shows Zoom: 125%.

  ODF / OOXML:
    - ODF load: text:p / text:h, text:span, table:table,
      draw:frame / draw:image (Pictures/...)
    - ODF save: content.xml, styles.xml, meta.xml,
      META-INF/manifest.xml, mimetype first + stored
      uncompressed, Pictures/ for images
    - DOCX import: w:p / w:r / w:t, w:pStyle, w:b / w:i / w:u,
      w:tbl. DOCX export: w:document, w:pStyle, bold/italic/
      underline, tables. Images in DOCX are exported as
      "[Image: path]" text - full word/media/ + w:drawing is
      the next step, ODT has real images.

PARTIAL / NEXT STEPS (honest limits):

  - DOCX images: [Image:] placeholder text in DOCX.
    Fix: word/media/imageN.png + word/_rels/document.xml.rels
    + w:drawing / a:blip.
  - Headers / Footers: Page > Headers/Footers shows a dialog
    explaining the current state. Per-section headers are not
    yet implemented. Workaround: first line + Title style.
  - Spell Check: counting only, no interactive Replace.
  - Table editing: display grid only, no cell-by-cell editing
    in the TextView. A custom table widget is the next step.
  - Page Setup: top/left margins are applied to the editor,
    full pagination / print layout is not yet done.
  - Print: draws plain text to Cairo, not full paginated layout
    with headers, footers, tables, images.

----------------------------------------------------------------
5. ARCHITECTURE
----------------------------------------------------------------
  UI: Vala + GTK3
    Toolbar / Format bar / Ruler / Status bar
    Layout / Outline / Draft views
        |
        v
  Internal Document Model (never talks to ODF/OOXML directly)
    Paragraphs / Runs / Styles / Tables / Frames / Sections
    Page Layouts (page size, orientation, margins)
        |
        v
  ODF Reader/Writer (native)  |  OOXML Reader/Writer (import/export)

Files in LittleSisPro/:

  meson.build           Meson project: littlesispro, gtk+-3.0,
                        gee-0.8, libxml-2.0, gio-2.0, gdk-pixbuf-2.0
  compile.sh            rm -rf build; meson setup build; ninja; run
  src/main.vala         main() -> LittleSisPro.Application
  src/main_window.vala  Application, MainWindow: menus, toolbars,
                        format bar, SmartIcons, sidebar, status bar,
                        Theme menu + apply_theme(), Print, Page Setup,
                        Spell, Hyperlink, Zoom, Table/Image dialogs,
                        Open/Save/Export
  src/editor.vala       Editor (Gtk.ScrolledWindow + TextView):
                        render(), sync_to_model(), undo/redo stack,
                        align, style, font, hyperlink, zoom,
                        spell_check(), apply_page_setup()
  src/document.vala     Document model: Block / Paragraph / Run /
                        TableBlock / FrameBlock / StyleDef,
                        page size/orientation/margins, word_count()
  src/odf.vala          Odf.load() / Odf.save(), build_content(),
                        build_styles(), draw:frame / draw:image,
                        Pictures/ embedding, manifest
  src/docx.vala         Docx.import_docx() / Docx.export_docx(),
                        w:p / w:r / w:tbl parsing
  src/zip_io.vala       ZipIO: unzip (via unzip -o -q), read/write
                        text, tmp_dir() (DirUtils.make_tmp)
  data/LittleSisPro.desktop   Desktop entry (also at top level)
  data/LittleSisPro.css       Fallback CSS (real CSS is embedded
                        in code via CssProvider.load_from_data)

ODF package (.odt = ZIP):
  mimetype              "application/vnd.oasis.opendocument.text"
                        first, stored uncompressed
  content.xml           office:document-content, office:text
  styles.xml            office:document-styles
  meta.xml              office:document-meta, dc:title
  META-INF/manifest.xml manifest:file-entry for /, content.xml,
                        styles.xml, Pictures/*.png
  Pictures/             imageN.png for each FrameBlock

OOXML package (.docx = ZIP):
  [Content_Types].xml   Types, Override for word/document.xml
  _rels/.rels           Relationship rId1 -> word/document.xml
  word/document.xml     w:document, w:body, w:p, w:r, w:tbl
  word/styles.xml       (planned - styles are inline in document.xml
                        in this build)
  word/numbering.xml, word/fontTable.xml  (planned)

----------------------------------------------------------------
6. PERFORMANCE TARGETS
----------------------------------------------------------------
  Binary:       < 15 MB
  Cold start:   < 300 ms
  Idle RAM:     < 40 MB
  100-page doc: < 150 MB
  Lazy image loading, only visible pages laid out,
  no background indexing.

These are targets, not guarantees - measure with:
  time ./LittleSisPro/build/littlesispro
  /usr/bin/time -v ./LittleSisPro/build/littlesispro

----------------------------------------------------------------
7. BUILD SYSTEM - THIS MAKEFILE, IN DETAIL
----------------------------------------------------------------
This Makefile lives ONE FOLDER UP from LittleSisPro/.
It does NOT contain the sources - it drives them.

Targets:

  make / make build
    - Checks LittleSisPro/ exists, else prints an error telling
      you to unzip LittleSisPro.zip next to this Makefile.
    - If LittleSisPro/build/build.ninja does not exist:
        meson setup LittleSisPro/build LittleSisPro
    - ninja -C LittleSisPro/build
    - Binary: LittleSisPro/build/littlesispro

  make run
    - make build, then run the binary.

  make check
    - grep for "^placeholder" in src/ (stub check - must fail)
    - grep for "insert_pixbuf(ref" (Vala error - must be
      insert_pixbuf(it, ...), not ref)
    - grep for "if(buffer.get_start_iter" (Vala error -
      get_start_iter() returns void, cannot be in if)
    - Counts set_no_show_all hits in main_window.vala

  make install [PREFIX=...] [DESTDIR=...]
    - Default PREFIX=/usr/local, DESTDIR empty.
      System install: sudo make install
        /usr/local/bin/littlesispro
        /usr/local/share/applications/org.littlesispro.desktop
        /usr/local/share/icons/hicolor/256x256/apps/littlesispro.png
        (if an icon ships in LittleSisPro/data/, else a generic
        text-editor icon is copied)
    - User install: make install PREFIX=$HOME/.local
        ~/.local/bin/littlesispro
        ~/.local/share/applications/org.littlesispro.desktop
    - DESTDIR is for packaging: make install DESTDIR=/tmp/stage
      installs into /tmp/stage/usr/local/... without touching
      the real system. make deb / make pet use this.
    - Desktop file: prefers ./LittleSisPro.desktop (top level),
      else LittleSisPro/data/LittleSisPro.desktop, else generates
      a minimal one on the fly.
    - Runs update-desktop-database + gtk-update-icon-cache if
      available, ignores failures.

  make uninstall [PREFIX=...] [DESTDIR=...]
    - Removes the three installed files above. Use the same
      PREFIX/DESTDIR you used for install.

  make deb
    - Builds dist/littlesispro-0.2.0_amd64.deb
    - Steps: rm -rf dist/deb-root, mkdir DEBIAN + usr/ tree,
      make install DESTDIR=dist/deb-root PREFIX=/usr,
      write DEBIAN/control (Package, Version, Section editors,
      Architecture amd64, Depends libgtk-3-0 libgee-0.8-2 libxml2
      libc6 libglib2.0-0 libgdk-pixbuf-2.0-0, Description),
      write usr/share/doc/littlesispro/README,
      dpkg-deb --build dist/deb-root dist/*.deb
    - Install: sudo dpkg -i dist/*.deb
    - Remove:  sudo apt remove littlesispro
    - Note: Depends list is for Ubuntu 24.04. Adjust for other
      Debian versions if dpkg complains about a missing lib.

  make pet
    - Builds dist/littlesispro-0.2.0.pet (Puppy Linux)
    - .pet is a tar.gz with a .pet suffix + pet.specs at top.
    - Steps: rm -rf dist/pet-root, make install
      DESTDIR=dist/pet-root PREFIX=/usr, write pet.specs
      (format: name-version|Title|Description|category|size|...),
      copy README.txt to usr/share/doc/, tar -czf dist/*.pet
      from inside pet-root.
    - Install on Puppy: click the .pet in the file manager,
      or: petget dist/littlesispro-0.2.0.pet

  make source
    - Builds dist/littlesispro-0.2.0.tar.gz + .zip
    - Includes: Makefile, README.txt, LittleSisPro.desktop,
      LittleSisPro/ (sources, meson.build, compile.sh, data/)
    - Excludes: LittleSisPro/build/, .git/, dist/
    - tar: tar --exclude=... -czf dist/*.tar.gz ...
    - zip: zip -rq dist/*.zip ... (if zip is installed)

  make clean
    - rm -rf LittleSisPro/build dist/

  make help
    - Prints the target list + examples.

Variables you can override on the command line:
  make install PREFIX=$HOME/.local
  make install DESTDIR=/tmp/stage PREFIX=/usr
  make deb VERSION=0.2.1   (VERSION is used in deb/pet/source names)

----------------------------------------------------------------
8. DESKTOP FILE
----------------------------------------------------------------
LittleSisPro.desktop (top level, also in LittleSisPro/data/):

  [DesktopEntry]
  Name=LittleSisPro
  GenericName=Word Processor
  Comment=Ami Pro successor - ODF-native, OOXML interchange...
  Exec=littlesispro %f
  Icon=littlesispro
  Terminal=false
  Type=Application
  Categories=Office;WordProcessor;TextEditor;
  Keywords=word processor;Ami Pro;ODF;ODT;DOCX;...
  MimeType=application/vnd.oasis.opendocument.text;
           application/vnd.openxmlformats-officedocument.wordprocessingml.document;
  StartupNotify=true

  %f means: open the file passed on the command line / from the
  file manager. So double-clicking an .odt can open LittleSisPro
  if it is set as the default app for .odt.

  To associate .odt with LittleSisPro after install:
    xdg-mime default org.littlesispro.desktop \
      application/vnd.oasis.opendocument.text

----------------------------------------------------------------
9. HISTORY / MILESTONES
----------------------------------------------------------------
  1. Core editor + ODF
     Document model, TextView editor, ODF save/load, meson build.
  2. Ami Pro feel
     Menu order, SmartIcons, format bar, status bar, Outline,
     frames, tables, font selection, Theme system.
  3. OOXML interchange
     DOCX import/export (text/styles/tables).
  4. All Features (0.2.0, this build)
     Undo/Redo, Align, Style-apply, Print, Spell, Page Setup,
     Zoom, Hyperlink, PNG images, Table grid, Navigator fix.
  0.3.4.8: Ami Pro buttons now theme-aware
     The hard-coded #C0C0C0 grey looked strange on the warm
     Yaru beige bar - grey blocks pasted onto beige. The
     button CSS now takes its colors from the active theme
     (@theme_bg_color / @theme_fg_color, hover/pressed via
     shade()), so the Ami Pro bevel shape stays but the
     buttons blend with System, Grey, Dark, Blue and Paper.
     Bevel also finer: 1px instead of 2px, radius 2px.

  0.3.4.9: Button Bar is switchable
     The flat toolbar (top) and the SmartIcons bar (bottom)
     do almost the same job - New, Open, Save, Print, Undo,
     Redo, Table, Frame... Both look good, so now you pick:
     View > Button Bar > Both / Toolbar only / SmartIcons
     only / None. The old SmartIcons on/off item is gone,
     the radio menu replaces it. Format bar (B/I/U, font,
     style) is not part of this - it stays always visible.

0.3.5.: Buttonbar toggle only

  5. Next (planned)
     DOCX images (word/media/), per-section headers/footers,
     interactive Spell (Ignore/Replace/Add), editable table
     grid, full pagination + print layout, templates,
     GtkSourceView-based undo (alternative to snapshot stack).

----------------------------------------------------------------
10. KNOWN ISSUES / GOTCHAS
----------------------------------------------------------------
  - Unzip: always rm -rf the old LittleSisPro/ folder before
    unzipping a new LittleSisPro.zip. unzip -o does NOT delete
    old files, so stale files (e.g. document.vala with
    "placeholder", old main_window.vala) survive and break
    the build. compile.sh does rm -rf build, but not the
    source folder - you must do that yourself.
  - compile.sh permission: chmod +x compile.sh if you get
    "Keine Berechtigung" / "Permission denied".
  - Vala gotchas fixed in this build:
      * catch(Error e) is ambiguous with `using Xml;` -
        use catch(GLib.Error e) everywhere.
      * Gtk.TextBuffer has no undo()/redo() in plain GTK3
        (GtkSourceView only) - this build uses a custom
        snapshot stack instead.
      * Local functions are experimental in Vala - use
        methods (add_style(), add_tool(), add_item()).
      * Duplicate tmp_dir() at namespace level - keep it
        once in ZipIO.
      * buffer.insert_pixbuf() takes it, NOT ref it.
      * buffer.get_start_iter() returns void, cannot be
        used in if(...).
  - show_all() bug: Gtk.Application activate() calls
    w.show_all(), which shows hidden widgets. Fix:
    sidebar.set_no_show_all(true) + smarticons.set_no_show_all(true),
    and toggle by set_no_show_all(false) + show_all().
  - Yaru / Ubuntu theme: if you want the grey Ami Pro look,
    pick Theme > Ami Pro Grey. System theme is the default,
    so brown/gold Yaru on startup is NOT a bug.
  - ODF image save: in the 0.2.0 fixed build, editor rendering
    of PNGs is fixed. If Save -> Reopen loses an image, the
    ODF build_content() / Pictures/ embedding is the file to
    check - it must write draw:image + manifest entry.
  - No .git in the zips in this conversation - source
    distribution is via make source (tar.gz / zip).

----------------------------------------------------------------
11. LICENSE / CREDITS
----------------------------------------------------------------
  LittleSisPro name, code and documentation: Mark's project.
  Icons: GTK stock icons, mimicking Ami Pro grouping/order.
  Lotus Ami Pro bitmaps are NOT copied (copyright).
  ODF: ISO/IEC 26300, OASIS / OpenOffice origin.
  OOXML: ISO/IEC 29500, Microsoft / ECMA origin.
  EU guidance: ODF recommended for public-sector revisable
  documents / long-term archiving; in practice both ODF and
  OOXML are supported as minimum.

  This README.txt is the full project description. There is
  no README.md in this delivery - README.txt is the canonical
  one, on purpose (plain text, readable everywhere, no
  markdown renderer needed).

----------------------------------------------------------------
END - LittleSisPro 0.2.0 - make help for build commands
----------------------------------------------------------------
