x/tools/cmd/present2md: conversion strips comments and .caption commands

[kortschak]

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

$ go version
go version go1.15.2 linux/amd64

Does this issue reproduce with the latest release?

Yes

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

go env Output

$ go env
GO111MODULE="on"
GOARCH="amd64"
GOBIN="/home/user/bin"
GOCACHE="/home/user/.cache/go-build"
GOENV="/home/user/.config/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="/home/user/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/user"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/home/user/go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/user/go/pkg/tool/linux_amd64"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/home/user/go/src/go.mod"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build264055988=/tmp/go-build -gno-record-gcc-switches"

present2md from golang/tools@96877f2

What did you do?

Invoke present2md on a file like so:

topic

Presenter McPresenterface

* Introduction

# Comment about this slide for internal use.

Content

.image https://blog.golang.org/lib/godoc/images/footer-gopher.jpg

.caption The gopher

What did you expect to see?

All the comments and .captions remaining.

# topic

Presenter McPresenterface

## Introduction

// Comment about this slide for internal use.

Content

.image https://blog.golang.org/lib/godoc/images/footer-gopher.jpg

.caption The gopher

What did you see instead?

Stripped like so:

# topic

Presenter McPresenterface

## Introduction

Content

.image https://blog.golang.org/lib/godoc/images/footer-gopher.jpg
The gopher

[gopherbot]

Change https://golang.org/cl/260897 mentions this issue: present: retain complete caption command when parsing captions

[kortschak]

The fix sent in CL260897 fixes the .caption command issue by correcting the parse behaviour, but I don't think that the loss of comment issue is trivially fixable; comments are discarded without consideration when parsed by x/tools/present. Keeping them would require an additional mode to retain them and is probably not worth doing. A possible work around is to preprocess the comments to // with something like sed (or internally in present2md).

[gopherbot]

Change https://golang.org/cl/260898 mentions this issue: cmd/present2md: allow comments to be retained in translated document

[dmitshur]

CC @rsc per owners.