Notare/README.md

# Ezdoc

A Ruby gem for creating docx files with a simple DSL

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'ezdoc'
```

And then execute:

    $ bundle install

Or install it yourself as:

    $ gem install ezdoc

## Usage

### Basic Example

```ruby
require 'ezdoc'

Ezdoc::Document.create("output.docx") do |doc|
  doc.p "Hello World"
end
```

### Paragraphs

```ruby
Ezdoc::Document.create("output.docx") do |doc|
  # Simple paragraph
  doc.p "This is a paragraph."

  # Paragraph with multiple text runs
  doc.p do
    doc.text "First part. "
    doc.text "Second part."
  end
end
```

### Text Formatting

Formatting uses nested blocks. Nesting combines formatting styles.

```ruby
Ezdoc::Document.create("output.docx") do |doc|
  doc.p do
    doc.text "Normal text "
    doc.b { doc.text "bold" }
    doc.text " and "
    doc.i { doc.text "italic" }
    doc.text " and "
    doc.u { doc.text "underlined" }
  end

  # Nested formatting (bold + italic)
  doc.p do
    doc.b do
      doc.i { doc.text "bold and italic" }
    end
  end
end
```

### Lists

#### Bullet Lists

```ruby
Ezdoc::Document.create("output.docx") do |doc|
  doc.ul do
    doc.li "First item"
    doc.li "Second item"
    doc.li { doc.b { doc.text "Bold item" } }
  end
end
```

#### Numbered Lists

```ruby
Ezdoc::Document.create("output.docx") do |doc|
  doc.ol do
    doc.li "First"
    doc.li "Second"
    doc.li "Third"
  end
end
```

### Tables

```ruby
Ezdoc::Document.create("output.docx") do |doc|
  doc.table do
    doc.tr do
      doc.td "Header 1"
      doc.td "Header 2"
    end
    doc.tr do
      doc.td "Cell 1"
      doc.td { doc.b { doc.text "Bold cell" } }
    end
  end
end
```

### Images

Images can be added to paragraphs, table cells, and list items. Supports PNG and JPEG formats.

```ruby
Ezdoc::Document.create("output.docx") do |doc|
  # Simple image (uses native dimensions)
  doc.p do
    doc.image "photo.png"
  end

  # Image with explicit dimensions (inches, cm, or pixels)
  doc.p do
    doc.image "logo.png", width: "2in", height: "1in"
  end

  # Specify only width (height auto-calculated to maintain aspect ratio)
  doc.p do
    doc.image "banner.jpg", width: "5cm"
  end

  # Image with text in the same paragraph
  doc.p do
    doc.text "Company Logo: "
    doc.image "logo.png", width: "0.5in", height: "0.5in"
  end

  # Image in a table cell
  doc.table do
    doc.tr do
      doc.td "Product"
      doc.td do
        doc.image "product.jpg", width: "1in", height: "1in"
      end
    end
  end

  # Image in a list item
  doc.ul do
    doc.li do
      doc.image "icon.png", width: "16px", height: "16px"
      doc.text " List item with icon"
    end
  end
end
```

### Complete Example

```ruby
Ezdoc::Document.create("report.docx") do |doc|
  doc.p "Monthly Report"

  doc.p do
    doc.text "This report contains "
    doc.b { doc.text "important" }
    doc.text " information."
  end

  doc.p "Key Points:"

  doc.ul do
    doc.li "Revenue increased by 15%"
    doc.li "Customer satisfaction improved"
    doc.li { doc.i { doc.text "See appendix for details" } }
  end

  doc.p "Summary Table:"

  doc.table do
    doc.tr do
      doc.td "Metric"
      doc.td "Value"
    end
    doc.tr do
      doc.td "Revenue"
      doc.td "$1.2M"
    end
    doc.tr do
      doc.td "Growth"
      doc.td { doc.b { doc.text "15%" } }
    end
  end
end
```

## API Reference

| Method | Description |
|--------|-------------|
| `p(text)` | Create a paragraph with text |
| `p { }` | Create a paragraph with block content |
| `text(value)` | Add text to the current context |
| `b { }` | Bold formatting |
| `i { }` | Italic formatting |
| `u { }` | Underline formatting |
| `ul { }` | Bullet list |
| `ol { }` | Numbered list |
| `li(text)` | List item with text |
| `li { }` | List item with block content |
| `table { }` | Table |
| `tr { }` | Table row |
| `td(text)` | Table cell with text |
| `td { }` | Table cell with block content |
| `image(path, width:, height:)` | Insert image (PNG/JPEG). Dimensions: `"2in"`, `"5cm"`, `"100px"`, or integer pixels |

## Development

After checking out the repo, run `bundle install` to install dependencies. Then, run `rake test` to run the tests.

```bash
bundle install
bundle exec rake test      # Run tests
bundle exec rake rubocop   # Run linter
bundle exec rake           # Run both
```

## License

The gem is available as open source under the terms of the [MIT License](LICENSE.txt).