#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Timestamp: 2026-02-04
# File: src/scitex_writer/_usage.py
"""Usage guide content for scitex-writer.
This module contains the usage documentation text, separate from branding logic.
"""
from ._branding import BRAND_ALIAS, BRAND_NAME, get_branded_import_example
_USAGE_TEMPLATE = """
================================================================================
{brand_name} - LaTeX Manuscript Compilation System
================================================================================
Setup:
git clone https://github.com/ywatanabe1989/scitex-writer.git my-paper
cd my-paper
<SCITEX_WRITER_ROOT> = Directory where compile.sh is located
================================================================================
Project Structure
================================================================================
<SCITEX_WRITER_ROOT>/
├── compile.sh # Main compilation script
├── 00_shared/ # Shared metadata (title, authors, keywords, bib_files/)
├── 01_manuscript/ # Main manuscript
├── 02_supplementary/ # Supplementary materials
└── 03_revision/ # Revision responses
================================================================================
Content Files (01_manuscript/contents/)
================================================================================
abstract.tex - Abstract text
introduction.tex - Introduction section
methods.tex - Methods section
results.tex - Results section
discussion.tex - Discussion section
Just write plain LaTeX content. No \\begin{{document}} needed.
================================================================================
Bibliography (00_shared/bib_files/)
================================================================================
Workflow:
1. SAVE authentic .bib from reliable sources -> bib_files/<descriptive>.bib
2. COMPILE -> system auto-merges all .bib with smart deduplication
3. CITE -> use any key from any file in bib_files/
CRITICAL: NO SYNTHETIC/FAKE CITATIONS
- NEVER create non-existent bibliography entries
- NEVER hallucinate author names, titles, or DOIs
- ALL entries MUST be retrieved using scitex MCP tools:
scitex - crossref_search # Search CrossRef (167M+ works)
scitex - crossref_search_by_doi # Lookup by DOI
scitex - openalex_search # Search OpenAlex (280M+ works)
scitex - openalex_search_by_id # Lookup by OpenAlex ID
- If unsure about a citation, DO NOT add it
Auto-Merge Features (battery-included):
- All .bib files in bib_files/ are merged automatically
- Smart deduplication by DOI and title+year
- No manual merge needed
IMPORTANT: BibTeX entries are SINGLE SOURCE OF TRUTH
- NEVER modify existing citation keys
- Use keys exactly as they appear in .bib files
- Check existing keys: grep -r "AuthorName" 00_shared/bib_files/
Directory Structure (keep clean):
00_shared/bib_files/
├── bibliography.bib # AUTO-GENERATED (do not edit)
├── my_papers.bib # Your own publications
├── field_background.bib # Core field references
├── methods_refs.bib # Methods/tools citations
└── related_work.bib # Related work citations
Files to AVOID:
- enriched_*.bib, merged_*.bib, by_*.bib, *.json
How to Cite in LaTeX:
\\cite{{Smith2024_DeepLearning}} -> [1]
\\citep{{Smith2024_DeepLearning}} -> (Smith et al., 2024)
\\citet{{Smith2024_DeepLearning}} -> Smith et al. (2024)
================================================================================
Figures (01_manuscript/contents/figures/caption_and_media/)
================================================================================
File Naming Convention (REQUIRED):
<NN>_<descriptive_name>.<ext> - Image file
<NN>_<descriptive_name>.tex - Caption file (MUST match image basename)
Example:
01_neural_network.png - Image file
01_neural_network.tex - Caption file
Caption File Format (01_neural_network.tex):
%% Figure caption
\\caption{{Architecture of the neural network model.}}
\\label{{fig:01_neural_network}}
Label Convention:
\\label{{fig:<filename_without_extension>}}
- Prefix: fig:
- Filename without extension (exactly as named)
How to Reference in Text:
Figure~\\ref{{fig:01_neural_network}} -> Figure 1
Figure~\\ref{{fig:01_neural_network}}A -> Figure 1A (for panels)
Supported Formats:
PNG, JPEG, PDF, SVG, TIFF, Mermaid (.mmd)
SVG/Mermaid auto-convert to PDF during compilation
Figure Style (REQUIRED for consistency):
import scitex as stx
stx.plt.load_style("SCITEX")
fig, ax = stx.plt.subplots(**stx.plt.presets.SCITEX_STYLE)
Or with figrecipe:
import figrecipe as fr
fr.load_style("SCITEX")
WARNING: Strict naming is REQUIRED for compilation
- Image and caption files MUST have identical basenames
- Label MUST match filename (fig:<filename>)
- Mismatched names cause compilation FAILURE
================================================================================
Tables (01_manuscript/contents/tables/caption_and_media/)
================================================================================
File Naming Convention (REQUIRED):
<NN>_<descriptive_name>.csv - Data file (CSV format)
<NN>_<descriptive_name>.tex - Caption file (MUST match CSV basename)
Example:
01_performance_metrics.csv - Data file
01_performance_metrics.tex - Caption file
CSV Format:
Column1,Column2,Column3
Value1,Value2,Value3
Value4,Value5,Value6
Caption File Format (01_performance_metrics.tex):
%% Table caption
\\caption{{Performance metrics across experimental conditions.}}
\\label{{tab:01_performance_metrics}}
Label Convention:
\\label{{tab:<filename_without_extension>}}
- Prefix: tab:
- Filename without extension (exactly as named)
How to Reference in Text:
Table~\\ref{{tab:01_performance_metrics}} -> Table 1
CSV auto-converts to LaTeX tabular during compilation.
WARNING: Strict naming is REQUIRED for compilation
- CSV and caption files MUST have identical basenames
- Label MUST match filename (tab:<filename>)
- Mismatched names cause compilation FAILURE
================================================================================
Four Interfaces
================================================================================
Python API:
{import_example}
{alias}.usage() # Show this guide
{alias}.compile.manuscript("./my-paper")
{alias}.project.clone("./new-paper")
{alias}.gui("./my-paper") # Launch GUI editor
CLI:
scitex-writer usage # Show this guide
scitex-writer compile manuscript . # Compile manuscript
scitex-writer mcp list-tools # List MCP tools
scitex-writer gui # Launch GUI editor
GUI (pip install scitex-writer[editor]):
scitex-writer gui ./my-paper # Browser-based editor
MCP Tool:
writer_usage() # Returns this guide
================================================================================
Compilation
================================================================================
Shell (BASH_ENV workaround for AI agents):
env -u BASH_ENV /bin/bash -c '<SCITEX_WRITER_ROOT>/compile.sh manuscript --draft'
Makefile (recommended):
make manuscript # Compile manuscript
make supplementary # Compile supplementary
make revision # Compile revision
make all # Compile all documents
make draft # Fast draft (skips bibliography)
make manuscript-watch # Watch manuscript
make supplementary-watch # Watch supplementary
make revision-watch # Watch revision
make all-watch # Watch all documents
Watch Mode (auto-recompile on file changes):
./compile.sh manuscript --watch
./compile.sh -m -w --no_figs # Watch with speed options
Options:
--watch, -w Auto-recompile on file changes (manuscript only)
--draft Skip bibliography processing (faster)
--no_figs Skip figure processing
--no_tables Skip table processing
--no_diff Skip diff generation
--dark_mode Dark background for figures
--quiet Suppress output
Output:
01_manuscript/manuscript.pdf
01_manuscript/manuscript_diff.pdf (tracked changes)
================================================================================
Highlighting for User Review
================================================================================
\\hl{{[PLACEHOLDER: description]}} - Content user must fill in
\\hl{{[CHECK: reason]}} - Claims/facts to verify
================================================================================
Supplementary Materials (02_supplementary/)
================================================================================
Same structure as 01_manuscript/.
IMPORTANT: File Naming Uses NUMERIC Prefixes (Same as Manuscript)
The preprocessing scripts require [0-9]* pattern for all document types.
Use numeric prefixes (01_, 02_, ...) for filenames, NOT S1_, S2_.
File Naming for Supplementary (REQUIRED):
01_descriptive_name.png # Image file (numeric prefix)
01_descriptive_name.tex # Caption file (must match)
01_descriptive_name.csv # Table data (numeric prefix)
Label Convention for Supplementary:
Use S-prefix in LABELS only (not filenames) for clarity:
\\label{{fig:S01_descriptive_name}} # Supplementary Figure S1
\\label{{tab:S01_descriptive_name}} # Supplementary Table S1
Or keep numeric labels and add "Supplementary" in text references:
\\label{{fig:01_descriptive_name}} # Referenced as "Supplementary Figure 1"
Cross-Referencing (Main -> Supplementary):
In 01_manuscript/contents/*.tex:
Supplementary Figure~\\ref{{fig:S01_descriptive_name}}
Supplementary Table~\\ref{{tab:S01_descriptive_name}}
(see Supplementary Methods for details)
Cross-Referencing (Supplementary -> Main):
In 02_supplementary/contents/*.tex:
(as described in the main text)
Figure~\\ref{{fig:01_neural_network}} in the main manuscript
Note: Cross-references work because of xr-hyper package setup
in base.tex with \\link command
================================================================================
Writing Guidelines
================================================================================
Content Standards:
- Write coherent paragraphs, NOT bullet lists
- One claim per paragraph, topic sentence first
- All claims must have citations or evidence
- Follow IMRAD structure (Intro, Methods, Results, Discussion)
Citation Requirements:
- Every factual claim needs a citation
- Cite primary sources, not reviews (when possible)
- Verify all citation keys exist in bib_files/
Figure Requirements:
- Figures must be referenced in text before appearing
- Captions must be self-explanatory (reader understands without main text)
- Include panel labels (A, B, C) for multi-panel figures
- Define all abbreviations in caption
Table Requirements:
- Tables must be referenced in text before appearing
- Define abbreviations in caption or footnote
- Use consistent decimal places and units
================================================================================
Journal Specifications (MUST CHECK BEFORE WRITING)
================================================================================
Word/Character Limits:
- Abstract: typically 150-300 words
- Main text: varies (3000-8000 words common)
- Check journal's "Instructions for Authors"
Figure/Table Limits:
- Many journals limit to 6-8 figures
- Combined figure+table limit may apply
- Excess goes to Supplementary Materials
Reference Limits:
- Some journals cap at 40-60 references
- Check if online-only references allowed
Section Requirements:
- Some journals require specific sections (e.g., "Data Availability")
- Author contributions format (CRediT taxonomy)
- Conflict of interest statement
Format Requirements:
- Line numbering (compile with --draft for this)
- Double spacing requirements
- Figure resolution (typically 300 DPI minimum)
================================================================================
Quality Checklist (Before Compilation)
================================================================================
[ ] No placeholder text remaining (\\hl{{[PLACEHOLDER:...]}})
[ ] All \\hl{{[CHECK:...]}} items verified
[ ] All figures referenced in text: Figure~\\ref{{fig:...}}
[ ] All tables referenced in text: Table~\\ref{{tab:...}}
[ ] All citations exist in bib_files/: \\cite{{...}}
[ ] No bullet lists in main text (use paragraphs)
[ ] IMRAD sections complete and coherent
[ ] Captions are self-explanatory
"""
def get_usage() -> str:
"""Get the usage guide with branding applied.
Returns
-------
str
Formatted usage guide string.
"""
return _USAGE_TEMPLATE.format(
brand_name=BRAND_NAME,
import_example=get_branded_import_example(),
alias=BRAND_ALIAS,
)
__all__ = ["get_usage"]
# EOF
/