cplusplus / cplusplus/draft

Systematically replacing `\linebreak` with `\brk` or `\-`

Open
#8,067 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

P3-Other
Dominant language
TeX
Stars
221
Forks
813
Avg merge
16h 4m
Merged PRs (30d)
36

Description

We have a 113 uses of manual \linebreak in the draft right now, and I'm not convinced that any of them are strictly necessary.

The problem with \linebreak is that unlike \brk{}, it introduces a forced line break, and if anything about the surrounding text changes, breaking at that point may become unnecessary or look totally wrong. It is better to introduce \brk{} for line break opportunities, or \- for soft hyphens. At worst, those have no effect.

Take for example:
https://github.com/cplusplus/draft/blob/06614c2b0ab562f6861cc1870d361387d6006672/source/exec.tex#L1365-L1369

Surely, paragraph justification could have been made happy by introducing a \- or \brk{} somewhere in those \tcodes.

One may argue that it's a waste of time/effort to replace \linebreaks, but I think it sets a bad precedent if we have any of these laying around. People copy that bad precedent. I'm willing to bet that some of these 100+ \linebreaks already look bad in the PDF.

We might even be able to ban the use of \linebreak outright via checks if all goes well.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Search the draft sources for the 113 uses of \linebreak, beginning with the example in source/exec.tex around lines 1365–1369. Review each occurrence in context and determine whether \brk{} or - is a suitable replacement, then inspect the generated PDF for awkward breaks. Done means unnecessary forced breaks have been replaced without introducing visible layout problems.

Written by the indexing model from the issue text.

Assessment

Tech stack
tex
Domain
documentation
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.