Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[MrC]

Over the past couple of weeks, I rewrote the Expression Language wiki page.  I had a couple of goals:

   - make the page easier to update (for new or changed functions)
   - formalize and standardize the style of the functions, arguments, etc.
   - automate generation of the function table from plain text as input
   - provide a more comprehensive overview of the expression language
   - provide more instructive narrative

Hopefully you find the page at least as useful as marko's original and definitive work done back in Oct 2010.

Feedback and criticism welcome.

[rlebrette]

That's great and more it's pretty nice...
Thanks for the good work.

[JimH]

Thanks, MrC!  Amazing work!

[6233638]

Thanks for taking the time to update this page - I use it as a reference all the time.

I did find the old page easier to parse though.
 

• Description, Modes, and Examples had their own sections. Description and modes now seem to have been combined, so I now have to read the top section to find what I'm looking for.
• The old theme made each expression distinct from the background, and each section had a border between it. It all blends together now and doesn't scan as easily.
• There's no space between each example now, or the paragraphs at the top of the page. Indentation is used instead of a new line to save space. Unless it's a list, I don't think it should be indented, and whitespace is important for legibility.
• Please just specify monospace instead of Consolas italic (at least don't make it italic!) and the color choice makes it look like a hyperlink.

 
Please don't take this as a criticism of your hard work though - overall it's a good change.

[MrC]

No problem, and thanks for the feedback.

1. In some cases, the Construction and the function's overview were intermixed, and it was difficult to refer to argument place holders in the description before the construction was shown.  I opted for showing the function's syntax up front, which allows the argument placeholders to be used in the descriptive text.  In some cases, the construction was a single line.

2. Can you explain what you mean by "The old theme made each expression distinct from the background"?  Each section does have a border - the inner border is very subtle.  If folks feel strongly, I'll make it more prominent.

3. I can add a larger chunk of whitespace after each example's text if that will help.  The whitespace between paragraphs is larger than that within a paragraph. This is how the wiki breaks paragraphs at newlines.  The previous page added an extra break, so it was like 1.5x.

4. I can use monospace.  I used Consolas back when I did the regex() documentation, because the default monospace made examples very difficult to read.  As far as italics for argument values, I'm not inclined to remove the italics here.  Italics are reserved here for placeholder text, and this is common in technical documentation.

[MrC]

Here are samples using each of: Monaco, Courier New, Courier, and Consolas.  If you save them, you can preview each back to back to compare.
I don't like Monaco when it is bold.

[magnust]

Great page! A LOT to take in  Love it 

[6233638]

1. In some cases, the Construction and the function's overview were intermixed, and it was difficult to refer to argument place holders in the description before the construction was shown.  I opted for showing the function's syntax up front, which allows the argument placeholders to be used in the descriptive text.  In some cases, the construction was a single line.

2. Can you explain what you mean by "The old theme made each expression distinct from the background"?  Each section does have a border - the inner border is very subtle.  If folks feel strongly, I'll make it more prominent.

3. I can add a larger chunk of whitespace after each example's text if that will help.  The whitespace between paragraphs is larger than that within a paragraph. This is how the wiki breaks paragraphs at newlines.  The previous page added an extra break, so it was like 1.5x.

If I'm writing up a complex expression, I may need to refer to three or four items. If I'm quickly scanning over the page, the old theme using clearly defined borders and three sections for each expression makes that very quick; I know immediately that I want the middle section, or the last one, and it's clearly defined.
With the new look, the first two sections have now been combined, and the subtle border means that it just reads as a single block of text. I know that there are headings on the left, but it just doesn't read as easily for me. Extra whitespace would definitely help though.

4. I can use monospace.  I used Consolas back when I did the regex() documentation, because the default monospace made examples very difficult to read.  As far as italics for argument values, I'm not inclined to remove the italics here.  Italics are reserved here for placeholder text, and this is common in technical documentation.

I think the problem that I have with Consolas in general, is that it's designed to read like a regular sans-serif font, rather than clearly being a "monospaced" font, if that makes any sense.
For some people this may be a good thing, but I find it's a lot easier to scan a block of text and look for the code examples when it doesn't blend in as easily.
I think defining monospace will just use whichever font you have selected in your browser.


I do think the page looks good though - it's probably just a case of me being used to the old one, more than anything else.

[MrC]

Here's a test with the following changes:

   1. Consolas changed to monospace
   2. inner-cell function table borders
   3. removed indenting in example text
   4. added additional paragraph break in between examples

I'm not thrilled with 3 and 4.  It adds a lot of whitespace, and the examples look flat by comparison, esp. with the different font, and lowercase example expressions followed by sentence-case example text.

[kensn]

Here's a test

I like the original version....

Spend time on new items if anything...... Good info is the same as pretty info... and more info is better

[MrC]

I like the original version....

Me too, btw. :-)

... and more info is better

Suggestions?

[6233638]

Here's a test with the following changes:
   1. Consolas changed to monospace

Are you using a Mac? Your font rendering looks weird.


(should animate in any good browser)

I will say this; I'm not sure about bold monospace fonts. Consolas looks OK, Courier New does not look great.
It's far easier to see the monospace fonts in the example text with Courier New though.

I'm not thrilled with 3 and 4.  It adds a lot of whitespace, and the examples look flat by comparison, esp. with the different font, and lowercase example expressions followed by sentence-case example text.

I agree, it doesn't look right with the new "theme". If the spacing were reduced somewhat it would look better, but the indentation is clearer.

[MrC]

Yes, I'd forgotten to take the screenshots on Windows.  I've updated the test image above.

It is difficult to control the wiki's paragraph spacing, since I don't control the paragraph tag styles.  I can either place hard breaks within a paragraph, or use multiple paragraphs.  The former screws up some alignment at the top of tables, while the latter introduces too much whitespace.

[MrC]

Here's a rendering that uses Monaco throughout, and reduces the synopsis font size to 100% (down from 110%).

[6233638]

Here's a rendering that uses Monaco throughout, and reduces the synopsis font size to 100% (down from 110%).

That's looking nice, but I find it even more difficult to pick out the "code" parts from the regular text in the examples.

[MrC]

I'm going to change the font to monospace, and users can configure their browsers however they see fit.

I haven't decided about the table lines - personally I think tables should be reserved for, well, table-like information.  But the code is already there, so its no hardship either way.

I'm going to leave the indenting and smaller white space around the examples.  It was the only system I could think of that was minimal, did not use excessive whitespace, and provides quick delineation between examples.

The good news is, with just minimal changes to my script, these changes are trivial.

[MrC]

Here's some fun reading regarding monospace fonts and user preferences:

   http://www.codinghorror.com/blog/2007/10/revisiting-programming-fonts.html

[MrC]

@Mr. Number.  I met you 1/2 way.  Take a look at the changes when you get a chance.  Let's see how it stands.

[kensn]

Suggestions?

Well, not to say it is up to you, I would like to have a list of all the HTML codes supported.... I looked around and found them in various posts but....

I am amazed at how much time you put into helping with expressions, your fluency with the language is impressive. It is just a pain to go searching for the examples when you want to do something and remember that you saw it answered in a post at some point. A repository with all the examples would be great to thumb through... and may assist others to self teach themselves...

Again MrC thanks for all you do. I have piggybacked off of your knowledge many times. 

Ken

[6233638]

@Mr. Number.  I met you 1/2 way.  Take a look at the changes when you get a chance.  Let's see how it stands.

Looks good.

Here's some fun reading regarding monospace fonts and user preferences:
   http://www.codinghorror.com/blog/2007/10/revisiting-programming-fonts.html

He doesn't even have 9pt bitmapped ProFont on the list!



Sadly, everything wants to anti-alias fonts these days, and it's looking a bit too small on modern displays.
I'm surprised that Liberation Mono and Source Code Pro were missing too.

Edit: well maybe I shouldn't have been too surprised about Source Code Pro, considering that post was written in 2007…

[MrC]

Well, not to say it is up to you, I would like to have a list of all the HTML codes supported.... I looked around and found them in various posts but....

Sure, I can create a page for this.  To get you going, add an expression column in a file list and use the expression:

Code: [Select]

Normal
<b>Bold<//b>
<i>Italics<//i>
<u>Underscore<//u>
<font color="ff0000">Color<//font>
<font bgcolor="cccccc">Background Color<//font>
<font alpha="50">Alpha Blending<//font>
<font size="90%">Size 90%<//font>
<font size="80%">Size 80%<//font>
<font size="70%">Size 70%<//font>
<font size="60%">Size 60%<//font>
<font size="50%">Size 50%<//font>
<font size="40%">Size 40%<//font>
<font size="30%">Size 30%<//font>
<font size="20%">Size 20%<//font>
<font size="10%">Size 10%<//font>
<font face="Comic Sans MS">Font Face<//font>
<font color="dd1199" bgcolor="dddddd" size="90%" alpha="50%" face="Consolas" size="90%">Combination<//font>

Now, hover your mouse over the cell.  It should look similar to the attached screenshot.

[kensn]

Nice....

But I am still not giving you my money  ..

[MrC]

See:

   http://wiki.jriver.com/index.php/Media_Center_expression_language#HTML_Font_Properties

No money required.

[kensn]

MrC.. you're too good to us...