search

golang / go

The Go programming language
https://go.dev
BSD 3-Clause "New" or "Revised" License
122.72k stars 17.5k forks source link

x/tools/cmd/godoc: specifying a file's language #6893

Open siritinga opened 10 years ago

siritinga commented 10 years ago 
Go source files are UTF-8 so there is, in principle, no need to specify its encoding or
language. However, I think there is one case when it would be very convenient to specify
in which language are the comments written.

When using CJK (Chinese, Japanese and Korean), there are different variations of some
ideograms that are written with different glyphs (sometimes differences are minor,
sometimes not so minor). However, in Unicode, some of these varied glyphs share the same
codepoint, so it is not possible to choose the right glyph if the language is unknown.
This is called the Han Unification: https://en.wikipedia.org/wiki/Han_unification

HTML code can include the <lang> label to inform the browser which font should it
use to render a text. If it is not included, the browser usually will use a default
font. For example, Google Chrome on a non-CJK system will usually choose a Chinese font,
and Japanese ideograms will be rendered with Chinese glyphs.

So my suggestion would be to include some kind of label for godoc to include the right
<lang> label in the HTML generated, so it will be rendered correctly in most
systems. 

Ideally, it should be possible to modify it inside a file, so you could write Chinese
and Japanese in the same file.

What do you think?
adg commented 10 years ago

Comment 1:

One possibility is to add some kind of magic comment:
// +language foo
But it would be non-trivial to implement this.
Got an example of this causing a real problem?

Status changed to Thinking.

ianlancetaylor commented 10 years ago

Comment 3:

Side note: I think we probably eventually want a general scheme for comments that affect
godoc, so that a package can present itself in an order that makes more sense.
minux commented 10 years ago

Comment 4:

Labels changed: added repo-tools.

siritinga commented 10 years ago

Comment 5:

I've searched in godoc for repositories with Japanese documentation for a real case. For
example http://godoc.org/github.com/yokano/escape3ds/server/view contains Japanese
comments that are rendered in Chinese in my computer. There is no <lang> label so
it is up to the browser. Honestly, with my limited Japanese I only found one ideogram
rendered incorrectly in that package (終), but the issue is present.
rsc commented 10 years ago

Comment 6:

Labels changed: added release-none.