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

Comments

Projects
None yet
5 participants
@biztos
Copy link

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 this to the Go1.9 milestone Dec 28, 2016

@dhananjay92

This comment has been minimized.

Copy link
Member

commented Dec 28, 2016

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">.

@dhananjay92 dhananjay92 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

@jayconrod jayconrod self-assigned this Feb 6, 2017

@gopherbot

This comment has been minimized.

Copy link

commented Feb 7, 2017

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.
You can’t perform that action at this time.