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/cmd/godoc: indentation stripped from raw string literals in example blocks #18446

Closed
biztos opened this issue Dec 28, 2016 · 2 comments
Closed
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@biztos
Copy link

biztos commented Dec 28, 2016

In code examples (e.g. foo_examples_test.go), leading whitespace is stripped from lines of a string declared with backticks, e.g.:

func Example() {
	foo := `One
    Two
Three`
	fmt.Println(foo)
	// Output:
	// One
	//     Two
	// Three
}

That will be rendered as follows by godoc:

<div class="expanded">
		<p class="exampleHeading toggleButton"><span class="text">Example</span></p>
		
		
		
			<p>Code:</p>
			<pre class="code">foo := `One
Two
Three`
fmt.Println(foo)
<span class="comment"></pre>
			
			<p>Output:</p>
			<pre class="output">One
    Two
Three
</pre>
			
		
	</div>
</div>

...ergo the code will appear without the crucial indentation in the string:

foo := `One
Two
Three`
fmt.Println(foo)

This bug is present in godoc and also at godoc.org despite the latter rendering code blocks quite differently.

Answers to the questions:

What version of Go are you using (go version)?

go version go1.7 darwin/amd64

What operating system and processor architecture are you using (go env)?

GOARCH="amd64"
GOBIN=""
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/frost/go"
GORACE=""
GOROOT="/usr/local/go"
GOTOOLDIR="/usr/local/go/pkg/tool/darwin_amd64"
CC="clang"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/vd/dv4ywnzd0gq3gsv6_sfq9nv80000gn/T/go-build153742415=/tmp/go-build -gno-record-gcc-switches -fno-common"
CXX="clang++"
CGO_ENABLED="1"

What did you do?

Used a multi-line string declared with backticks in a code example for my
project frostedmd.

The string has meaningful indentation describing a code block in Markdown,
and the bug (or an identical bug) can be seen in action on Godog.org here:

https://godoc.org/github.com/biztos/frostedmd#ex-package

What did you expect to see?

The string correctly indented in the code block of the example documentation.

What did you see instead?

The string with leading whitespace stripped from indented lines, thus making
the example invalid.

@griesemer griesemer added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Dec 28, 2016
@griesemer griesemer added this to the Go1.9 milestone Dec 28, 2016
@JayNakrani
Copy link
Contributor

Looks like, it's because example_htmlFunc() and example_textFunc() try to unident function block by replacing "\n<4 spaces>" with "\n". That replacement ends up removing indentation from backticked-string too.

Value of code, before:

{
    foo := `One
        Two
    Three
Four`
    fmt.Println(foo)
    <span class="comment">// Output:</span>
    <span class="comment">// One</span>
    <span class="comment">//     Two</span>
    <span class="comment">// Three</span>
}

and after:

foo := `One
    Two
Three
Four`
fmt.Println(foo)
<span class="comment">

Also there's a side issue that it retains the last <span class="comment">.

@JayNakrani JayNakrani changed the title Indentation stripped from strings in example code blocks. x/tools/cmd/godoc: indentation stripped from raw string literals in example blocks Jan 10, 2017
@JayNakrani JayNakrani 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 Jan 10, 2017
@jayconrod jayconrod self-assigned this Feb 6, 2017
@gopherbot
Copy link

CL https://golang.org/cl/36544 mentions this issue.

@golang golang locked and limited conversation to collaborators Feb 17, 2018
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

5 participants