Skip to content

x/tools/cmd/godoc: indentation stripped from raw string literals in example blocks #18446

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

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
Contributor

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

@golang golang locked and limited conversation to collaborators Feb 17, 2018
henderjon pushed a commit to oggodoc/godoc that referenced this issue Jun 13, 2024
godoc formats function examples for text or HTML output by
stripping the surrounding braces and un-indenting by replacing
"\n    " with "\n". This modifies the content of string literals,
resulting in misleading examples.

This change introduces a function, replaceLeadingIndentation, which
unindents more carefully. It removes the first level of indentation
only outside of string literals. For plain text output, it adds custom
indentation at the beginning of every line including string literals.

Fixes golang/go#18446

Change-Id: I52a7f5756bdb69c8a66f031452dd35eab947ec1f
Reviewed-on: https://go-review.googlesource.com/36544
Run-TryBot: Jay Conrod <jayconrod@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Alan Donovan <adonovan@google.com>
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