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

One sentence per line? #1132

Open
RalfJung opened this issue May 26, 2021 · 13 comments
Open

One sentence per line? #1132

RalfJung opened this issue May 26, 2021 · 13 comments

Comments

@RalfJung
Copy link
Member

The docs currently use a fixed-width style for formatting the source, so even small changes (adding a single word somewhere) can lead to large diffs. This also amplifies conflicts.

It might be worth to consider using one-sentence-per-line or one-logical-unit-per-line (allowing line-breaks at reasonable places even inside sentences). I have made good experience with that formatting. The change doesn't have to happen all at once; when existing text is changed one could encourage also changing it to the new format.

Cc @jyn514

@rylev
Copy link
Member

rylev commented Jul 1, 2021

I'd personally prefer to each paragraph on its own line. Most editors can visually line break (making reading the raw markdown easy).

@RalfJung
Copy link
Member Author

RalfJung commented Jul 1, 2021

That makes diffs quite bad though -- diff is line-based, which aligns well with one-sentence-per-line IMO.

@rylev
Copy link
Member

rylev commented Jul 1, 2021

That's true though I think GitHub's diff can handle intra-line diffs a bit better than plain diff, but this doesn't make local diffing nicer. I'm fine with moving to a per line scheme, but is their tooling that will do this automatically. It would be a huge when to not have to think about this at all when writing (similar to how rustfmt can be run on save in many editors).

@RalfJung
Copy link
Member Author

RalfJung commented Jul 1, 2021

Yeah tooling would be nice, but I'm not aware of any.

@pierwill
Copy link
Member

I posted a (duplicate) issue in which I further discuss (rehash?) the benefits of this approach. I think it even tends to improve writing quality.

@tshepang
Copy link
Member

@RalfJung this looks like can be closed, given #1241

@RalfJung
Copy link
Member Author

#1241 was closed as a duplicate of this one. If we also close this one there's none left to track this. ;)

@tshepang tshepang pinned this issue Aug 19, 2022
@jyn514
Copy link
Member

jyn514 commented Aug 24, 2022

I'm fine with moving to a per line scheme, but is their tooling that will do this automatically. It would be a huge when to not have to think about this at all when writing (similar to how rustfmt can be run on save in many editors).

this is my opinion as well - unless we have some way to enforce it, we'll use an enormous amount of energy to switch over the existing docs only to have new PRs not follow the format (and either have another round of back and forth to fix it, or it just won't get fixed because the reviewer won't think about it). Tooling would greatly reduce the effort for both the initial switch and continued maintenance.

FWIW I would expect this to be fairly simple to write ourselves - the hard part is distinguishing line endings from abbreviations (e.g.), but maybe there's some existing dictionary we can use?

tshepang added a commit to tshepang/rustc-dev-guide that referenced this issue Aug 25, 2022
@tshepang
Copy link
Member

am working on the tool... it is so far not so clever, but I could already start using to migrate things gradually

tshepang added a commit to tshepang/rustc-dev-guide that referenced this issue Oct 18, 2022
tshepang added a commit to tshepang/rustc-dev-guide that referenced this issue Oct 18, 2022
@Noratrieb
Copy link
Member

In the meantime, can we just disable the current checks? Reviewers can complain if a line gets too unwieldy. The current checks make it really annoying to write the documentation, which I consider to be really bad. Having a tool to enforce semantic line breaks sounds ok, but I think having no tool is way better than the current bad tool.

@saethlin
Copy link
Member

We've been waiting over a year for the tool to arrive. It seems foolish to wait indefinitely. @tshepang are you still working on that tool? If not, we should invite others to finish it up.

@Noratrieb
Copy link
Member

I have deleted the checks in #1952, btw.

@tshepang
Copy link
Member

tshepang commented Mar 31, 2024

@saethlin I have intention to finish the tool, but I hope that does not discourage anyone to build something finished... my approach is bad anyways, and am very slow.

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

7 participants