Skip to content

read.md

Latest commit

 

History

History
227 lines (163 loc) · 5.62 KB

read.md

File metadata and controls

227 lines (163 loc) · 5.62 KB
Raw

Read Command

The read command extracts and displays the content of specific articles from ZIM archive files. It supports multiple article lookup strategies and provides intelligent content rendering for optimal terminal viewing.

Overview

The read command provides two main usage patterns:

  1. File-specific reading - Read an article from a specific ZIM file
  2. Unified search - Search all available ZIM files for an article

Usage

File-Specific Reading

zim read <file.zim or name> <article>

Examples:

zim read english-wikipedia.zim "Main_Page"
zim read wikipedia_fr "France"
zim read ~/.cache/zim/english-wikipedia.zim "Python (programming_language)"

Unified Search Mode

zim read <article>

The command searches all ZIM files in your library and prioritizes Wikipedia files:

zim read "Albert Einstein"
zim read "Machine Learning"
zim read "The Great Gatsby"

Article Lookup

The read command uses sophisticated article finding strategies to locate articles even with imperfect matching:

Search Strategies

  1. Exact Match - Looks for the exact article title in both modern ('C') and legacy ('A') namespaces
  2. Space/Underscore Variants - Automatically tries:
    • Main_Page ↔ Main Page
    • Python_(programming_language) ↔ Python (programming language)
  3. Parenthetical Cleanup - Removes disambiguation numbers like "(3671)" from titles
  4. Cross-File Search - For Wikipedia files, searches all available Wikipedia ZIM files if not found in the current one

Smart File Selection

In unified search mode, files are prioritized based on content:

  • Wikipedia files get priority over other ZIM types
  • Wikipedia files are smart-ordered by language and scope (all languages, history editions, etc.)

Output Formats

The command intelligently formats content based on its type:

Text Content (text/*)

Plain text content is displayed as-is:

Article: Introduction
======================
This is a plain text article with no formatting.
Multiple paragraphs are preserved.

HTML Content (text/html)

HTML content is processed for optimal terminal display:

  • HTML tags are stripped
  • CSS and JavaScript are removed
  • Text structure is preserved with:
    • Headings converted to ## Title format
    • Lists shown with bullet points (•)
    • Paragraphs separated by double newlines
  • MediaWiki CSS artifacts are specially filtered

Binary Content

Binary bodies are consumed as a stream to verify the archive read without retaining the payload in memory. Use zim extract when the bytes themselves are needed.

For non-text content (images, PDFs, etc.):

Content-Type: image/png
Size: 45.2 KB

💾 Binary content - use 'zim extract' command to save to file

Article Information Display

For each article found, the command displays:

Header Information

📄 Article: Albert Einstein
===============================
📊 Size: 12.3 KB

✅ Found: Albert Einstein
🔄 Redirected to: Albert_Einstein

Content Types

HTML Articles

If HTML is detected but stripped content is minimal:

⚠️  This article appears to be mostly formatting/styles.
💡 Try using: zim serve english-wikipedia.zim
   Then browse to http://localhost:8080 for better viewing

Redirect Handling

The command follows up to 5 redirect hops to find the final article content and shows the redirect path.

Examples

Example 1: Reading a Wikipedia Article

zim read "Albert Einstein"

Output:

✨ Searching all ZIM files for: Albert Einstein
📚 Found in: english-wikipedia.zim
🔍 Looking for: Albert Einstein
✅ Found: Albert Einstein

📄 Article: Albert Einstein
===============================
📊 Size: 12.3 KB

Albert Einstein (14 March 1879 – 18 April 1955) was a German-born
theoretical physicist who is widely held to be one of the greatest
and most influential scientists of all time...

Example 2: Reading with Underscores in Title

zim read "Python_(programming_language)"

The command automatically tries both variants:

  • Python_(programming_language)
  • Python (programming language)

Example 3: Handling Redirects

zim read "US"

Output might show:

🔍 Looking for: US
✅ Found: US
🔄 Redirected to: United_States

📄 Article: United States
==========================
📊 Size: 45.7 KB

The United States of America (USA) is a country primarily located
in North America...

Example 4: Binary Content

zim read commons:Logo_of_Wikimedia_Foundation.svg

Output:

Content-Type: image/svg+xml
Size: 2.1 KB

💾 Binary content - use 'zim extract' command to save to file

Error Handling

Common Error Messages

❌ Article not found: Some Article
💡 Try: zim search english-wikipedia.zim "Some Article"

❌ Article "Some Article" not found in any ZIM file
💡 Try: zim search "Some Article" for similar articles

❌ Failed to follow redirect: redirect chain broken

Solutions

  1. Article not found: Use zim search to find similar articles
  2. Redirect errors: The article may have a broken redirect chain
  3. Permission errors: Ensure you have read access to the ZIM file

Performance Tips

  1. Use exact titles when possible for faster lookup
  2. For HTML-heavy articles, consider using zim serve for better viewing
  3. Unified search is convenient but may be slower for the first article lookup

Related Commands

  • zim search - Find articles by keyword
  • zim list - List all articles in a ZIM file
  • zim extract - Extract binary content to files
  • zim serve - Start a web server for browsing ZIM content