Article Format Adjustment

Source: https://github.com/aipoch/medical-research-skills

Validation Shortcut

Run this minimal command first to verify the supported execution path:

python scripts/format_adjuster.py --help

When to Use

• You have a draft in Word/LaTeX/Markdown and must submit it in a different format (e.g., DOCX → LaTeX).
• A journal or school requires strict typography rules (fonts, sizes, margins, spacing) and you want them applied automatically.
• You need to enforce consistent figure/table captions and table border styles across the whole manuscript.
• You must switch or standardize citation/reference styles (e.g., IEEE, APA, GB/T 7714) before submission.
• You want to apply a known journal template (e.g., Nature/Science/Elsevier) or a custom JSON/YAML template to multiple papers.

Key Features

• Format conversion

  • Word (.docx) ↔ Markdown (.md)
  • Word (.docx) ↔ LaTeX (.tex) (via Pandoc)
  • Markdown (.md) ↔ LaTeX (.tex)
  • Preserves document structure and basic formatting as much as possible

• Full formatting adjustment

  • Typography: fonts, font sizes (body/headings/footnotes), line spacing, margins, paragraph indentation and spacing
  • Figures/Tables: caption font size, caption position, table font, table border/line styles
  • References: citation styles (APA/MLA/Chicago/IEEE/GB/T 7714), reference list formatting, in-text citation formatting
  • Terminology: first-occurrence abbreviation annotation, terminology consistency checks, unit formatting standardization

• Journal template management

  • Built-in templates (e.g., Nature, Science, IEEE, Elsevier)
  • Template download by journal name (best-effort from official sources/Overleaf)
  • Custom templates via JSON/YAML configuration

• Validation

  • Checks whether the output meets the configured formatting requirements.

Dependencies

Runtime

• Python >= 3.8

Python packages (typical)

• python-docx (Word read/write)
• markdown (Markdown processing)
• PyYAML (YAML parsing)
• requests (template download)
• beautifulsoup4 (HTML parsing)

System tools

• pandoc (required for DOCX ↔ LaTeX conversions)
  • Windows: choco install pandoc
  • macOS: brew install pandoc
  • Linux (Debian/Ubuntu): apt install pandoc

Note: Exact package versions depend on requirements.txt in your repository.

Example Usage

1) Apply a built-in journal template (DOCX → formatted DOCX)

python scripts/init_run.py \
  --input paper.docx \
  --journal "Nature" \
  --output paper_formatted.docx

2) Apply a custom configuration (MD → formatted MD)

python scripts/init_run.py \
  --input paper.md \
  --config formats/my_journal.json \
  --output paper_adjusted.md

3) Download a journal template configuration

python scripts/init_run.py \
  --download-template "Science" \
  --output templates/science_format.json

4) Minimal end-to-end runnable Python example (module usage)

from scripts.format_converter import FormatConverter
from scripts.format_adjuster import FormatAdjuster

def run(input_file: str, config: dict, output_file: str):
    converter = FormatConverter()
    adjuster = FormatAdjuster(config)

    # 1) Normalize to Markdown as an intermediate representation
    md = converter.to_markdown(input_file)

    # 2) Apply formatting rules
    formatted_md = adjuster.apply_format(md, config)

    # 3) Validate against the same rules
    ok = adjuster.validate_format(formatted_md, config)
    if not ok:
        raise RuntimeError("Validation failed: output does not meet the configured requirements.")

    # 4) Convert back to the desired output format inferred from output_file
    converter.from_markdown(formatted_md, output_file)

if __name__ == "__main__":
    config = {
        "font": {"body": "Times New Roman", "body_size": 10},
        "spacing": {"line_space": "single", "paragraph_space": 6, "indent": 0.5},
        "margins": {"top": 2.54, "bottom": 2.54, "left": 2.54, "right": 2.54},
        "references": {"style": "Nature", "format": "numbered"},
        "figures": {"caption_position": "below", "font_size": 9},
        "tables": {"caption_position": "above", "font_size": 9, "borders": True},
    }
    run("paper.docx", config, "paper_formatted.docx")

Implementation Details

Processing pipeline

1. Detect input format (.docx / .md / .tex)
2. Convert to Markdown as a unified intermediate representation
3. Apply formatting rules from a selected journal template or custom config
4. Validate the formatted result against the config
5. Convert to target format (DOCX/MD/TEX)

Core modules (typical responsibilities)

• format_converter.py
  • Conversion engine between Word/Markdown/LaTeX
  • Uses Pandoc for conversions involving LaTeX and/or DOCX where needed
• format_adjuster.py
  • Applies typography, figure/table, and reference formatting rules
  • Provides validation routines to check compliance
• template_downloader.py
  • Downloads template/config by journal name (best-effort)
  • Parses web sources (often via requests + beautifulsoup4)
• format_validator.py
  • Performs rule-based checks (margins, font sizes, caption placement, citation style selection, etc.)

Configuration schema (key parameters)

A configuration file (JSON/YAML) typically includes:

• font
  • body, body_size, title, title_size, caption, caption_size
• spacing
  • line_space (single / 1.5 / double)
  • paragraph_space (e.g., points)
  • indent (e.g., first-line indent)
• margins
  • top, bottom, left, right (commonly in cm)
• references
  • style (e.g., IEEE, APA, GB/T 7714-2015)
  • format (e.g., numbered, author-year)
• figures / tables
  • caption_position (above / below)
  • font_size
  • borders (tables)

CLI parameters (behavior)

• --input: input file path (required)
• --output: output file path (auto-generated if omitted)
• --config: path to JSON/YAML config (uses built-in default if omitted)
• --journal: journal name (selects a built-in or downloaded template)
• --download-template: journal name to download a template config
• --format: output format (docx / md / tex), defaults to the input format

When Not to Use

• Do not use this skill when the required source data, identifiers, files, or credentials are missing.
• Do not use this skill when the user asks for fabricated results, unsupported claims, or out-of-scope conclusions.
• Do not use this skill when a simpler direct answer is more appropriate than the documented workflow.