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

Table of contents sometimes locates in wrong section (confusion between subsections without id-s) [DATACMNS-1814] #2229

Open
spring-projects-issues opened this issue Oct 9, 2020 · 10 comments

Comments

@spring-projects-issues
Copy link

@spring-projects-issues spring-projects-issues commented Oct 9, 2020

Chealer opened DATACMNS-1814 and commented

The table of contents at the left of the Spring Data JPA Reference Documentation dynamically changes to reflect the precise subsection being shown. The subsections of sections not displaying do not display.

 

The mechanism to detect position in the document appears to be malfunctioning, as I realized that moving forward in the document, the ToC would indicate the opposite. This happened when I was going from section 4 to section 5.

 

When displaying the end of 4.8.3 and the beginning of 5, the ToC correctly contains:

  1. Preface
    1. 1. Project Metadata
    2. 2. New & Noteworthy
    3. 3. Dependencies
    4. 4. Working with Spring Data Repositories
      1. 4.1. Core concepts
      2. 4.2. Query methods
      3. 4.3. Defining Repository Interfaces
      4. 4.4. Defining Query Methods
      5. 4.5. Creating Repository Instances
      6. 4.6. Custom Implementations for Spring Data Repositories
      7. 4.7. Publishing Events from Aggregate Roots
      8. 4.8. Spring Data Extensions

4.8.1. Querydsl Extension

4.8.2. Web support

4.8.3. Repository Populators

  1. Reference Documentation
    1. 5. JPA Repositories
  2. Appendix
    1. Appendix A: Namespace reference
    2. Appendix B: Populators namespace reference
    3. Appendix C: Repository query keywords
    4. Appendix D: Repository query return types
    5. Appendix E: Frequently Asked Questions
    6. Appendix F: Glossary

But after pressing Page down, it displays as if I had went back to 4.5.1:

  1. Preface
    1. 1. Project Metadata
    2. 2. New & Noteworthy
    3. 3. Dependencies
    4. 4. Working with Spring Data Repositories
      1. 4.1. Core concepts
      2. 4.2. Query methods
      3. 4.3. Defining Repository Interfaces
      4. 4.4. Defining Query Methods
      5. 4.5. Creating Repository Instances

4.5.1. XML configuration

Using filters

4.5.2. JavaConfig

4.5.3. Standalone usage

1. [4.6. Custom Implementations for Spring Data Repositories](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#repositories.custom-implementations)
1. [4.7. Publishing Events from Aggregate Roots](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#core.domain-events)
1. [4.8. Spring Data Extensions](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#core.extensions)
  1. Reference Documentation
    1. 5. JPA Repositories
  2. Appendix
    1. Appendix A: Namespace reference
    2. Appendix B: Populators namespace reference
    3. Appendix C: Repository query keywords
    4. Appendix D: Repository query return types
    5. Appendix E: Frequently Asked Questions
    6. Appendix F: Glossary

 

This happens whether using Google Chrome 85 or Firefox 81, -but only when the viewport is sufficiently high. This can happen at 1153 pixels of height, but probably not when just a little less-. The difference between the Spring ToC correct and Spring ToC incorrect screenshots is exactly one Page Up/Down.

It should also be noted that the link for Using filters (in 4.5.1) is broken (it brings to the document's start)


Affects: 2.3.4 (Neumann SR4)

Reference URL: https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#core.repository-populators

Attachments:

Referenced from: pull request #470

Backported to: 2.3.5 (Neumann SR5), 2.2.11 (Moore SR11)

@spring-projects-issues
Copy link
Author

@spring-projects-issues spring-projects-issues commented Oct 9, 2020

Chealer commented

It turns out the other issue I reported by the side is a symptom of the same problem. This bug occurs no matter how high the viewport is.

This is definitely caused by broken sections which have an empty anchor. In this case, the table of contents is confusing section Using filters (a subsection of 4.5.1) with section Custom Namespace Attributes (a subsection of 5.1.1). This bug occurs when the document considers it is positioned in section Custom Namespace Attributes.

I am pretty sure this is related to the following JavaScript warning in the browser console : « Une chaîne vide a été transmise à « getElementById() ». » ("An empty string was passed to getElementById().")
This is triggered by tocbot.min.js.

This may be exposed by an error in the reference, but I imagine there's ultimately a bug in tocbot

@spring-projects-issues
Copy link
Author

@spring-projects-issues spring-projects-issues commented Oct 9, 2020

Chealer commented

This also affects multiple other level 4 sections, including some in section 5.3.3. Using JPA Named Queries. Section Entity State-detection Strategies, however, is not affected, surely because, unlike others, its h5 element has an id attribute.

Ensuring that all headers in the document have an id attribute would surely fix this. However, Tocbot (or perhaps Tocbot's configuration - I do not know Tocbot at all) should be modified so it does not fail that bad with headers with no id. After all, the HTML document appears to be valid (elements do not require id-s)

@spring-projects-issues
Copy link
Author

@spring-projects-issues spring-projects-issues commented Oct 9, 2020

Chealer commented

This also affects level 2 sections, for example in Appendix E

@spring-projects-issues
Copy link
Author

@spring-projects-issues spring-projects-issues commented Oct 14, 2020

Jay Bryant commented

I don't know Jira well, so I won't try to change the issue's status or do anything more than comment.

I have created a PR to address the missing IDs, so that ToC links won't jump to the top of the document:

#470

I can't re-create the other part of this issue (strange rendering on page down. I don't have a monitor big enough to get a viewport that size.

I also noticed some changes that I hadn't yet edited, so I am doing an editing pass against Spring Data JPA's documentation, including that part of it that is in Spring Data Commons. I expect to make that PR tomorrow

@spring-projects-issues
Copy link
Author

@spring-projects-issues spring-projects-issues commented Oct 16, 2020

Jens Schauder commented

Second PR: #471

@spring-projects-issues
Copy link
Author

@spring-projects-issues spring-projects-issues commented Oct 16, 2020

Chealer commented

Thank you Jay,
I am sorry for the misleading initial description, I now struck out the outdated part. All which is needed to reproduce is for Tocbot to consider the currently viewed section to be Custom Namespace Attributes (or any other affected section).

Your change will help, but the solution is merely partial. For example, I suppose the Custom Namespace Attributes section will remain affected

@spring-projects-issues
Copy link
Author

@spring-projects-issues spring-projects-issues commented Nov 13, 2020

Chealer commented

I am afraid that commit d18701a broke the table of contents. I cannot see where the problem comes from as I do not know AsciiDoc, but I am guessing by elimination. Do you see the issue Jay? For example, empty section 5

Also, while f20b508 does help with this issue and fixes the one case I initially reported, as explained in my second comment, this affects several other subsections. The ticket can be marked as being worked on, but for an actual solution, either the whole documentation must be scanned to find all occurrences, or Tocbot needs to be fixed to cope with such sections.

 

@Chealer
Copy link

@Chealer Chealer commented Dec 30, 2020

Can someone with the necessary permission remove "Status: closed" from this ticket?

@mp911de
Copy link
Member

@mp911de mp911de commented Dec 30, 2020

That issue should be addressed since the last release. Does it still persist for you @Chealer?

@schauder schauder reopened this Jan 4, 2021
@schauder
Copy link
Contributor

@schauder schauder commented Jan 4, 2021

The subsection "Custom Namespace Attributes" still has issues, probably caused by a missing anchor.

Clicking on it in the TOC currently jumps to the beginning of the documentation. But I'm assuming this is more of a Spring Data JPA issue. I'll open a ticket there.

I also reopened the ticket here since @Chealer basically stated that it isn't fixed yet for him. Although we still need more information if more is broken than what I mentioned above.

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

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.