ClipmanAndroid/Manual.html
Rama main · réplica de lectura del repositorio original.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Clipman Android Test Build Manual</title>
<style>
body {
font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
line-height: 1.55;
max-width: 56rem;
margin: 0 auto;
padding: 1.5rem;
color: #111;
background: #fff;
}
h1, h2, h3 {
line-height: 1.25;
}
code {
font-family: "Cascadia Mono", "Consolas", monospace;
background: #f3f3f3;
padding: 0.1rem 0.25rem;
border-radius: 0.2rem;
}
pre {
background: #f3f3f3;
padding: 1rem;
overflow-x: auto;
}
a {
color: #0645ad;
}
</style>
</head>
<body>
<h1>Clipman Android Test Build Manual</h1>
<p>Clipman Android is a foreground clipboard-history client for Android phones and tablets. It can keep history privately on the phone or merge it with Clipman Server while the app is open. You can browse, search, copy, add, edit, pin, delete, and open links.</p>
<p>This Android package is currently a test build. It is intended for Clipman Server users who want to help test the Android client before a wider Android release.</p>
<p>iPhone and iPad users can <a href="https://apps.apple.com/app/clipman/id6793250105">download Clipman from the App Store</a>.</p>
<h2>Contents</h2>
<ul>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#install">Install</a></li>
<li><a href="#first-run">First Run</a></li>
<li><a href="#main-screen">Main Screen</a></li>
<li><a href="#view-entry">View Entry</a></li>
<li><a href="#settings">Settings</a></li>
<li><a href="#updates">Updates</a></li>
<li><a href="#server-addresses">Server Addresses</a></li>
<li><a href="#privacy">Privacy and Security Notes</a></li>
</ul>
<h2 id="requirements">Requirements</h2>
<ul>
<li>Android 8.0 or newer.</li>
<li>For Server mode, a configured Clipman Server address and token.</li>
<li>For an existing shared history, the same history password used by your other Clipman clients.</li>
<li>Biometric unlock or an Android device credential only when you enable Clipman's optional authentication setting.</li>
</ul>
<p>Clipman Android does not monitor the Android clipboard in the background. Android restricts background clipboard access, and Clipman follows that platform rule. The app syncs while it is open.</p>
<h2 id="install">Install</h2>
<ol>
<li>Copy the APK to the Android device.</li>
<li>Open it from Files, Downloads, or your preferred file manager.</li>
<li>If Android asks whether to allow installing unknown apps from that source, allow it for this install.</li>
<li>Install Clipman.</li>
<li>Open Clipman.</li>
</ol>
<p>The Android package ID is <code>me.onj.clipman</code>.</p>
<h2 id="first-run">First Run</h2>
<p>Clipman can optionally ask Android to unlock with biometrics or your device credential before showing history after you return to the app. This is off by default and can be enabled in Settings.</p>
<p>The first time you configure it:</p>
<ol>
<li>Open Settings if it is not already shown.</li>
<li>Choose <strong>Local</strong> to keep history on this phone, <strong>Shared Folder</strong> to synchronize through Android's system folder picker, or <strong>Server</strong> to use Clipman Server.</li>
<li>For Shared Folder mode, choose a folder offered by Android and enter the same nonblank history password on every participating device. If encrypted backup already has a folder, Clipman reuses it as the initial choice.</li>
<li>For Server mode, open the private <code>.clpconf</code> file from Android's file browser, or choose <strong>Import server connection file</strong> in Clipman Settings. You can also enter the server address and token manually.</li>
<li>Enter a nonblank, preferably unique history password. Clipman Server does not allow passwordless history.</li>
<li>Choose <strong>Save</strong> at the top of Settings.</li>
</ol>
<p>Local mode stores <code>clipman-history.clipdb</code> in Android's private app storage. Shared Folder and Server modes keep that local copy as an offline cache and merge it with the selected storage. If storage is unavailable, changes remain local and retry while Clipman is open. Switching back to a synchronized mode merges both histories, including deletion records, instead of replacing either side.</p>
<p>Enable <strong>Preserve copied formatting and show Rich Text history</strong> in Settings before using Paste when you want Clipman to retain HTML supplied by browsers, messaging apps, email clients, and editors. Formatted entries appear in a separate Rich Text section and are copied back with HTML plus the normal plain-text fallback. Android preserves RTF received from Windows, Mac, or iOS, but Android's standard text clipboard does not publish RTF, so RTF-only entries copy as plain text on Android.</p>
<p>An additional <strong>Include copied images in Rich Text history</strong> setting can store a standalone PNG or JPEG clipboard image. This is also off by default. To add a photo without first copying it, select one photo in Android's Photos, Gallery, or file app, choose Share, and then choose Clipman. Clipman waits for the normal unlock and initial history load, adds the photo to Rich Text history, and reports completion through the status area, sound, and optional haptic feedback. Clipman accepts one shared photo at a time. It preserves an already-compliant image, safely reduces a larger accepted image, and copies the result back as native image data. Retained metadata may contain camera or location information and follows the history's encryption and sync choices.</p>
<p>Your server address, token, and history password remain saved when you switch to Local mode. The token control is disabled until Server mode is selected again. Once configured, the server connection section is collapsed in Settings; use <strong>Show server connection</strong> to open it.</p>
<h2 id="main-screen">Main Screen</h2>
<p>The main toolbar includes:</p>
<ul>
<li><strong>Paste</strong>: adds the current Android clipboard text and available HTML formatting to Clipman history when Rich Text history is enabled.</li>
<li><strong>Quick Clip</strong>: creates a new entry without replacing the Android clipboard. An unfinished draft survives switching apps or Android suspending Clipman until you save or explicitly cancel it.</li>
<li><strong>More</strong>: opens a stable menu containing every other enabled history section, Settings, and Close. Section changes preserve the current group or device filter.</li>
<li><strong>Share to Clipman</strong>: choose Clipman from Android's share sheet to add text, a link, or one photo directly to history. Shared HTML is retained when Rich Text history is enabled.</li>
<li><strong>Filter</strong>: shows All first, followed by named Groups and Devices in separate sections. Group and device names are not prefixed, so TalkBack can read them directly.</li>
<li><strong>Top</strong>: returns to the beginning of the current history list.</li>
<li><strong>Status</strong>: the bottom status combines the number of entries in the current section with local or server state and temporary operation results. It is also a button: activate it to move to the end of the current history list, or long-press it to use the next sort order. TalkBack actions can choose Manual order, Newest first, Oldest first, or Text directly.</li>
</ul>
<p>Group names are case-insensitive. Spellings such as <strong>GitHub</strong>, <strong>Github</strong>, and <strong>github</strong> remain one group. If existing entries use several capitalizations, Clipman displays the spelling used most often and uses the newest spelling to resolve a tie.</p>
<p>Each history row is one accessibility focus target. TalkBack users can move from entry to entry with a single swipe. Very long entries use a bounded row and TalkBack preview and announce <strong>Preview truncated</strong>; viewing, copying, editing, searching and synchronizing still use the complete unchanged entry. An unnamed website link uses a readable offline label followed by its destination without <code>http://</code> or <code>https://</code>; viewing or copying still uses the full unchanged URL. A URL copied with only a trailing screen-reader role word, such as <code>https://example.com link</code>, remains in Links history while Clipman preserves the original stored text.</p>
<p>Double-tap an entry to copy it to the Android clipboard. Clipman announces <strong>Copied to clipboard</strong> and plays the copy sound when sounds are enabled.</p>
<p>Long-press, or use TalkBack actions, to open <strong>View Entry</strong>. The action order matches iPhone and iPad. A named link first offers the copy format opposite to ordinary activation: <strong>Copy Name and Link</strong>, or <strong>Copy Link</strong> when named-link copying is enabled. An unnamed public HTTP or HTTPS link can instead offer <strong>Use Website Title as Name</strong>. Link actions then continue with <strong>Open Link</strong>, <strong>View Entry</strong>, <strong>Edit Entry</strong>, <strong>Pin Entry</strong> or <strong>Unpin Entry</strong>, and <strong>Delete Entry</strong>. An image entry then adds <strong>Save to Photos</strong> followed by <strong>Share</strong>; ordinary entries do not include those two actions. Clipman asks before contacting the selected site, can find useful titles on modern script-heavy pages, ignores misleading bot-check titles, and stores a successful result in the ordinary Name field. Local or private destinations, non-standard ports, credential-related parameters, signed requests and token-like paths are refused. Website titles are never fetched automatically or in bulk.</p>
<h2 id="view-entry">View Entry</h2>
<p><strong>View entry</strong> shows the clipboard text line by line so TalkBack can review it naturally.</p>
<p>For an image entry, View Entry shows an image preview. Activate the preview to see the image at screen size; use <strong>Close image preview</strong> to return. Clipman retains a source filename when one is available and otherwise uses a generic image name rather than guessing the originating app.</p>
<p>If Clipman detects one link in an entry, the history row exposes an <strong>Open link</strong> action.</p>
<p>If Clipman detects multiple links in an entry, <strong>View entry</strong> lists each URL after the text. Each link is its own button and speaks the URL itself, so you know where it goes before opening it.</p>
<h2 id="settings">Settings</h2>
<p>Settings includes:</p>
<ul>
<li><strong>History storage</strong>: switches among private Local history, Shared Folder, and Clipman Server. Each labelled radio choice is one TalkBack focus target. Switching modes keeps the other modes' settings and merges local changes when synchronization resumes.</li>
<li><strong>Shared Folder</strong>: synchronizes encrypted history through a folder selected with Android's system picker. Android may offer on-device folders or installed providers such as Google Drive, OneDrive, or Dropbox. A provider must grant persistent read and write access; Clipman does not receive the provider account. Use the same folder and nonblank history password on each device.</li>
<li><strong>Encrypted history backup</strong>: optionally writes <code>Clipman History.clipdb</code> to a folder selected through Android's system picker. A nonblank history password is required. Use <strong>Restore and merge history backup</strong> to combine its entries and deletions with current history. Server details, tokens, settings, and passwords are not included.</li>
<li><strong>Copy remote additions to Android clipboard</strong>: when another device adds new text to the shared history, Clipman can place that new text on the Android clipboard while the app is open.</li>
<li><strong>Add current clipboard to history on launch</strong>: after a successful unlock and initial history load, Clipman adds the current Android clipboard text to the selected history. This is off by default.</li>
<li><strong>History sort order</strong>: chooses Manual order, Newest first, Oldest first, or Text for normal entries. This per-device display choice does not rewrite shared history or change pinned-entry order.</li>
<li>Deleting an entry updates the visible history immediately while encrypted local storage and optional server synchronization continue in the background. Clipman reports synchronization in progress and reports completion only after the server accepts the deletion. If the local save fails, Clipman restores durable history and reports the error.</li>
<li><strong>Preserve copied formatting and show Rich Text history</strong>: captures and restores Android HTML clipboard formatting and adds Rich Text to the history-section switcher. This is off by default.</li>
<li><strong>Include copied images in Rich Text history</strong>: stores bounded standalone PNG and JPEG clipboard images in the existing history database and lets Clipman receive one selected photo through Android's Share sheet. It is available only when Rich Text history is enabled and is off by default.</li>
<li><strong>Play sounds</strong>: enables Clipman sounds.</li>
<li><strong>Use haptic feedback</strong>: vibrates for supported feedback events.</li>
<li><strong>Confirm before deleting entries</strong>: asks before removing one history entry. This is on by default and can be turned off.</li>
<li><strong>Require biometric or device authentication</strong>: when enabled, locks Clipman whenever it leaves the foreground and requires Android authentication when you return. This is off by default.</li>
<li><strong>Check for updates automatically</strong>: checks the Clipman GitHub release at most once per day while the app is open. Disable it to use only manual checks.</li>
<li><strong>Check Now</strong>: checks immediately and reports whether this Android build is current.</li>
<li><strong>History password</strong>: encrypts local, shared-folder, server-cache, and backup history. Shared Folder and Server modes require a nonblank password.</li>
<li><strong>Server connection</strong>: imports or exports a private <code>.clpconf</code> server file, or shows server address and server token controls for manual setup.</li>
<li><strong>Support Clipman</strong>: opens the optional Tip Jar. Tips do not unlock features or change Clipman's free functionality.</li>
<li><strong>Help</strong>: <strong>Open Manual</strong> opens the rendered Clipman manual in the default browser without saving or discarding Settings changes.</li>
<li><strong>Build information</strong>: shows the app version, readable UTC build time, and exact build stamp so a tester can identify the installed build unambiguously.</li>
</ul>
<p>Choose <strong>Cancel</strong> at the top, or use Android Back, to discard changes and return to history. Choose <strong>Save</strong> to apply changes and return to history. A history refresh that finishes while Settings is open does not close the Settings screen.</p>
<p>Opening a <code>.clpconf</code> file starts Clipman and requires the normal device unlock. An imported connection is shown for review and is not applied until you choose <strong>Save</strong>. If a private-CA HTTPS server generated the file, it can also contain the public authority. Clipman validates that certificate and trusts it only for this server profile and reviewed HTTPS host; it does not install a device-wide Android CA. If a particular Android file provider does not offer Clipman when you open the file, use the import button in Clipman Settings instead. Export offers <strong>Save to Files</strong> and <strong>Share</strong> for the address, token, and matching private authority currently shown in Settings. Share opens Android's native share chooser with temporary read-only access to the file. Every <code>.clpconf</code> file contains the private server token; store and share it securely, never keep it beside an exported clipboard history, and delete it or move it to a password manager after configuring your devices.</p>
<p>When Clipman starts in Shared Folder or Server mode, it displays the encrypted local cache before contacting synchronized storage. While Clipman is in the foreground and Settings is closed, it checks revisions every five seconds. It reads full history only when a revision changes, pauses checks in the background, and progressively slows retries during an outage. Returning to Clipman or closing Settings triggers an immediate refresh.</p>
<p>After a normal addition, edit, pin, title change, or deletion, Clipman saves and encrypts the local database once and uploads it against the known server revision. It downloads, decrypts, merges, and retries the complete history only when another client changed the server first. The status area reports server sync in progress and does not report the change as synced until Clipman Server accepts it.</p>
<p>If only some custom sounds are available, Clipman uses those and falls back to bundled defaults for the rest.</p>
<h2 id="updates">Updates</h2>
<p>When an update is available, Clipman can download the versioned Android APK from the official GitHub release. Before opening the installer, it checks the package name and version, checks the SHA-256 digest when GitHub supplies one, and confirms that the APK is signed by the same application key as the installed Clipman.</p>
<p>Android requires the user to approve application installation. The first in-app update may also ask you to allow Clipman as an installation source. This permission allows Clipman to open Android's installer for its verified update; it does not permit Clipman to install silently. You can remove that permission later through Android's application settings.</p>
<h2 id="server-addresses">Server Addresses</h2>
<p>Server addresses may be entered as:</p>
<pre><code>clipman://host:port
host:port
http://host:port
https://host:port</code></pre>
<p><code>clipman://</code> is Clipman's private-network server scheme. Use HTTPS or a VPN such as Tailscale when connecting across untrusted networks.</p>
<h2 id="privacy">Privacy and Security Notes</h2>
<ul>
<li>Clipman can require Android biometric or device unlock before showing history after you return from another app. This protection is opt-in under Settings.</li>
<li>Current private-CA HTTPS connection files can carry the public authority. Clipman uses it only for the matching server profile and still verifies the server host and certificate. Existing user-installed authorities remain a legacy option when a connection file does not contain one.</li>
<li>Server address, server token, and history password are stored using Android protected app storage.</li>
<li>Local history is stored in Android's private app data. It uses the configured history password when one is present.</li>
<li>Shared Folder mode grants Clipman access only to the folder selected through Android. Clipman stores encrypted history there but does not receive the storage provider's account credentials.</li>
<li>Clipman Android only syncs while the app is open.</li>
<li>The Android clipboard itself is controlled by Android. Once an entry is copied to the clipboard, other apps may be able to paste it according to Android's normal clipboard rules.</li>
</ul>
</body>
</html>