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

x/tools/godoc: non-go file HTML rendering adds a leading tab, which can become visible #29568

Closed
dmitshur opened this issue Jan 4, 2019 · 7 comments
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@dmitshur
Copy link
Contributor

dmitshur commented Jan 4, 2019

The CONTRIBUTORS file does not have any leading whitespace on its lines. However, when viewed at https://golang.org/CONTRIBUTORS, the generated HTML adds leading whitespace (a single tab character):

In most cases the tab character does not show visually up due to the way CSS is used to style content:

However, in some cases it becomes highly visible and distracting:

This does not affect the plain-text rendering mode of text files (e.g., https://golang.org/CONTRIBUTORS?m=text), only the HTML rendering.

@dmitshur dmitshur added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jan 4, 2019
@dmitshur dmitshur added this to the Unplanned milestone Jan 4, 2019
@dmitshur
Copy link
Contributor Author

dmitshur commented Jan 4, 2019

As noted by @bradfitz, this doesn't seem to affect rendered .go files. There is no leading tab character inserted in HTML on pages like https://golang.org/src/net/http/server.go:

It does affect other text files without an extension like https://golang.org/LICENSE, https://golang.org/AUTHORS, and files with non-go extension like https://golang.org/src/make.bash.

@dmitshur dmitshur changed the title x/website: plain text file rendering adds a leading tab, which can become visible x/website: non-go file HTML rendering adds a leading tab, which can become visible Jan 4, 2019
@agnivade
Copy link
Contributor

agnivade commented Feb 2, 2019

The leading tabs were always there.
fmt.Fprintf(w, "<span id=\"L%d\" class=\"ln\">%6d</span>\t", line, line)
Removing \t from there fixes it. But I am wondering the \t was there for a reason in the first place ?

The CSS change which caused this effect is golang/tools@4bc20fc#diff-62ab65160863cb8b1bd55a2653402fe4, which was made to fix another tab issue.

Specifically, if I disable these 2 properties from style.css .ln { class -

* Ensure 8 characters in the document - which due to floating
* point rendering issues, might have a width of less than 1 each - are 8
* characters wide, so a tab in the 9th position indents properly. See
* https://github.com/webcompat/web-bugs/issues/17530#issuecomment-402675091
* for more information. */
display: inline-block;
width: 8ch;

the leading space goes away, although the tab is still there in the html.

/cc @bradfitz @dmitshur @andybons @kevinburke for decision.

@dmitshur
Copy link
Contributor Author

dmitshur commented Feb 2, 2019

My guess is the tab was used for adding spacing. If no evidence otherwise can be found, I think we should remove it and implement spacing with a margin-right CSS property on ln class, if more spacing is needed.

@agnivade Where in the source code is that fmt.Fprintf call? Can you confirm that it’s only there when rendering non-.go files, but not when rendering .go ones, consistent with the behavior described in my comment above? It’d be great to learn why that difference exists, if possible.

Thank you for investigating this issue, it is helpful.

@agnivade
Copy link
Contributor

agnivade commented Feb 2, 2019

Where in the source code is that fmt.Fprintf call

godoc/format.go - FormatText()

Can you confirm that it’s only three when rendering non-.go files, but not when rendering .go ones, consistent with the behavior described in my comment above?

Correct. When rendering go files formatGoSource is called which does not have a trailing tab in its fmt.Fprintf call. See godoc/server.go formatGoSource()

Let me know if removing \t is the consensus. I can send a CL. I already have it ready.

@dmitshur
Copy link
Contributor Author

dmitshur commented Feb 2, 2019

Based on the history of events, I understand the tab character was used to ensure correct spacing. It's no longer needed and actively harmful after the change in golang/tools@4bc20fc. For that reason, and also because having it there makes copying the text harder (it includes a leading tab character not present in the source file), we should remove it.

When removing it, we just need to check that various non-.go files render okay and that it doesn't cause any spacing issues. If it does, we should address those with CSS instead of a tab character. But after the change golang/tools@4bc20fc, I expect spacing to work well in all cases. /cc @kevinburke and @mvdan, who worked on that CL.

Thanks @agnivade!

@dmitshur dmitshur added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Feb 2, 2019
@dmitshur dmitshur changed the title x/website: non-go file HTML rendering adds a leading tab, which can become visible x/tools/godoc: non-go file HTML rendering adds a leading tab, which can become visible Feb 2, 2019
@agnivade
Copy link
Contributor

agnivade commented Feb 2, 2019

Did some testing on several pages, with both Chrome and FF. Didn't see any issues. Will send the CL.

@gopherbot
Copy link

Change https://golang.org/cl/160917 mentions this issue: godoc: remove leading tabs while formatting text

@golang golang locked and limited conversation to collaborators Feb 5, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

3 participants