RLE: Tcl user and one of the [wikignomes]. Created pages: * [Hyperlink widget] ---- [LkpPo] - Hi RLE, I see that you care for actively improving the wiki like me. Do you know who I can contact to report a bug in the search engine? The bugtracker is hosted on Google and I do not like the idea of having to create an account with Google! Thanks. ---- Hi LkpPo - [RLE] here, I just noticed your edit to my page. If you look at the bottom of the [About the WIki] page, it implies that [Colin McCormack] might be a contact that you are looking for regarding bug reporting. ---- [LkpPo] - Hi RLE, I'll contact him. Thank you for your help. ---- [PYK] - Hi RLE, I'm looking for a way to link to the page http::geturl Any suggestions? [RLE] (2013-04-01): Try this way: [http://wiki.tcl.tk/24061%|%http::geturl %|%] Edit page to see. The problem you are encountering is that raw colon characters are not allowed in a URL ([http://www.rfc-editor.org/rfc/rfc1738.txt%|%rfc1738.txt %|%]). Linking to the page by wiki number gets around that limitation, and then using the wiki "rename url" syntax, you can make the link look like '''http::geturl'''. [PYK] 2013-04-01: Thanks. The problem with that, though, is that the "what links here" mechanism doesn't pick up on those links. Even if URL syntax doesn't support colons, wiki syntax still could (and should) recognize such links. I've filed [http://code.google.com/p/wikitcl/issues/detail?id=289%|%this bug] regarding the issue. [PYK] 2013-12-13: Hi RLE, on the [[`[return]`] page, you removed the brackets around the inline Tcl code examples. Isn't it standard style to put brackets around inline code examples? If you look at [AMG]'s comments on that same page, for example, they had brackets around the code examples prior to my edit. I'm somewhat on the fence about what the standard style should be, but whatever it is hopefully it can be applied consistently throughout the wiki. Maybe it's time to initiate a [Tcl Wiki Style Guide]. [AMG]: Hate to say it, but you did it again with the missing close bracket. You have: ====== [[`[return]`] ====== Which should be: ====== [[`[return]`]] ====== This will trip up the wiki markup parser if there is a mismatched open bracket nearby, plus it's very confusing and asymmetrical. [PYK]: [AMG], are you sure it will trip up the markup parser? I've never seen it do so. Rather, I interpret the double left bracket as the way to escape the bracket, but the closing bracket doesn't need to be escaped. I tend to be minimalist about syntax, so why escape the closing bracket if it isn't necessary? [AMG]: I did a test on [Graffiti] a few minutes ago, and indeed it matched a single open bracket from earlier in the line with the single closing bracket you didn't think needed to be escaped. There's a difference between being minimalist and taking shortcuts. The wiki markup translation code emits a single close bracket ''as a failsafe'' when given a single close bracket on input with no matching single open bracket, but it's still an error condition it's trying to handle gracefully. If you want to be minimalist, simply don't use the extra markup features in the first place. You're combining three markup features in a way that's easy to be confused about. Just pick your favorite and go with it, no need to toss in the kitchen sink too. The trouble with adding features to any language, markup languages included, is that folks then feel obligated to use them, even if they got along without for many years. Witness [C++]... [PYK]: But that's a different situation because it was already in a "link" context, so not relevant to the comments above :P I'm not sure there is any way to escape a closing bracket in a link context. I doubt the implementation is as you say, because it would be more straightforward for it to simply interpret `[[[[` as a single open bracket. Witness the fact that a single ] anywhere in a page is not treated specially. It's the opening bracket that moves the implementation into a different state. However, this is where [Tcl Wiki Style Guide] would come in handy, because we could just specify "don't do that" in the guide. [PYK] 2013-12-13: The problem with using italics instead of brackets is that italics are already used to denote placeholder values that should be changed by the user to the appropriate value for a particular scenario. [RLE]: [PYK] I never even noticed that the original brackets were there. After you added the bracket overload edits I just assumed that all of the brackets were the result of your edits and set about undoing the resultant mess. I find it interesting that 6 paragraphs up you state: : "I tend to be minimalist about syntax, ..." Yet, [[having]] square [[brackets]] around [[every]] possible [[word]] that [[happens]] to be a [[tcl]] [[keyword]] hardly seems [[very]] "[[minimalist]] [[about]] [[syntax]]". In fact, it gives the pages to which you've made this change a look reminiscent of 1930's ransom letters where each letter/word was cut from a separate newspaper advertisement, and so the result was a hodgepodge of random fonts, sizes, etc. English prose does not normally contain loads of square brackets within its sentences. In fact, they usually denote a [http://www.thefreedictionary.com/parenthetical%|%parenthetical] phrase, i.e. "a construction that can be used to extend the meaning of a word or phrase but is not one of the main constituents of a sentence". Which makes reading English prose loaded with lots of brackets a significantly different, more painful, experience. The words in prose that are [Tcl] keywords, that are also being used in the context of their [Tcl] meaning, should simply be links. Reading the prose with embedded links is significantly less jarring than [[reading]] the [[prose]] with lots [[of]] extra [[brackets]] [[throughout]]. Which is why I set upon removing the brackets. As for [AMG]'s originals, I do see some slight use where a Tcl command plus arguments might be inlined within the prose itself. But to [[bracket]] [[every]] [[instance]] of [[any]] use of [[Tcl]] [[keywords]] is simply overkill. I.e., brackets, within prose, is a feature/style best used judiciously and with significant restraint. Because do to otherwise risks making the actual prose significantly more difficult to read. : "The problem with using italics instead of brackets is that italics are already used to denote placeholder values that should be changed by the user to the appropriate value for a particular scenario." Given that you indicate that there is no "Tcl Wiki Style Guide" yet, where is this rule written down? Italics, like boldface and fixed width font, are styles of emphasis. More often than not, the meaning of any particular emphasis is conveyed by the surrounding context, and/or through that which is emphasized. I.e., this: binary format H* input_string_here indicates the "placeholder" via the name used. Adding italics to "input_string_here" simply makes it stand out more, but the above is not any less indicative of a placeholder by lacking italicized text. [PYK] 2013-12-13: Actually, the only place italics have the meaning I described is in the command synopsis on the official reference pages, which have a style separate from the wiki. The wiki does tend to mirror that usage, at least for command synopsis. But the vast majority of wiki pages use [[command ...] notation, whereas the only place I have seen the ''italics'' command style is in the pages you've edited in the last couple of days. The ''italics'' style isn't too bad, but there are years of [[commmand ...] usage throughout the wiki. Is it really a good idea to switch at this point? I can see the point about foregoing the brackets when a command is used not as a code example but simply in reference to the concept. If you're really intent on switching all inline code examples to italics, I suggest doing a couple of pages in that style (''[eval]'' ,''[namespace eval]'' ,''[return]''), and giving other people a chance to react to it. [RLE] 2013-12-13: Actually, I'm not interested in that style. I just did it initially on those pages as a way to test a middle ground between delineating everything with square brackets (which rapidly becomes overwhelming) and delineating nothing (which makes picking finding the end of the inline snippets harder). '''Judicious''' use of square brackets to set out the inline prose command snippets actually looks better in my opinion. However there is a rather fine, narrow, line between judicious and overuse there so care is necessary. [PYK] 2013-12-14: I'm experimenting with another style on the `[return]` page: inlined code marked up with only ``, and all commands marked up as inlined code. Markup such as '''bold''' and ''Italics'' is still used in inlined-code context for their respective purposes. Inlined code definitely looks better without the brackets, and in many contexts knowing that an individual word is also a command is useful. For example, the extra information means that one can write "`[return]`" instead of "the [return] command". In some places, like the list of commands under "See Also", the extra information isn't so useful, but I think it would be good on this point to be consistent throughout, because it give the page a uniform feel. Otherwise, you end up with sentences where some command names being marked up as inlined code, and some not. Consider this line from `[return]`: [Funky Tcl extensibility]: tricks to play with `return -code return` and `[error]` on `return -code error` Which I think looks better than [Funky Tcl extensibility]: tricks to play with `return -code return` and [error] on `return -code error` [RLE] 2013-12-13: The mono-spaced font is significantly better visually than an overload of square brackets. I however have no difficulty with interpreting the single word "error" in the non-formatted version as a "link" to a page named error, as well as recognizing it as a reference to the Tcl command named [error]. Given that links already get differing visual treatment by browsers (even by text based browsers) I would submit that even someone who knows nothing about Tcl would recognize the word "error" as a link, and if they were curious why it was a link, would click it and then learn it had a "special" Tcl meaning. Even without having to make it mono-spaced at the same time. With that said, the mono-spaced version removes the visual clutter resulting from the excessive square bracket version, so it is fine as a formatting style. ---- [PYK] 2014-02-03: Hi [RLE], it looks like its time to settle the question of where '''See Also''' belongs on a Wiki page. My rationale for putting it near the top is that the primary Wiki activity is browsing, and '''See Also''' is indispensable for that. When one is searching for information in a browsing mode, It can be annoying to scroll to the bottom of each page to try to find the '''See Also''' section. Conversely, once one finally gets to the desired page, and the activity shifts from browsing to reading, it's only a little overhead to scroll down past "See Also", which in any case, is usually of some interest as well. [RLE]: But even in "browsing mode", you are looking for a page on topic X. So you search a topic, look at the hits, and click a link because the link looks interesting for your topic of interest. The same applies while jumping off another page, the link looks interesting, so you click the link to go to the page. Now, once there, even though you are still "browsing", in order to know if where you've landed is what you are looking for, you have to read what the page is about. Putting the "see also" section at the top interrupts determining what the page is about. Once you know what the page is about, then you know if you've found your topic, or if more research (browsing) is warranted. At which point you should naturally be near the end of the page. So then you checkout the "see also" section (at the end) for other related possibilities. Or for another analogy, think of each page as a technical publication about whatever topic to which it relates. Now, if you go pull a scientific research publication on topic X, does it start, on page 1, with the "references" section? No, it does not. It starts on page 1 with the topic to which it relates (or more commonly background). The "references" section (almost directly analogous to the "see also" on the wiki pages) is attached at the end of the document, not at the beginning where it just interrupts the flow of the page describing whatever topic it is that the page is about. If you really want a fast way to get to the "see also" section of a page, then put a <> entry at the top of the page, which will generate a cross-reference set of links to all of the header elements on the page. [PYK] 2014-02-03: It doesn't work that way for me because I usually don't know which page is worth reading, but with the '''see also''' section near the top, I can quickly build up a list of potentially relevant pages, open up a number of them up at once, and scour them from top to bottom. <> does take up a lot of real estate at the top -- usually at least as much as '''see also''', and the same information is already available in the sidebar. I'll have another go at using '''see also''' at the bottom of pages, to see if it isn't some modifiable habits informing my opinion about that. ---- [PYK] 2014-03-03: I moved the contact info for [Jean-Luc Fontaine] from [stooop], so simply reverting the edit to [Jean-Luc Fontaine] is going to lose information. The alternative to putting contact info on the pesron's individual page is duplicating it on multiple pages and then remembering to update it in those multiple locations whenever the info updates. Same thing with websites. It's easier to keep that info on a personal page and then reference the person on the relevant projects. <> Person