Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Follow "semantic line breaks" in the LaTeX sources #2064

Closed
jwakely opened this issue May 11, 2018 · 7 comments
Closed

Follow "semantic line breaks" in the LaTeX sources #2064

jwakely opened this issue May 11, 2018 · 7 comments

Comments

@jwakely
Copy link
Member

jwakely commented May 11, 2018

See http://sembr.org/ and http://rhodesmill.org/brandon/2012/one-sentence-per-line/

The following example makes it hard to grep for "pointer types" in the source, because of an arbitrary line break that would have been better placed before "pointer":

Arithmetic types\iref{basic.fundamental}, enumeration types, pointer
types, pointer-to-member types\iref{basic.compound},

Reformatting everything would be a huge amount of churn and make git blame less convenient, but it would be good to start following this style when making other editing changes.

@jwakely
Copy link
Member Author

jwakely commented May 11, 2018

This one's even worse because we have a line break in the middle of a \defn:

Cv-unqualified scalar types, trivially copyable class types\iref{class}, arrays of
such types, and cv-qualified versions of these
types are collectively called \defn{trivially
copyable types}.

This means to search for all occurrences of "trivially copyable types" you need to search in the generated PDF rather than the sources.

This example also unnecessarily splits "arrays of such types" across two lines.

@tkoeppe
Copy link
Contributor

tkoeppe commented May 11, 2018

I wouldn't be opposed to that being changed :-)

@jensmaurer
Copy link
Member

jensmaurer commented May 24, 2018

We should decide whether "semantic line breaks" should become an editorial guideline.
Pros: see above
Cons: We can no longer press "M-q" (reformat paragraph to fit window width) in emacs to auto-reformat overlong lines. (Not that I do that frequently, because it likely adds no-op diffs to a change.)

@jensmaurer jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label May 24, 2018
@jensmaurer
Copy link
Member

Editorial meeting consensus: This is already the convention; we simply need to document this policy.

@jensmaurer jensmaurer removed the decision-required A decision of the editorial group (or the Project Editor) is required. label Jun 7, 2018
@jensmaurer
Copy link
Member

Added a sentence to the "Source code formatting" section of our "Specification Style Guidelines".

@jwakely
Copy link
Member Author

jwakely commented Jun 27, 2018

Thanks! Should we close this now then?

@jensmaurer
Copy link
Member

Since we're probably not doing fixes for violations unless we're editing in the vicinity, let's close this issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants