feat: add proposal for cover letter PDF conversion
Add OpenSpec proposal for converting markdown cover letters to PDF format using Swiss business letter standards. The proposal includes: - Swiss letter formatting with scrlttr2 and Swiss Norm configuration - Environment validation for Pandoc and LaTeX - Comprehensive error handling and user guidance - Support for Swiss German formatting and address window positioning This addresses step 7 "Generate PDFs" in the project workflow. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
@@ -0,0 +1,24 @@
|
||||
# Add Cover Letter PDF Conversion
|
||||
|
||||
## Why
|
||||
|
||||
The current system generates cover letters in markdown format, but many job applications require PDF submissions. This creates a gap in the workflow where users must manually convert their generated cover letters to PDF format using external tools. Adding native PDF conversion will complete the job application workflow by providing professionally formatted Swiss-style business letters ready for submission.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add new slash command `/convert-cover-letter` for converting markdown cover letters to PDF
|
||||
- Implement environment validation to check for required tools (Pandoc, LaTeX)
|
||||
- Create Swiss letter template (scrlttr2) with proper formatting for Swiss business correspondence
|
||||
- Support automatic extraction of metadata from markdown frontmatter (sender, recipient, date, subject, etc.)
|
||||
- Generate PDF output in the same directory as the markdown source
|
||||
- Provide helpful error messages and setup guidance when tools are missing
|
||||
|
||||
## Impact
|
||||
|
||||
- **Affected specs**: New capability `cover-letter-pdf-conversion`
|
||||
- **Affected code**:
|
||||
- New slash command: `src/.claude/commands/convert-cover-letter.md`
|
||||
- New LaTeX template: `src/.claude/templates/swiss-letter.tex`
|
||||
- Test environment: Will need to update test directory with new command
|
||||
- **Dependencies**: Requires Pandoc and LaTeX (texlive-latex-base, texlive-lang-german) to be installed on the user's system
|
||||
- **User workflow**: Completes step 7 "Generate PDFs" in the project workflow (see project.md:51)
|
||||
+144
@@ -0,0 +1,144 @@
|
||||
# Cover Letter PDF Conversion Specification
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Cover Letter Detection
|
||||
|
||||
The system SHALL detect the presence of a valid cover letter markdown file in the current directory before attempting conversion.
|
||||
|
||||
#### Scenario: Valid cover letter found
|
||||
- **WHEN** a file named `cover-letter.md` exists in the current directory
|
||||
- **AND** the file contains valid markdown with frontmatter
|
||||
- **THEN** the system proceeds with conversion
|
||||
|
||||
#### Scenario: No cover letter found
|
||||
- **WHEN** no `cover-letter.md` file exists in the current directory
|
||||
- **THEN** the system displays an error message indicating no cover letter was found
|
||||
- **AND** suggests running `/write-cover-letter` first
|
||||
|
||||
#### Scenario: Invalid cover letter format
|
||||
- **WHEN** `cover-letter.md` exists but lacks required frontmatter fields
|
||||
- **THEN** the system displays an error listing the missing required fields
|
||||
- **AND** provides an example of correct frontmatter structure
|
||||
|
||||
### Requirement: Environment Validation
|
||||
|
||||
The system SHALL validate that all required tools are installed before attempting conversion.
|
||||
|
||||
#### Scenario: All tools available
|
||||
- **WHEN** the user runs `/convert-cover-letter`
|
||||
- **AND** Pandoc is installed and accessible
|
||||
- **AND** LaTeX (pdflatex) is installed and accessible
|
||||
- **THEN** the system proceeds with conversion
|
||||
|
||||
#### Scenario: Pandoc missing
|
||||
- **WHEN** the user runs `/convert-cover-letter`
|
||||
- **AND** Pandoc is not installed
|
||||
- **THEN** the system displays installation instructions for Pandoc
|
||||
- **AND** provides platform-specific commands (apt, brew, etc.)
|
||||
- **AND** stops the conversion process
|
||||
|
||||
#### Scenario: LaTeX missing
|
||||
- **WHEN** the user runs `/convert-cover-letter`
|
||||
- **AND** Pandoc is installed but LaTeX is not installed
|
||||
- **THEN** the system displays installation instructions for LaTeX packages
|
||||
- **AND** lists required packages (texlive-latex-base, texlive-lang-german, texlive-latex-extra)
|
||||
- **AND** stops the conversion process
|
||||
|
||||
### Requirement: Swiss Letter Formatting
|
||||
|
||||
The system SHALL generate PDFs using Swiss business letter standards (scrlttr2 with SN configuration).
|
||||
|
||||
#### Scenario: Address window positioning
|
||||
- **WHEN** converting a cover letter to PDF
|
||||
- **THEN** the recipient address is positioned according to Swiss Norm (SN)
|
||||
- **AND** fits within standard Swiss envelope window dimensions
|
||||
|
||||
#### Scenario: Swiss German formatting
|
||||
- **WHEN** the cover letter content contains German text
|
||||
- **THEN** Swiss German hyphenation rules are applied
|
||||
- **AND** date formatting follows Swiss convention (DD.MM.YYYY)
|
||||
- **AND** number formatting uses Swiss conventions
|
||||
|
||||
#### Scenario: Professional layout
|
||||
- **WHEN** converting to PDF
|
||||
- **THEN** the output includes proper margins for Swiss business letters
|
||||
- **AND** sender information is positioned in the header
|
||||
- **AND** contact information (phone, email) is formatted with hyperlinks
|
||||
|
||||
### Requirement: Metadata Extraction
|
||||
|
||||
The system SHALL extract metadata from markdown frontmatter and map it to LaTeX variables.
|
||||
|
||||
#### Scenario: Complete frontmatter
|
||||
- **WHEN** the markdown contains all required frontmatter fields
|
||||
- **THEN** sender information (name, street, city, phone, email) is extracted
|
||||
- **AND** recipient address lines are extracted
|
||||
- **AND** letter details (date, subject, opening, closing, signature) are extracted
|
||||
- **AND** optional enclosures list is extracted if present
|
||||
|
||||
#### Scenario: Minimal frontmatter
|
||||
- **WHEN** the markdown contains only required frontmatter fields
|
||||
- **THEN** the system uses default values for optional fields
|
||||
- **AND** generates a valid PDF without enclosures section
|
||||
|
||||
#### Scenario: Invalid frontmatter structure
|
||||
- **WHEN** the frontmatter cannot be parsed as YAML
|
||||
- **THEN** the system displays a clear error message
|
||||
- **AND** points to the specific syntax error if possible
|
||||
|
||||
### Requirement: PDF Generation
|
||||
|
||||
The system SHALL convert the markdown body to PDF using Pandoc with the Swiss letter template.
|
||||
|
||||
#### Scenario: Successful conversion
|
||||
- **WHEN** all prerequisites are met
|
||||
- **AND** the markdown is valid
|
||||
- **THEN** the system generates a PDF file in the same directory
|
||||
- **AND** names the file `cover-letter.pdf`
|
||||
- **AND** displays a success message with the file path
|
||||
|
||||
#### Scenario: Conversion with enclosures
|
||||
- **WHEN** the frontmatter includes an `enclosures` list
|
||||
- **THEN** the generated PDF includes an enclosures section after the closing
|
||||
- **AND** lists each enclosure item on a separate line
|
||||
|
||||
#### Scenario: LaTeX compilation error
|
||||
- **WHEN** Pandoc generates LaTeX but pdflatex fails to compile
|
||||
- **THEN** the system displays the LaTeX error output
|
||||
- **AND** suggests checking for special characters or formatting issues
|
||||
- **AND** preserves the intermediate .tex file for debugging
|
||||
|
||||
### Requirement: Template Management
|
||||
|
||||
The system SHALL provide and maintain the Swiss letter LaTeX template.
|
||||
|
||||
#### Scenario: Template availability
|
||||
- **WHEN** the `/convert-cover-letter` command is run
|
||||
- **THEN** the system uses the template at `src/.claude/templates/swiss-letter.tex`
|
||||
- **AND** passes it to Pandoc via the `--template` option
|
||||
|
||||
#### Scenario: Template customization
|
||||
- **WHEN** users need to modify letter styling
|
||||
- **THEN** they can edit the swiss-letter.tex template
|
||||
- **AND** changes apply to all subsequent conversions
|
||||
- **AND** the template includes comments explaining customizable sections
|
||||
|
||||
### Requirement: Error Handling
|
||||
|
||||
The system SHALL provide clear, actionable error messages for common failure scenarios.
|
||||
|
||||
#### Scenario: File permission error
|
||||
- **WHEN** the PDF cannot be written due to permissions
|
||||
- **THEN** the system displays a permission error message
|
||||
- **AND** suggests checking directory write permissions
|
||||
|
||||
#### Scenario: Disk space error
|
||||
- **WHEN** PDF generation fails due to insufficient disk space
|
||||
- **THEN** the system displays a disk space error
|
||||
- **AND** suggests freeing up space or choosing a different output location
|
||||
|
||||
#### Scenario: Process timeout
|
||||
- **WHEN** LaTeX compilation takes longer than 30 seconds
|
||||
- **THEN** the system displays a timeout warning
|
||||
- **AND** suggests checking for complex formatting or large embedded content
|
||||
@@ -0,0 +1,58 @@
|
||||
# Implementation Tasks
|
||||
|
||||
## 1. Template Creation
|
||||
- [ ] 1.1 Create Swiss letter LaTeX template at `src/.claude/templates/swiss-letter.tex`
|
||||
- [ ] 1.2 Configure scrlttr2 with Swiss Norm (SN) settings
|
||||
- [ ] 1.3 Add proper encoding (UTF-8, T1 font encoding) for German characters
|
||||
- [ ] 1.4 Implement hyperlinks for email addresses
|
||||
- [ ] 1.5 Add Pandoc variable placeholders for all frontmatter fields
|
||||
- [ ] 1.6 Add inline comments explaining customizable sections
|
||||
- [ ] 1.7 Test template with sample data to ensure proper formatting
|
||||
|
||||
## 2. Slash Command Implementation
|
||||
- [ ] 2.1 Create command file at `src/.claude/commands/convert-cover-letter.md`
|
||||
- [ ] 2.2 Implement cover letter file detection logic
|
||||
- [ ] 2.3 Implement environment validation checks (Pandoc, LaTeX)
|
||||
- [ ] 2.4 Add platform-specific installation instructions
|
||||
- [ ] 2.5 Implement frontmatter parsing and validation
|
||||
- [ ] 2.6 Build Pandoc command with correct arguments
|
||||
- [ ] 2.7 Execute conversion and capture output
|
||||
- [ ] 2.8 Implement error handling for common failure scenarios
|
||||
- [ ] 2.9 Add success message with file path output
|
||||
|
||||
## 3. Error Handling & Messaging
|
||||
- [ ] 3.1 Create clear error message for missing cover letter
|
||||
- [ ] 3.2 Create error message for missing required frontmatter fields
|
||||
- [ ] 3.3 Create installation guide for Pandoc (apt, brew, winget)
|
||||
- [ ] 3.4 Create installation guide for LaTeX packages
|
||||
- [ ] 3.5 Add error handling for YAML parsing failures
|
||||
- [ ] 3.6 Add error handling for LaTeX compilation failures
|
||||
- [ ] 3.7 Add error handling for file permission issues
|
||||
- [ ] 3.8 Add timeout handling for long-running conversions
|
||||
|
||||
## 4. Testing
|
||||
- [ ] 4.1 Test with complete frontmatter and body content
|
||||
- [ ] 4.2 Test with minimal required frontmatter only
|
||||
- [ ] 4.3 Test with optional enclosures list
|
||||
- [ ] 4.4 Test with missing cover-letter.md file
|
||||
- [ ] 4.5 Test with invalid YAML frontmatter
|
||||
- [ ] 4.6 Test with missing required frontmatter fields
|
||||
- [ ] 4.7 Test with special characters (ä, ö, ü, ß) in German text
|
||||
- [ ] 4.8 Test environment validation when Pandoc is missing
|
||||
- [ ] 4.9 Test environment validation when LaTeX is missing
|
||||
- [ ] 4.10 Test error handling for file permission issues
|
||||
- [ ] 4.11 Verify Swiss address window positioning with printed output
|
||||
- [ ] 4.12 Verify date formatting follows Swiss convention
|
||||
|
||||
## 5. Documentation
|
||||
- [ ] 5.1 Document required frontmatter structure
|
||||
- [ ] 5.2 Document system requirements (Pandoc, LaTeX)
|
||||
- [ ] 5.3 Add example cover-letter.md with complete frontmatter
|
||||
- [ ] 5.4 Document troubleshooting steps for common errors
|
||||
- [ ] 5.5 Add template customization guide
|
||||
|
||||
## 6. Integration
|
||||
- [ ] 6.1 Update test directory with new command
|
||||
- [ ] 6.2 Update test directory with new template
|
||||
- [ ] 6.3 Ensure compatibility with existing cover letter generation
|
||||
- [ ] 6.4 Verify workflow integration (step 7 in project.md)
|
||||
Reference in New Issue
Block a user