Remove trailing whitespace from docs. #214

Merged
merged 3 commits into from Dec 26, 2016

Projects

None yet

3 participants

@bk2204
Contributor
bk2204 commented Apr 25, 2014

Trailing whitespace is widely considered a bad idea, so this commit removes it from all the AsciiDoc files in the docs directory.

This change only affects the docs directory to keep the amount of changes something I could reasonably review. The only difference when processing the docs before and after this change is the last updated timestamp, so this change has no functional impact.

The command I used to perform this was:

cd docs; for i in $(git grep -lP '\s+$'); do [[ -z ${i%%*.pdf} ]] && continue;  ruby -pi -e '$_.gsub!(/\s+$/, "\n")' $i; done
@mojavelinux
Member

The editor that @graphitefriction is using is either adding or leaving behind these trailing whitespaces. I'll look into a switching that setting and also adding this recommendation to the writer's style guide.

Keep in mind that Asciidoctor strips all trailing whitespace when it reads in the file, so this won't affect the behavior of Asciidoctor...though it could shave off a few milliseconds from processing.

@mojavelinux
Member

Ironic to note that if you did this to a Markdown document, you would break any hard wraps, which is why I think using trailing whitespace for formatting is an absolutely terrible idea :)

@mojavelinux
Member

I also agree that trailing whitespace should not be left in the file.

@olleolleolle
Contributor
olleolleolle commented Dec 15, 2016 edited

Hi! Can we resolve this issue?

  • Closing it without change?
  • Teaching users about settings in editors by adding meta-docs (i.e. document how to author documentation)?
  • Adding a pre-commit Git script one must run?
  • Adding a Travis build rule that fails edits to .adoc files when they have whitespace at end-of-line?
@mojavelinux
Member

What needs to happen here first is that this change needs to be reapplied. If someone wants to run with it, feel free to submit a new PR.

I completely agree that moving forward we should have:

  • .editorconfig file in the root of the project with the shared settings
  • a validation on the CI job that runs* to ensure no trailing whitespace is added

* CI runs the travis rake task. We could add a validate task to the Rake build that checks for trailing whitespace and throws an exception if it is detected. The failure routine will catch it and flag the PR.

bk2204 added some commits Dec 19, 2016
@bk2204 bk2204 Remove trailing whitespace.
Trailing whitespace tends to cause diff noise and makes end-of-line commands
in editors act strangely.
611907e
@bk2204 bk2204 Fail travis target on trailing whitespace. 74af301
@bk2204
Contributor
bk2204 commented Dec 19, 2016

I've adjusted the commit to remove all the existing trailing whitespace in *.adoc files. Additionally, I've made the travis target raise an exception on trailing whitespace and added a .editorconfig covering *.adoc.

I wasn't sure if we wanted to cover some settings more globally. For example, we probably want to require UTF-8 for all files, as well as using LF for line endings. Let me know what changes you want, and I'll resubmit.

@mojavelinux
Member

Thank you @bk2204!

we probably want to require UTF-8 for all files, as well as using LF for line endings.

👍 to both of these validations.

@bk2204 bk2204 Add a basic .editorconfig file. 4282fed
@mojavelinux
Member

Let's go ahead and merge this and handle the other enhancements in a follow-up PR.

@mojavelinux mojavelinux merged commit 3e4d948 into asciidoctor:master Dec 26, 2016

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@mojavelinux
Member

Thanks @bk2204!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment