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

Site files are not schema-valid #6563

Closed
Vampire opened this issue Mar 12, 2019 · 2 comments

Comments

Projects
None yet
2 participants
@Vampire
Copy link
Contributor

commented Mar 12, 2019

Currently the validate property of the maven-site-plugin is disabled because of a bug in xml-maven-plugin that was fixed in 1.0.2.
Since checkstyle in the meantime uses that version, the validate could be enabled again.
Unfortunately in the long time it was off, some invalid markup made it into the site files.

I'd like to suggest to reenable the validation and fix the invalid parts.
In detail this would be:

  • text directly within <section> needs to be wrapped in paragraphs
  • block tags like <div> or <ul> must not occur within paragraphs, but besides
  • <source> tag does not allow class attribute but instead you have to wrap a <div> around it and adapt the CSS accordingly to have the wanted effect
  • Within <body> only <section> is allowed, not <div> like in the release notes, but via CSS placement it can still look the same in the end even with the release date within the section which is semantically cleaner anyway as it belongs to the respective version (this also needs to be changed in the release notes generator template)
  • Not exactly due to schema-validity, but because the wrap-content style needs to be changed anyway I also suggest to change it a tad bit, so that not white-space: pre-wrap but white-space: pre-line is used.
    With the former all whitespace is preserved, but if space gets narrow (too long text, too much zoom) the text is automatically wrapped.
    With the latter line-breaks are preserved, but leading spaces are stripped from each line.
    This means, that you can then properly indent the code in the sources or you can have them at column 0 or anywhere in between and it will look the same on the final page so it doesn't matter if someone indents it accidentally for example unlike currently.
    This also means if you want to have visual indentation on the page, you have to use a non-breaking space as &#xa0;.
    Another big plus you get which is why I looked into it actually is, that also trailing spaces get removed which looks nicer in the result.
    grafik
    vs.
    grafik
    And in the code
    grafik
    vs.
    grafik

Vampire added a commit to Vampire/checkstyle that referenced this issue Mar 12, 2019

Issue checkstyle#6563: re-enable maven-site-plugin validation as unde…
…rlying problem was fixed in xml-maven-plugin 1.0.2 and fix invalid markup
@Vampire

This comment has been minimized.

Copy link
Contributor Author

commented Mar 12, 2019

Result of proposed changes from PR can be looked at under http://kautler.net/cs/

@romani romani closed this in #6514 Mar 16, 2019

romani added a commit that referenced this issue Mar 16, 2019

Issue #6563: re-enable maven-site-plugin validation as underlying pro…
…blem was fixed in xml-maven-plugin 1.0.2 and fix invalid markup

@romani romani added this to the 8.19 milestone Mar 16, 2019

@romani

This comment has been minimized.

Copy link
Member

commented Mar 16, 2019

fix is merged.

Vantuz added a commit to Vantuz/checkstyle that referenced this issue Apr 3, 2019

Issue checkstyle#6563: re-enable maven-site-plugin validation as unde…
…rlying problem was fixed in xml-maven-plugin 1.0.2 and fix invalid markup
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.