|
== Archives ==
[[/Archive 1]]
== Quick poll on typographic conventions ==
Past debate has occurred on the best typographic conventions to use in this article. In a nutshell, documentation produced by Eiffel Software and other parties documenting Eiffel generally uses a set of conventions for color (mostly blue), boldface, and italics in the visual presentation of code samples. In contrast, Wikipedia conventions (as indicated by most programming-related articles) use a simple <nowiki><code></nowiki> font for inline code, and a MediaWiki "literal" block (indented text; currently rendered with <nowiki><pre></nowiki>) for code blocks.
How should this article handle typographic markup of source code examples. Please comment with your opinion, and the reasons for it.
=== Code Blocks ===
==== Eiffel color/font in code blocks ====
*I definitely think that we should use the colour guidelines as laid out by the standard, especially in the code boxes. These are not as jarring as the inline code samples, and if you're going to edit the code blocks, you should know what you're doing anyway. Wikipedia is for the reader first, the editor second. It's better for it to be accurate than for a less accurate easy-edit version. For me, this stems down to [[Meta:Wiki is not paper]], Wikipedia is not bound by the costs of colour ink, colour is trivial, Wikipedia should take advantage of this fact. - [[User:Hahnchen|Hahnch]][[Evil|<span title="WP:Esperanza"><font color="green">e</font></span>]][[User:Hahnchen|n]] 03:13, 7 September 2006 (UTC)
*I think Eiffel code must be made to look like Eiffel code looks. Otherwise the article trivializes it to just another code syntax and misses a key point of its purpose and design. Make it blue, etc. [[User:Dicklyon|Dicklyon]] 05:43, 7 September 2006 (UTC)
*I tend to prefer this option, this way the article is more illustrative --'''[[User:it.wiki:Twilight|<font color="red">Twi</font>]][[User_talk:It.wiki:Twilight|light]]''' 03:38, 8 September 2006 (UTC)
*Me too. There are the following precedents on Wikipedia for using each language's preferred convention (although not with color): [[Algol 60]], [[Simula]], [[Algol W]], [[Pascal (programming language)]]. Anyone know of others? [[User:Fuchsias|Fuchsias]] 03:38, 9 September 2006 (UTC)
* if there is a standard resp. recommendation, i'd rather go with the standard. --[[User:ThurnerRupert|ThurnerRupert]] 21:18, 24 September 2006 (UTC)
*This should satisfy all parties, and was my original suggestion at the beginning of the entire debacle. On the one hand it allows the example code the appearance of "normal" Eiffel code, on the other hand it will not mar the discussion. Of specific significance is that blue text in the body text is confusing in a hypertext context because it is easily mistaken for hyperlinks, even if in code-tags (f.i. this occurs in several C++ articles: <code>#include <[[iostream]]></code>). Also, it is bad pedagogics because it throws of normal text flow. There are very simple reasons that text books not to laborate with colours in mid-text. [[User:Mikademus|Mikademus]] 06:54, 7 September 2006 (UTC)
*Best way would be to apply the "Eiffel style in code blocks, Wikipedia style in blocks" scenario, as it leaves the Wikipedia text unformatted. Code blocks are OK on Eiffel style. [[User:Jossi|≈ jossi ≈]] <small>[[User_talk:Jossi|t]] • [[Special:Emailuser/Jossi|@]]</small> 19:45, 7 September 2006 (UTC)
*I have not done lots of editing on wikipedia yet, but I am familiar with software engineering (including Eiffel) and typography. As a user I was puzzled with the inline blue fonts (I expect links to be blue). I hear that one of the reasons why Lulu wanted all the standard typographic editing was to make it easier to edit for beginners, right? Looking at the source, I do not understand, why using the font tag with the color argument also alters the face to italic when using uppercase only. Personnally, I find it best to read if the words appear in Eiffel style (except for the color) inline, while code snippets are completely in Eiffel style --[[User:Masche|Masche]] 08:11, 11 September 2006 (UTC)
==== Eiffel style (no color) in code blocks ====
*I agree with Lambiam. While it would be good, in principle, to use Eiffel style conventions wherever possible, I agree that the blue text colour, particularly in inline text, can be confused too easily with Wikilinks. That, however, only represents an argument against the use of blue text. My understanding is that if colour is unavailable as an option, then it is reasonable to default to black text according to the standard. Given the potential confusion of blue text, perhaps it is best to assume colour is, essentially, unavailable, and default back to black text with all the other style conventions remaining. As Lambian said, this deals with most of the objections of both sides. I would also point out that this is hardly jarring given that it would be similar to pseudocode according to Wikipedia style guidelines in [[Wikipedia:Algorithms_on_Wikipedia]]. [[User:Leland McInnes|Leland McInnes]] 18:55, 8 September 2006 (UTC)
==== Wikipedia (partially implicit) style guidelines in code blocks ====
* Beyond the general jarringness of encountering a non-standard convention in one particular programming language article, I found additional difficulties when I began to edit code blocks marked in the "Eiffel style". A lot of extra markup goes into those conventions, making code samples extremely fragile for editors to modify without disturbing markup features (often in ways that produce dramatically bad results). Non-editing readers will not see this issue, but allowing easy collaboration (rather than implied "invariant" sections) is an important principle of Wikipedia. [[User:Lulu of the Lotus-Eaters|<span style="color:darkgreen;">LotLE</span>]]×[[User talk:Lulu of the Lotus-Eaters|<span style="color:darkred;font-size:x-small;">talk</span>]] 03:01, 7 September 2006 (UTC)
* Besides the reasons above there is no official standard for the font. Yes, the ECMA standard does recommend the typographic conventions discussed but it is not an official enforced standard. If an implementation's IDE would not be considered compliant because they changed the color of the text then it would be a standard. There are unofficial standards for many languages. Should the Java article (and all articles that feature Java code) be rewritten using the same font as Sun's documents? Likewise, should all the C code (and there's tons of it) be rewritten using the "One True Brace Style" (which has been recommended by standards groups just like Eiffel's conventions)? I don't think anyone would seriously advocate any of the previous notions, hence, I believe that enforcing the stylistic recommendations over the current Wikipedia de facto standard is inappropriate in this case. - [[User:DNewhall|DNewhall]] 05:59, 7 September 2006 (UTC)
==== What value does the blue color add? ====
* Like every other programmer I understand the value of syntax highlighting - keywords in one color, variables in another, separators in third... That's really useful. But highlighting all the code with just one color doesn't make sense to me. It's just as good as not highlighting it at all. The black-text codeblocks stand out just fine, there's no need to add extra emphasis with bright blue color. If I look at the page, the codeblocks are like screaming: "Look at me! I'm codeblock!". Marking the keywords in boldface is fine, but the blue color has absolutely no meaning. Admit it. [[User:Renku|Nene]] 13:07, 1 December 2006 (UTC)
::The principe of using blue typeface for code is that all code, including inline code referring to variables in the previous codeblock, or keywords, or feature calls etc. can then be easily distinguished as code. Note that the emphasis here is on '''inline''' code being easily distinguishable from text. Because of the poor quality compromise that this article has taken the end result is moot. Code blocks being blue serves little purpose if inline code is left alone. Consistency of style differentiating it from text is the aim. I agree that it is not served here. I suggest using black text evrywhere and reserving bold and italic text for code to help distinguish it. [[User:Leland McInnes|Leland McInnes]] 18:12, 1 December 2006 (UTC)
=== Inline Code ===
==== Eiffel style with color in inline code ====
*I definitely think that we should use the colour guidelines as laid out by the standard, especially in the code boxes. These are not as jarring as the inline code samples, and if you're going to edit the code blocks, you should know what you're doing anyway. Wikipedia is for the reader first, the editor second. It's better for it to be accurate than for a less accurate easy-edit version. For me, this stems down to [[Meta:Wiki is not paper]], Wikipedia is not bound by the costs of colour ink, colour is trivial, Wikipedia should take advantage of this fact. - [[User:Hahnchen|Hahnch]][[Evil|<span title="WP:Esperanza"><font color="green">e</font></span>]][[User:Hahnchen|n]] 03:13, 7 September 2006 (UTC)
*I think Eiffel code must be made to look like Eiffel code looks. Otherwise the article trivializes it to just another code syntax and misses a key point of its purpose and design. Make it blue, etc. [[User:Dicklyon|Dicklyon]] 05:43, 7 September 2006 (UTC)
*I tend to prefer this option, this way the article is more illustrative --'''[[User:it.wiki:Twilight|<font color="red">Twi</font>]][[User_talk:It.wiki:Twilight|light]]''' 03:38, 8 September 2006 (UTC)
*Me too. There are the following precedents on Wikipedia for using each language's preferred convention (although not with color): [[Algol 60]], [[Simula]], [[Algol W]], [[Pascal (programming language)]]. Anyone know of others? [[User:Fuchsias|Fuchsias]] 03:38, 9 September 2006 (UTC)
* if there is a standard resp. recommendation, i'd rather go with the standard. --[[User:ThurnerRupert|ThurnerRupert]] 21:18, 24 September 2006 (UTC)
==== Eiffel style about bold/italics, but no color in inline code ====
*Use the Eiffel conventions for inline code ''except for the colour''. Example: "In the below code block, the <code>'''class'''</code> called <code>''HELLO_WORLD''</code> has a feature called <code>''make''</code>, which is usually used as an entry-point for the class." I think this is better than "Eiffel style in code blocks, Wikipedia style in paragraph text" and takes away most of the objections against both "Wikipedia style everywhere" and "Eiffel style everywhere". --[[User:Lambiam|Lambiam]][[User talk:Lambiam|<small><sup>Talk</sup></small>]] 06:00, 8 September 2006 (UTC)
*I agree with Lambiam. While it would be good, in principle, to use Eiffel style conventions wherever possible, I agree that the blue text colour, particularly in inline text, can be confused too easily with Wikilinks. That, however, only represents an argument against the use of blue text. My understanding is that if colour is unavailable as an option, then it is reasonable to default to black text according to the standard. Given the potential confusion of blue text, perhaps it is best to assume colour is, essentially, unavailable, and default back to black text with all the other style conventions remaining. As Lambian said, this deals with most of the objections of both sides. I would also point out that this is hardly jarring given that it would be similar to pseudocode according to Wikipedia style guidelines in [[Wikipedia:Algorithms_on_Wikipedia]]. [[User:Leland McInnes|Leland McInnes]] 18:55, 8 September 2006 (UTC)
* I would be more than happy to use this convention, if it is general consensus. Color is the part I find the most jarring, italics and boldface are farily neutral (this is enforced by the fact that ital/bold have built-in wiki markup, where color needs to drop to HTML). It still makes modifying examples slightly harder, but not too badly. [[User:Lulu of the Lotus-Eaters|<span style="color:darkgreen;">LotLE</span>]]×[[User talk:Lulu of the Lotus-Eaters|<span style="color:darkred;font-size:x-small;">talk</span>]] 19:45, 8 September 2006 (UTC)
*I have not done lots of editing on wikipedia yet, but I am familiar with software engineering (including Eiffel) and typography. As a user I was puzzled with the inline blue fonts (I expect links to be blue). I hear that one of the reasons why Lulu wanted all the standard typographic editing was to make it easier to edit for beginners, right? Looking at the source, I do not understand, why using the font tag with the color argument also alters the face to italic when using uppercase only. Personnally, I find it best to read if the words appear in Eiffel style (except for the color) inline, while code snippets are completely in Eiffel style --[[User:Masche|Masche]] 08:11, 11 September 2006 (UTC)
* —''[[User:R._Koot|Ruud]]'' 13:06, 16 September 2006 (UTC)
==== Use generic fixed-font for inline code ====
*This should satisfy all parties, and was my original suggestion at the beginning of the entire debacle. On the one hand it allows the example code the appearance of "normal" Eiffel code, on the other hand it will not mar the discussion. Of specific significance is that blue text in the body text is confusing in a hypertext context because it is easily mistaken for hyperlinks, even if in code-tags (f.i. this occurs in several C++ articles: <code>#include <[[iostream]]></code>). Also, it is bad pedagogics because it throws of normal text flow. There are very simple reasons that text books not to laborate with colours in mid-text. [[User:Mikademus|Mikademus]] 06:54, 7 September 2006 (UTC)
*Best way would be to apply the "Eiffel style in code blocks, Wikipedia style in blocks" scenario, as it leaves the Wikipedia text unformatted. Code blocks are OK on Eiffel style. [[User:Jossi|≈ jossi ≈]] <small>[[User_talk:Jossi|t]] • [[Special:Emailuser/Jossi|@]]</small> 19:45, 7 September 2006 (UTC)
* Beyond the general jarringness of encountering a non-standard convention in one particular programming language article, I found additional difficulties when I began to edit code blocks marked in the "Eiffel style". A lot of extra markup goes into those conventions, making code samples extremely fragile for editors to modify without disturbing markup features (often in ways that produce dramatically bad results). Non-editing readers will not see this issue, but allowing easy collaboration (rather than implied "invariant" sections) is an important principle of Wikipedia. [[User:Lulu of the Lotus-Eaters|<span style="color:darkgreen;">LotLE</span>]]×[[User talk:Lulu of the Lotus-Eaters|<span style="color:darkred;font-size:x-small;">talk</span>]] 03:01, 7 September 2006 (UTC)
* Besides the reasons above there is no official standard for the font. Yes, the ECMA standard does recommend the typographic conventions discussed but it is not an official enforced standard. If an implementation's IDE would not be considered compliant because they changed the color of the text then it would be a standard. There are unofficial standards for many languages. Should the Java article (and all articles that feature Java code) be rewritten using the same font as Sun's documents? Likewise, should all the C code (and there's tons of it) be rewritten using the "One True Brace Style" (which has been recommended by standards groups just like Eiffel's conventions)? I don't think anyone would seriously advocate any of the previous notions, hence, I believe that enforcing the stylistic recommendations over the current Wikipedia de facto standard is inappropriate in this case. - [[User:DNewhall|DNewhall]] 05:59, 7 September 2006 (UTC)
*I would be fine with this too. - [[User:Hahnchen|Hahnch]][[Evil|<span title="WP:Esperanza"><font color="green">e</font></span>]][[User:Hahnchen|n]] 03:13, 7 September 2006 (UTC)
* I'd be fine with this. I use emacs when writing Eiffel programs. Having code in blue makes it difficult to make a complete article in Wikipedia style. I think the main article should be shorter and details moved to subtopics, which could be expanded. [[User:Epiteo|Epiteo]] 03:51, 29 October 2006 (UTC)
=== Examples ===
To illustrate the proposed stylistic conventions, each is presented below.
'''Wikipedia style everywhere:''' In the below code block, the <code>class</code> called <code>HELLO_WORLD</code> has a feature called <code>make</code>, which is usually used as an entry-point for the class:
class
HELLO_WORLD
create
make
feature
make
do
io.put_string ("Hello, world!")
io.put_new_line
end
end
'''Eiffel style in code blocks, Wikipedia style in paragraph text:''' In the below code block, the <code>class</code> called <code>HELLO_WORLD</code> has a feature called <code>make</code>, which is usually used as an entry-point for the class:
<font color=blue>'''class'''
''HELLO_WORLD''
'''create'''
''make''
'''feature'''
''make''
'''do'''
''io.put_string'' ("Hello, world!")
''io.put_new_line''
'''end'''
'''end'''</font>
'''Eiffel style everywhere:''' In the below code block, the <code><font color=blue>'''class'''</font></code> called <code><font color=blue>''HELLO_WORLD''</font></code> has a feature called <code><font color=blue>''make''</font></code>, which is usually used as an entry-point for the class:
<font color=blue>'''class'''
''HELLO_WORLD''
'''create'''
''make''
'''feature'''
''make''
'''do'''
''io.put_string'' ("Hello, world!")
''io.put_new_line''
'''end'''
'''end'''</font>
'''Eiffel style everywhere, less colour''': In the below code block, the <code>'''class'''</code> called <code>''HELLO_WORLD''</code> has a feature called <code>''make''</code>, which is usually used as an entry-point for the class:
'''class'''
''HELLO_WORLD''
'''create'''
''make''
'''feature'''
''make''
'''do'''
''io.put_string'' ("Hello, world!")
''io.put_new_line''
'''end'''
'''end'''
'''Eiffel style everywhere, colour in code blocks only ''': In the below code block, the <code>'''class'''</code> called <code>''HELLO_WORLD''</code> has a feature called <code>''make''</code>, which is usually used as an entry-point for the class:
<font color=blue>'''class'''
''HELLO_WORLD''
'''create'''
''make''
'''feature'''
''make''
'''do'''
''io.put_string'' ("Hello, world!")
''io.put_new_line''
'''end'''
'''end'''</font>
:guys: I can't follow the long baroque discussion about formatting.
: is this what your are looking for? :
:<syntaxhighlight lang="eiffel" style="color:blue;font-style:italic">
class
HELLO_WORLD
create
make
feature
make
do
io.put_string ("Hello, world!")
io.put_new_line
end
end
</syntaxhighlight>
:the source/syntaxhighlight label has many parameters, just decide which ones to use and be consistent in their use. Please do not format directly the program text, otherwise it would be useless for copying and pasting to try it with an Eiffel compiler.
=== Discussion ===
An additional problem, to my mind, with using syntax highlighted code (even in code blocks) is that it tends to mislead readers who may be unclear at first exactly where the highlighting comes from, and whether it is required to make code compile/execute. I.e. do I ''need'' to use a custom IDE to manually mark keywords as such, in order to create or run Eiffel code? In my personal world, the most common way I look at code is something like:
% cat hello.e
class
HELLO_WORLD
create
make
feature
make is
do
io.put_string ("Hello, world!")
io.put_new_line
end
end
I never see any special highlights or non-standard console color, even when I look at completely compilable source code files. Now obviously, if I were to use specific IDEs or programming editors, I might see the "Eiffel style" markup features (or I might see other ones, depending on what syntax highlighting features I chose). Picking something non-generic and IDE-specific draws readers into thinking a non-essential feature is an actual part of the language syntax (albeit a moderate amount of potential confusion). [[User:Lulu of the Lotus-Eaters|<span style="color:darkgreen;">LotLE</span>]]×[[User talk:Lulu of the Lotus-Eaters|<span style="color:darkred;font-size:x-small;">talk</span>]] 19:56, 7 September 2006 (UTC)
:To carry the example of the confused reader "I.e. do I ''need'' to use a custom IDE to manually mark keywords as such, in order to create or run Eiffel code?" to its logical conclusion, we should probably remove the indentation so that the mentioned reader does not wonder "Do I need to indent manually indent blocks of code in order to create or run Eiffel code?"
something like:
class
HELLO_WORLD
create
make
feature
make is
do
io.put_string ("Hello, world!")
io.put_new_line
end
end
or
class HELLO_WORLD create make feature make is do io.put_string ("Hello, world!") io.put_new_line end end
[[User:75.30.203.153|75.30.203.153]] 06:57, 9 September 2006 (UTC)
::Agreed - it's unreasonable to try to cater for, to me, a misunderstanding so silly as to be only an academic exercise. Removing colour from the code purely to avoid the case where a user assumes the colouring is somehow part of the syntax is akin to handing out rubber knives and forks at a restaurant to stop people accidentally stabbing themselves.
[[User:Destynova|Destynova]] 01:24, 3 November 2007 (UTC)
== [[WP:AUTO]] ==
| 