Styles and options¶

A redline has two looks and two options that work with both:

ope redline ./Policy --from-commit v1.0.0                                  # blackline
ope redline ./Policy --from-commit v1.0.0 -O redline.style=side-by-side    # two columns
ope redline ./Policy --from-commit v1.0.0 -O redline.collapse=on           # only the changes
ope redline ./Policy --from-commit v1.0.0 --blame                          # who changed what

Every redline starts with a change summary after the title: the two versions with their commits, dates and authors, the number of replaced, inserted, deleted and moved passages and of other changes (formatting, link targets, heading levels, tasks), the changed sections with their page numbers, and the commits between the two versions. The table of contents shows the number of changes next to each changed section, marks new sections with "new" and lists removed headings struck through.

Blackline¶

The default. The document is the new version, with every change marked where it happened:

• Inserted text is blue with a double underline, removed text vermilion and struck through. A replaced passage shows the old words followed by the new ones.
• Moved text is purple: struck through where it was, underlined where it is now. A label at each end names the section of the other end and links to it.
• A black bar in the left margin marks every group of changed blocks.
• Formatting changes, link targets, task states and heading levels get a dotted underline or a small label.

The colours are chosen so that inserted and removed text stay apart for readers with red-green colour blindness, and every change also has a form that survives greyscale printing (underline, strike-through, bar).

Side by side¶

The old and the new document in two columns on landscape pages. Every block of the document sits on its own row, so the old and the new version of a paragraph, a list item or a table always start at the same height. A block that exists in only one version faces a hatched gap ("not in the old version", "deleted", "moved"). Every list item has a row of its own, so a long list stays aligned and can break between pages.

A thin bar between the columns marks the rows that changed; a moved block has a dashed purple bar. Word changes are marked in both columns: removed words in the old column, inserted words in the new one.

Collapse unchanged content¶

With -O redline.collapse=on the redline shows only what changed. The heading of every section that contains a change stays, so the reader knows where a change is. Each run of unchanged blocks becomes one quiet line, for example "⋯ 2 paragraphs unchanged ⋯" or "⋯ unchanged: 4 Contact (1 paragraph) ⋯". Inside a changed list or table, a run of unchanged items or rows is collapsed the same way. Links from the table of contents, the summary and the text to collapsed headings and blocks still work: they point to the collapsed line. In the side-by-side style, a chapter without changes becomes one such line in the table of the chapter before it. A link to a heading that is not in the PDF at all, such as [[#Typo]], stays as plain text, and the command prints a warning.

In the side-by-side style every row shown is a change, so the bar between the columns is left out.

Every combination¶

The example below is a short policy with changed list items, a table with a new row, a changed paragraph and two sections that did not change. The version before was written by one author, the change by another, so the blame strip has two names.

## Scope

This policy applies to all laptops of the team. It covers how devices are handed out, used and returned.

## Rules

- Lock the screen when you leave the desk.
- Install updates once a week.
- Use the password manager for all accounts.
- Store work files on the shared drive.
- Report a lost device within one day.

## Devices

| Device | Owner      | Review |
| ------ | ---------- | ------ |
| Laptop | IT team    | yearly |
| Phone  | Each user  | yearly |

## Contact

Questions go to the service desk. The service desk answers within one working day.

## Exceptions

Test devices are exempt from the update rule.

## Scope

This policy applies to all laptops of the team. It covers how devices are handed out, used and returned.

## Rules

- Lock the screen when you leave the desk.
- Install updates once a month.
- Use the password manager for all accounts.
- Store work files on the shared drive.
- Report a lost or stolen device within one hour.
- Ask the service desk when in doubt.

## Devices

| Device | Owner      | Review    |
| ------ | ---------- | --------- |
| Laptop | IT team    | quarterly |
| Phone  | Each user  | yearly    |
| Tablet | IT team    | yearly    |

## Contact

Questions go to the service desk. The service desk answers within one working day.

## Exceptions

Test devices in the lab are exempt from the update rule. They must not hold customer data.

Which one to use¶

• Blackline for review and approval of a new release: the reader sees the final text with every change in place, in the layout of the released document.
• Side by side when the old wording matters as much as the new one, for example for contracts, specifications or translated texts, and for tables and code that are easier to compare in two columns.
• Collapse for long documents with few changes, and for change requests where only the changes need a decision.
• Blame when a reviewer needs to know who changed a passage and why; the commit message says why.