THE WRITER’S COMPANION — RELEASE 1.0
User Guide and Feature Reference | Linux edition
Plain-text writing in a quiet, typewriter-inspired workspace

======================================================================
CONTENTS
======================================================================

1. Welcome
2. What The Writer's Companion Is
3. The Main Window at a Glance
4. Starting a New Document
5. Opening an Existing Document
6. Saving Your Work
7. Automatic Saving and Recovery
8. Backups When You Quit
9. Choosing a Typewriter Style
10. Font Size
11. Line Spacing
12. Left and Right Margins
13. Night Mode
14. Key Sound
15. Shortcut Guide
16. Help Toggle and Search
17. Show Scrollbar
18. Show File Path
19. Status Bar and Word Count
20. Keyboard Shortcuts
21. Editing Text
22. Sample Text
23. Where Files and Settings Are Stored
24. Installation and Launching
25. Troubleshooting
26. Current Limitations
27. Quick Reference
28. Feature Checklist

====================================================================== 1.
WELCOME
======================================================================

The Writer’s Companion is a small, distraction-free writing application
for Linux. It is designed to provide a calm place to write, with the
simple feel of an electronic typewriter and the convenience of a modern
computer.

This guide is intended to work both as an instruction manual and as a
feature reference. It explains the controls, the document workflow, the
safeguards that help protect writing, and the current limitations.

The application works with ordinary plain-text documents. It does not
require an online account, and your writing is stored on your computer.

======================================================================
2. WHAT THE WRITER’S COMPANION IS
======================================================================

The application is designed for writing stories, poems, articles,
letters, memoirs, notes, drafts, manuscripts and other text-based work.

Its main priorities are: - A large, uncluttered writing area. - A
typewriter-inspired appearance. - Straightforward document creation,
opening and saving. - A choice of named typewriter styles. - Adjustable
font size, line spacing and margins. - Optional night mode and typing
sound. - Background saving and recovery protection. - A compact
interface that keeps the writing area central.

The application works with plain text. It is not a word processor with
rich formatting. Text files do not store font choices, text colours,
page layout, images or other visual styling.

======================================================================
3. THE MAIN WINDOW AT A GLANCE
======================================================================

The main window is divided into four areas:

TOP BANNER The banner displays THE WRITER’S COMPANION and the tagline “A
quiet place to write.”

TOP TOOLBAR The toolbar contains document buttons and switches for
optional interface features.

WRITING CONTROLS The second row contains the Typewriter selector, text
Size, Line spacing, Left margin and Right margin controls. The selected
typewriter’s sample is shown in the writing area when a new document is
empty.

WRITING PAGE AND STATUS AREA The large page is where you write and edit.
The status area at the bottom reports writing information, including
margins, line spacing, cursor position and word count. If Show file path
is on, the footer also displays the current file name and/or location.

The application opens full-screen by default. Press F11 to toggle
full-screen mode.

======================================================================
4. STARTING A NEW DOCUMENT
======================================================================

Click NEW or press Ctrl+N.

If the current document has unsaved changes, the application asks what
you want to do before replacing it. Follow the prompt to save, discard
the changes or cancel the operation.

A new document starts with: - Brother GX-6750 as the default typewriter
on a fresh installation, unless a different typewriter was previously
saved in settings. - Font size 16. - Left margin 11. - Right margin
11. - Line spacing 1.5, unless a saved preference changes it. - A sample
paragraph to demonstrate the selected typewriter style.

The sample is demonstration text, not your writing. It is excluded from
the document’s word count and is intended to be replaced when you start
typing.

A new document has not yet been saved under a file name. Use Save to
choose a name and location.

======================================================================
5. OPENING AN EXISTING DOCUMENT
======================================================================

Click OPEN… or press Ctrl+O.

Choose a file in the file dialog. The application reads the document as
UTF-8 text. Although the file dialog may allow different file
extensions, the application treats the contents as plain text.

Before opening another file, the application checks whether the current
document has unsaved changes and asks how to proceed.

When a document is opened: - Its text is displayed in the writing
area. - The new-document sample is not added to the file. - The
application attempts to restore that document’s saved margin settings
from its companion settings file. - The selected typewriter and other
application preferences remain available as display settings.

If the file cannot be read, the application reports an error.

======================================================================
6. SAVING YOUR WORK
======================================================================

Click SAVE or press Ctrl+S.

For a document that has not been saved before, Save opens a file dialog
so you can choose the file name and location. The default document
folder is:

    ~/Documents/Writers_Companion/

The default extension offered is .txt. The application saves UTF-8 plain
text. You can choose another location through the file dialog.

After a document has a file name, Save writes changes to that file. The
application reports a save error if the file cannot be written.

Font, line spacing, and typewriter appearance are not embedded in a
plain-text document. Margin preferences are stored separately in a small
companion settings file.

======================================================================
7. AUTOMATIC SAVING AND RECOVERY
======================================================================

The application has two separate background protections. They serve
different purposes.

FIVE-MINUTE DOCUMENT AUTOSAVE About every five minutes: - If the
document already has a file name and has unsaved changes, the
application saves those changes quietly to the existing file. - If the
document is new and has not been named yet, the application asks whether
you want to save it. It cannot silently choose a file name or location
for you. - If there is no text to save, no document save is needed.

The new-document prompt is an opportunity to choose a name and location.
If you do not save the new document, continue writing; the application
will ask again at a later five-minute check while the document remains
unsaved and contains text.

THIRTY-SECOND RECOVERY SNAPSHOT The application also attempts to write a
recovery copy of non-empty writing about every 30 seconds. This is
intended to help recover text after an unexpected crash or interruption.

If a recovery copy from a previous session is found, the application
offers to open it.

IMPORTANT: - Recovery snapshots are not a replacement for saving your
document. - A crash may lose changes made since the latest recovery
snapshot. - The recovery copy is a safety copy of text, not a complete
version history of your document. - Recovery content may not identify
which original file it came from. - Save important work normally and
check that the save completed.

======================================================================
8. BACKUPS WHEN YOU QUIT
======================================================================

When you use SAVE AND QUIT, press Ctrl+Q, or close the application
window, the application follows its closing routine.

It saves the current document if required. If saving is cancelled or
fails, it keeps the application open rather than closing and discarding
the unsaved writing.

The application then attempts to create a timestamped backup: - For a
saved document, the backup is placed beside the original file. - For an
unsaved document, it attempts to place an Untitled backup in the
application’s data backup folder.

Backup names include a date and time so that separate backups can
coexist. Backups are plain-text copies; they are not a complete copy of
all settings or application data.

The recovery file is removed during a normal successful close when
possible.

======================================================================
9. CHOOSING A TYPEWRITER STYLE
======================================================================

Use the TYPEWRITER selector in the writing-controls row to choose the
machine whose style you would like to imitate.

The selector offers these named styles: - Malling-Hansen Writing Ball -
Remington No. 2 - Oliver No. 3 - Underwood No. 5 - Royal Standard -
Corona 3 - Hermes Baby - Royal Quiet De Luxe - Olympia SM3 -
Smith-Corona Silent-Super - IBM Selectric - Olivetti Lettera 32 -
Brother M-2000 - Brother GX-6750 - Brother AX Series

The application uses bundled, redistributable monospaced fonts to
provide consistent font availability on supported Linux installations.
The named typewriter choices are style presets, not exact digital
reproductions of each machine’s original typeface.

When a new, empty document is displayed, the sample sentence shows the
selected style. The selected typewriter is remembered in application
settings and restored the next time the application starts. On a fresh
installation, the default is Brother GX-6750.

Changing the selected typewriter changes the on-screen appearance of the
text. It does not alter the plain-text characters in the document.

======================================================================
10. FONT SIZE
======================================================================

Use the SIZE selector to choose a comfortable text size. The available
range is 10 through 22.

The default size is 16. This larger-than-small default is intended to
make the writing easier to read.

Keyboard controls: - Ctrl++ or Ctrl+= : increase text size. - Ctrl+- :
decrease text size. - Ctrl+0 : reset text size to 16.

Font size affects the display on screen. It does not change the text
stored in the plain-text file. The application remembers the selected
size between sessions.

======================================================================
11. LINE SPACING
======================================================================

Use LINE SPACING to choose: - 1 Single spacing. - 1.5 One-and-a-half
spacing. - 2 Double spacing.

Line spacing changes the visual distance between lines, including lines
created when text wraps. It does not insert extra newline characters
into your document.

The chosen spacing is an appearance preference and is remembered by the
application.

======================================================================
12. LEFT AND RIGHT MARGINS
======================================================================

Use LEFT MARGIN and RIGHT MARGIN to adjust the writing area.

The controls use values from 0 to 20. The values are character-width
units measured using the active font, rather than fixed physical
measurements in inches or centimetres.

LEFT MARGIN controls the indentation from the left side of the page.
RIGHT MARGIN controls the space reserved at the right side, limiting the
width available for writing.

The usual default for a new document is: - Left margin: 11. - Right
margin: 11.

Margin values are saved separately for each document in a companion
settings file. When you reopen a document, the application attempts to
restore its saved margin values. If no companion settings file exists,
the default values are used.

Changing margins affects how the text is displayed and wrapped. It does
not insert spaces at the start or end of every line in the saved
plain-text file.

======================================================================
13. PAPER SIZE AND ESTIMATED PAGE COUNT
======================================================================

Use the Paper dropdown, positioned immediately after Typewriter, to
choose one of three paper sizes:

- A4: 8.27 × 11.69 inches (210 × 297 mm).
- Letter: 8.5 × 11 inches (215.9 × 279.4 mm).
- Foolscap: 8.5 × 13 inches (215.9 × 330.2 mm).

The selected paper size is remembered by the application. It changes the
estimated number of characters per line and writing lines per page; it
does not change the plain-text file or insert page breaks.

The writing area leaves a visual top margin of approximately one inch,
so the first line does not begin right against the top edge of the page.
This is display spacing only; it does not add blank lines to the saved
plain-text document. The page-count estimate also assumes one-inch top
and bottom margins.

The bottom status line shows “Page X of Y (est.)”. X is the estimated
page containing the cursor; it changes as you move through the text. Y
is the estimated total number of pages in the document. Both values are
estimates and are recalculated as the text and layout settings change.

The estimate accounts for the selected paper dimensions, the active
typewriter font and font size, left and right character margins, line
spacing (1, 1.5 or 2), wrapped display lines, and assumed one-inch top
and bottom margins. The count is a guide to manuscript length, not exact
print pagination. Actual printed pages can differ because of printer
settings, font substitution and the layout used by a word processor.

Page numbers are shown only in the status line. The application does not
print page numbers into the writing area or insert page breaks, headers
or footers into the plain-text document.

======================================================================
13. NIGHT MODE
======================================================================

Use the NIGHT MODE switch on the top toolbar.

When enabled, the writing area changes to a dark background with light
text. When disabled, the normal light page with dark text is restored.

Night mode is intended to reduce the brightness of the page when writing
in a dim environment. It changes the display only; it does not change
the saved text.

The application remembers the night-mode preference between sessions.

======================================================================
14. KEY SOUND
======================================================================

Use the SOUNDS switch to turn both sound effects on or off together.
When enabled, the application plays its typing sound for printable
characters and rings the page bell when typing first increases the
estimated total page count. The bell does not ring when navigating or
deleting text.

Sound playback depends on a supported audio player being available on
the Linux system. The sound effects are not recorded in the document.

======================================================================
15. SHORTCUT GUIDE
======================================================================

Use the SHORTCUT GUIDE switch to show or hide the compact keyboard
reference panel.

The guide includes common document commands, text-size controls,
full-screen mode, undo, clipboard operations and navigation keys.

The guide is a reference. It does not replace the keyboard’s normal
editing behaviour.

======================================================================
17. HELP TOGGLE AND SEARCH
======================================================================

The Help toggle is at the far right of the top-toolbar switches. Turn it
on to display this manual inside the application. The manual is
read-only: you can select and search its text, but cannot edit it or
save changes over your writing.

Enter a word or phrase in Search help and press Enter or click Find.
Matches are highlighted in the manual. Use Next match to move to the
next occurrence. Common searches include margins, typewriter, night
mode, autosave, recovery and keyboard shortcuts.

Turn Help off to return to your document. Help temporarily replaces the
visible writing page without replacing the document's text or undo
history. Your cursor position and unsaved changes are preserved. Help
text is not included in your document, word count, autosave or recovery
snapshots.

There is intentionally no separate Quit toggle or Quit button. This is
a safety choice: it reduces the chance that a user will hit Quit by
mistake and close the application after typing pages of work. Use Save
and Quit, or Ctrl+Q, so the application's save and backup routine runs
before the application closes.

======================================================================
18. SHOW SCROLLBAR
======================================================================

Use SHOW SCROLLBAR to display or hide the vertical scrollbar at the
right side of the writing area.

The scrollbar helps you move through longer documents. Hiding it gives
the writing page a cleaner appearance. Text navigation and scrolling
remain available through normal keyboard or mouse actions supported by
the application.

======================================================================
18. SHOW FILE PATH
======================================================================

Use SHOW FILE PATH to display or hide the file-location line in the
footer.

When enabled, the footer displays the current file name and location.
For an unsaved document, it shows the default document directory.

This switch changes only what is displayed in the interface. It does not
move, save, rename or otherwise change your file.

======================================================================
19. HELP TOGGLE AND BUILT-IN MANUAL
======================================================================

The Help toggle is intended to display this manual inside The Writer’s
Companion whenever help is needed. It is positioned at the FAR RIGHT of
the row of toolbar toggles so it is easy to find and remains separate from
the everyday writing controls.

When Help is switched on, the manual should appear in a read-only view.
The text can be searched, but it cannot be edited or saved over the user's
work. Switching Help off returns the user to the document that was open
before Help was displayed. The document text, cursor position and editing
state should be preserved. The manual should not be treated as the user's
current document, and its words should not affect the document word count.

The built-in manual is intended to make instructions and the feature list
available without leaving the writing application.

======================================================================
20. STATUS BAR AND WORD COUNT
======================================================================

The status area reports: - The current left and right margin values. -
The selected line-spacing value. - The cursor’s line and column
position. - The current word count.

The word count is based on groups of text separated by whitespace. It is
a simple live count intended to help writers monitor progress. It does
not provide a page count, character count, reading-time estimate,
paragraph count or word target.

The cursor position updates as you type or move the cursor. Text may
wrap visually when it reaches the right margin; a wrapped display line
is different from a new paragraph created by pressing Enter.

======================================================================
20. KEYBOARD SHORTCUTS
======================================================================

Ctrl+N Document Ctrl+O Open document Ctrl+S Save document Ctrl+Q
Save and quit Ctrl++ Increase text size Ctrl+= Increase text size Ctrl+-
Decrease text size Ctrl+0 Reset text size to 16 F11 Toggle full-screen
mode Ctrl+Z Undo Ctrl+C Copy selected text Ctrl+X Cut selected text
Ctrl+V Paste

Common navigation keys: Home Move to the start of the current line End
Move to the end of the current line Page Up Move up through the document
Page Down Move down through the document Backspace Delete the character
before the cursor Delete Delete the character after the cursor

Arrow keys, mouse selection and other standard text-editing actions are
also available through the text editor.

======================================================================
21. EDITING TEXT
======================================================================

Click in the writing area and begin typing. Use Enter to create a new
line or paragraph. Text automatically wraps when it reaches the
available writing width.

Use Backspace to delete the character before the cursor and Delete to
remove the character after it. Select text with the mouse or normal
keyboard selection methods. Copy, cut and paste use the usual clipboard
shortcuts.

Undo is available with Ctrl+Z.

The application is designed for plain text. It does not provide rich
text styling such as bold, italic, underlining, coloured words, styled
headings, embedded pictures, tables, footnotes or floating objects.

======================================================================
22. SAMPLE TEXT
======================================================================

A new, empty document displays a sample paragraph to demonstrate the
selected typewriter style:

“This is sample text for the selected typewriter name. The quick brown
fox jumped over the lazy dog. Now is the time for all good men to go to
work.”

The typewriter name in the introduction follows the selected preset. The
sample is a visual demonstration, not part of the user’s actual
document. It is excluded from the word count and is intended to be
replaced when the user starts typing.

Opening an existing document displays that document’s contents instead
of adding the sample to it.

======================================================================
23. WHERE FILES AND SETTINGS ARE STORED
======================================================================

DEFAULT DOCUMENT FOLDER ~/Documents/Writers_Companion/

APPLICATION INSTALLATION ~/Documents/Writers_Companion_App/

APPLICATION PREFERENCES ~/.config/wills-travel-writer/settings.json

RECOVERY AND BACKUP DATA ~/.local/share/writers-companion/

The exact installed application files may depend on the package and
installer version. The installer installs the application for the
current Linux user.

A document’s margin settings are stored in a companion JSON file beside
the document. For example:

    MyStory.txt.wc-settings.json

The text document itself remains a plain UTF-8 text file.

======================================================================
24. INSTALLATION AND LAUNCHING
======================================================================

The application is designed for Linux. The supplied ZIP includes the
Python application, installer, bundled font files and their licence
notices, typing sound and application icon.

General installation: 1. Download the versioned ZIP into your Downloads
folder. 2. Extract the ZIP. 3. Open a terminal in the extracted
application folder. 4. Make the installer executable if necessary: chmod
+x install.sh 5. Run the installer: ./install.sh

Follow the installation instructions supplied with the particular
release. The installer creates the application files and launcher for
the current Linux user and prepares the default document folder.

The application requires Python 3 and Tkinter. Optional typing sound
depends on a supported audio player. No online account is required.

Use the install command provided for your exact version. Some earlier
packages contained an extra folder inside the ZIP, so the directory
containing install.sh may differ between releases.

======================================================================
25. TROUBLESHOOTING
======================================================================

THE APPLICATION DOES NOT START - Confirm the installation completed
without errors. - Try launching it from a terminal to see any error
message. - Check that Python 3 and Tkinter are installed. - Confirm that
the launcher points to the installed application.

THE INSTALLER SAYS install.sh CANNOT BE FOUND - You may be in the parent
directory rather than the directory that contains install.sh. - Use the
file manager to locate install.sh, or run: find “$HOME/Downloads” -name
install.sh - Follow the instructions for the exact ZIP version you
downloaded.

THE TYPING SOUND DOES NOT PLAY - Turn on Key Sound. - Confirm a
supported audio player is installed. - The writing functions do not
require the sound to work.

THE FONT LOOKS DIFFERENT - Confirm the bundled fonts were installed by
the package installer. - Restart the application after font
installation. - The named typewriter styles are approximations using
bundled monospaced fonts; they are not exact recreations of original
manufacturers’ typefaces.

A DOCUMENT DOES NOT LOOK THE SAME WHEN REOPENED - Plain-text files store
characters, not their font or line spacing. - Select the preferred
typewriter and spacing in the application. - The application attempts to
restore per-document margin settings from the companion settings file.
Keep that file beside the document.

I AM ASKED TO SAVE A NEW DOCUMENT AFTER FIVE MINUTES - This is expected.
The application cannot silently save a new document without knowing its
file name and location. - Choose Save to name the file, or continue
writing and save later.

A RECOVERY COPY IS OFFERED AT STARTUP - It means a recovery snapshot
from an earlier session was found. - Choose to open it if it contains
the writing you need. - Review the recovered text and save it under an
appropriate file name.

======================================================================
26. CURRENT LIMITATIONS
======================================================================

The Writer’s Companion is a plain-text writing tool. The current
application does not provide these features through its normal
interface:

-   Rich-text formatting such as bold, italic, underline or coloured
    text.
-   Styled headings, images, tables, footnotes or embedded objects.
-   Find and replace.
-   Spell checking, grammar checking or thesaurus.
-   Automatic hyphenation.
-   Chapter management or book-project organisation.
-   Automatic table of contents for a manuscript.
-   Character count, page count, paragraph count, reading-time estimate
    or word-count targets.
-   Page breaks, pagination, page numbering, headers or footers.
-   Print preview or a normal Print button.
-   Dedicated PDF, EPUB, DOCX, HTML or RTF export.
-   A configurable backup browser or restore-history interface.
-   Native Windows or macOS support.

The source contains a printing routine, but it is not connected to a
normal visible Print button in the main interface. The app is intended
primarily for composing and saving plain text.

======================================================================
27. QUICK REFERENCE
======================================================================

NEW Click New or press Ctrl+N.

OPEN A FILE Click Open… or press Ctrl+O.

SAVE Click Save or press Ctrl+S.

SAVE AND QUIT Click Save and Quit or press Ctrl+Q.

CHANGE TYPEWRITER STYLE Use the Typewriter selector. The fresh-install
default is Brother GX-6750.

CHANGE TEXT SIZE Use Size, Ctrl++ or Ctrl+= to increase, Ctrl+- to
decrease, or Ctrl+0 to reset to 16.

CHANGE LINE SPACING Use the Line spacing selector: 1, 1.5 or 2.

CHANGE MARGINS Use Left margin and Right margin. The usual new-document
defaults are 11 and 11.

TURN ON DARK PAGE Turn on Night mode.

TURN TYPING SOUND ON OR OFF Use Key Sound.

SHOW KEYBOARD SHORTCUTS Turn on Shortcut guide.

SHOW OR HIDE THE SCROLLBAR Use Show scrollbar.

SHOW OR HIDE THE FILE LOCATION Use Show file path.

RECOVER AFTER AN INTERRUPTION If offered a recovery copy at startup,
choose whether to reopen it.

======================================================================
28. FEATURE CHECKLIST
======================================================================

DOCUMENT WORK [+] Create a new document [+] Open a text file [+] Save a
text file [+] Save and quit [+] Prompt before replacing unsaved work [+]
UTF-8 plain-text documents [+] Default document folder [+] Per-document
margin settings

WRITING AND DISPLAY [+] Large writing page [+] Automatic word wrapping
[+] Typewriter-style selector with 15 named presets [+] Bundled
monospaced fonts [+] Font size range 10-22 [+] Default font size 16 [+]
Single, 1.5 and double line spacing [+] Adjustable left and right
margins [+] Night mode [+] Optional typing sound [+] Optional vertical
scrollbar [+] Optional file-path display [+] Shortcut guide [+] Built-in read-only searchable Help manual [+] Live
word count and cursor-position status [+] Full-screen mode

PROTECTION [+] Five-minute document autosave for named files with
changes [+] Prompt to save a new, unnamed document at the five-minute
check [+] Recovery snapshots approximately every 30 seconds [+] Startup
offer to reopen recovery text [+] Timestamped backup attempt when
quitting

INSTALLATION [+] Linux installer [+] Desktop launcher [+] Bundled font
files and licence notices [+] Application icon [+] No online account
required

This guide describes the features available in the application version
for which it is supplied. Controls and behaviour can change in later
releases. If the application version changes, review this manual against
the updated source before bundling it with a new release.

======================================================================
END OF GUIDE
======================================================================


======================================================================
RELEASE UPDATE: PAPER FORMATS AND PAGE BELL
======================================================================

The Paper dropdown appears immediately after the Typewriter selector and
offers A4, Letter and Foolscap. A5 has been removed. The selection is
remembered in application settings and used by the estimated page
capacity calculation. Typeface Size labels the font-size selector.

The single Sounds switch controls both the keyboard typing sound and the
page-boundary bell. When enabled, the bell sounds when typing first
increases the estimated total page count. It does not ring when moving
the cursor or deleting text. The page count remains an estimate; the
current release does not insert physical page breaks into the document.
