Generated docs: git chokes on mixed line endings

[deining]

How to reproduce:

git clone https:/remkop/picocli.git
cd picocli/

I'm on a linux box. Immediately after cloning the repo, I do see modified files:

git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   docs/A-Whirlwind-Tour-of-Picocli.html
        modified:   docs/announcing-picocli-1.0.html
        modified:   docs/autocomplete.html
        modified:   docs/build-great-native-cli-apps-in-java-with-graalvm-and-picocli.html
        modified:   docs/feedback.html
        modified:   docs/groovy-2.5-clibuilder-renewal-part1.html
        modified:   docs/groovy-2.5-clibuilder-renewal-part2.html
        modified:   docs/groovy-2.5-clibuilder-renewal.html
        modified:   docs/index.html
        modified:   docs/man/index.html
        modified:   docs/migrating-from-commons-cli.html
        modified:   docs/picocli-2.0-do-more-with-less.html
        modified:   docs/picocli-2.0-groovy-scripts-on-steroids.html
        modified:   docs/picocli-on-graalvm.html
        modified:   docs/picocli-programmatic-api.html
        modified:   docs/quick-guide.html
        modified:   docs/zh/picocli-2.0-do-more-with-less.html
        modified:   docs/zh/picocli-2.0-groovy-scripts-on-steroids.html

no changes added to commit (use "git add" and/or "git commit -a")

git config --get core.autocrlf doesn't print out anythig, so I think the default value of false applies.

I do have an idea what is causing this behavior: the generated html files do have mixed line endings.

For e.g. docs/man/index.html/ has these mixed line endings (on a Linux checkout):

Line 1-1711: LF
Line 1712-1786: CR/LF
Line 1787-19079: LF

AFAICS, The CR/LF in line 1712 - 1786 are introduced by the gradle asciidoctorj-tabbed-code-extension that is used from the gradle asciidoc task.

picocli/gradle/docs.gradle

Lines 2 to 10 in cc0602b

	apply plugin: 'org.asciidoctor.jvm.convert'
	pluginManager.withPlugin('org.asciidoctor.jvm.convert') { // if plugin applied, execute this action
	configurations {
	tabbedCodeExt
	}
	dependencies {
	tabbedCodeExt "com.bmuschko:asciidoctorj-tabbed-code-extension:0.3"
	}
	}

These are the two files that included as inline .css and .js into the generated html documents:

https:/bmuschko/asciidoctorj-tabbed-code-extension/blob/master/src/main/resources/codeBlockSwitch.css
https:/bmuschko/asciidoctorj-tabbed-code-extension/blob/master/src/main/resources/codeBlockSwitch.js

As far as I can see, these files are not part of the picocli repo, but are included during gradle run.

So far my investigations, I hope I'm correct with my analysis. I'm not sure about the best solution for this. My first thought was an additional build step that normalizes the line endings of the generated html files. Maybe there is a more elegant solution that I can't see right now?

I would like to see this resolved. This is an issue that bothers me for quite some time now. With this obstacle removed, it is more likely you will see further commits from me in the future 😄 .

[remkop]

I did a manual dos2unix now but I am still unsure why this happens:
notice that the .gitattributes file has this line:

*.html          text eol=lf

I thought that the above line would prevent this issue... No idea what is going on. Hopefully this manual action will allow you to make progress.

[deining]

I did a manual dos2unix
...
Hopefully this manual action will allow you to make progress.

Yes, this is helpful, thanks a lot.

I just realized that inside the directories /docs/man and /docs/zh, there are further .html files with mixed line endings. Can you please recode these files as well and commit them to the repo? Thanks!

[remkop]

@deining Sorry for the delay...
I finally got around to doing dos2unix on the remaining docs/man and docs/zh directories.

[remkop]

@deining Are we okay to close this ticket, or is there any more work remaining? (Happy to do more, just let me know...)

[deining]

@deining Are we okay to close this ticket, or is there any more work remaining? (Happy to do more, just let me know...)

@remkop Thanks for your action, the issue seems to be resolved.