Unicode em- and en-dashes in godocs?

[Matthew Dempsky]

I noticed a handful of hyphens and double-hyphens in godocs where typical English style guides would advise using em- or en-dashes instead.  Is it worth changing them to use Unicode dashes, or is that just make-work?

There's precedent for using Unicode dashes in internal comments and the HTML documentation, and for using other Unicode characters in godocs as appropriate.

debug/elf:

        SHN_XINDEX    SectionIndex = 0xffff /* Escape -- index stored elsewhere. */

mime/multipart:

        contain certain ASCII characters, and must be 1-69 bytes long.

net:

        the mask is not in the canonical form--ones followed by zeros--then Size

net/http:

        Write writes an HTTP/1.1 request -- header and body -- in wire format.

text/template:

        "Actions"--data evaluations or control structures--are delimited by "{{"

[Aram Hăvărneanu]

Apologies, but I don't understand your proposal/question. To me, it
can be about one of these three things:

1) changing the comments
2) making godoc synthesise unicode dashes in the browser
3) making godoc (or go doc?) synthesise unicode dashes in the terminal

--
Aram Hăvărneanu

[Matthew Dempsky]

Changing the source comments to use "—" or "–" as stylistically appropriate instead of "--" or "-".  E.g., changing src/text/template/doc.go:19 to:

        "Actions"—data evaluations or control structures—are delimited by "{{"

[Nigel Tao]

On Fri, Jul 24, 2015 at 4:07 PM, 'Matthew Dempsky' via golang-dev
<golan...@googlegroups.com> wrote:
> I noticed a handful of hyphens and double-hyphens in godocs where typical
> English style guides would advise using em- or en-dashes instead. Is it
> worth changing them to use Unicode dashes, or is that just make-work?

I feel like it's make-work, but will defer to r for any documentation
bikeshedding.

[Rob Pike]

If you want to do the work, I will review the results. If you don't
want to do the work, I won't bother.

-rob

[Matthew Dempsky]

My take away from golang.org/cl/12683: em- and en-dash, while technically correct, are not the best kind of correct, because they make fixed-width presentations harder to read.  Instead, continue to use double hyphens without spaces in lieu of em-dashes, but favor simpler syntax where possible.

[Russ Cox]

On Mon, Jul 27, 2015 at 10:51 PM, 'Matthew Dempsky' via golang-dev <golan...@googlegroups.com> wrote:

My take away from golang.org/cl/12683: em- and en-dash, while technically correct, are not the best kind of correct, because they make fixed-width presentations harder to read.  Instead, continue to use double hyphens without spaces in lieu of em-dashes, but favor simpler syntax where possible.

I'm sorry, but I disagree. It is perfectly fine to use em dashes, and they are preferable to typing "--", which smacks of ASCII art. There are already em dashes in the docs for the standard library. Please do not take them out.

Russ

[Matthew Dempsky]

I have to defer to Rob.  My "take away" was not meant to advocate a solution, but instead as a summary of how I plan to write standard library documentation in the future based on his code review feedback.

I primarily read Go documentation in a variable-width font, so my personal preference would still be to use em and en dashes instead of "--".  But I do agree with Rob that fixed-width presentations (particularly Gerrit) make them difficult to distinguish from hyphens.

Lastly, for what it's worth, golang.org/cl/12683 did not remove any em dashes.  It only replaced hyphens and double hyphens.

[Rob Pike]

In Gerrit, the em dashes were indistinguishable from dashes, which led
to significant ambiguity.

-rob