INTERACT FORUM

Please login or register.

Login with username, password and session length
Advanced search  
Pages: [1]   Go Down

Author Topic: Expression language wiki page updated  (Read 5978 times)

MrC

  • Citizen of the Universe
  • *****
  • Posts: 10462
  • Your life is short. Give me your money.
Expression language wiki page updated
« on: August 26, 2013, 02:35:10 pm »

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.
Logged
The opinions I express represent my own folly.

rlebrette

  • Guest
Re: Expression language wiki page updated
« Reply #1 on: August 26, 2013, 06:19:43 pm »

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

JimH

  • Administrator
  • Citizen of the Universe
  • *****
  • Posts: 72367
  • Where did I put my teeth?
Re: Expression language wiki page updated
« Reply #2 on: August 26, 2013, 06:26:07 pm »

Thanks, MrC!  Amazing work!
Logged

6233638

  • Regular Member
  • Citizen of the Universe
  • *****
  • Posts: 5353
Re: Expression language wiki page updated
« Reply #3 on: August 26, 2013, 08:49:11 pm »

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.
Logged

MrC

  • Citizen of the Universe
  • *****
  • Posts: 10462
  • Your life is short. Give me your money.
Re: Expression language wiki page updated
« Reply #4 on: August 26, 2013, 09:36:08 pm »

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.
Logged
The opinions I express represent my own folly.

MrC

  • Citizen of the Universe
  • *****
  • Posts: 10462
  • Your life is short. Give me your money.
Re: Expression language wiki page updated
« Reply #5 on: August 26, 2013, 10:10:36 pm »

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.
Logged
The opinions I express represent my own folly.

magnust

  • Galactic Citizen
  • ****
  • Posts: 380
Re: Expression language wiki page updated
« Reply #6 on: August 27, 2013, 12:36:04 am »

Great page! A LOT to take in  ;D Love it  :D
Logged

6233638

  • Regular Member
  • Citizen of the Universe
  • *****
  • Posts: 5353
Re: Expression language wiki page updated
« Reply #7 on: August 27, 2013, 09:09:29 pm »

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.
Logged

MrC

  • Citizen of the Universe
  • *****
  • Posts: 10462
  • Your life is short. Give me your money.
Re: Expression language wiki page updated
« Reply #8 on: August 28, 2013, 02:12:00 pm »

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.
Logged
The opinions I express represent my own folly.

kensn

  • MC Beta Team
  • Citizen of the Universe
  • *****
  • Posts: 1362
Re: Expression language wiki page updated
« Reply #9 on: August 28, 2013, 02:43:08 pm »

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
Logged
If(IsEmpty([Coffee Cup]), Coffee, Drink)

MrC

  • Citizen of the Universe
  • *****
  • Posts: 10462
  • Your life is short. Give me your money.
Re: Expression language wiki page updated
« Reply #10 on: August 28, 2013, 03:01:37 pm »

I like the original version....

Me too, btw. :-)

... and more info is better

Suggestions?
Logged
The opinions I express represent my own folly.

6233638

  • Regular Member
  • Citizen of the Universe
  • *****
  • Posts: 5353
Re: Expression language wiki page updated
« Reply #11 on: August 28, 2013, 04:56:08 pm »

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.
Logged

MrC

  • Citizen of the Universe
  • *****
  • Posts: 10462
  • Your life is short. Give me your money.
Re: Expression language wiki page updated
« Reply #12 on: August 28, 2013, 05:31:36 pm »

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.
Logged
The opinions I express represent my own folly.

MrC

  • Citizen of the Universe
  • *****
  • Posts: 10462
  • Your life is short. Give me your money.
Re: Expression language wiki page updated
« Reply #13 on: August 28, 2013, 05:48:14 pm »

Here's a rendering that uses Monaco throughout, and reduces the synopsis font size to 100% (down from 110%).
Logged
The opinions I express represent my own folly.

6233638

  • Regular Member
  • Citizen of the Universe
  • *****
  • Posts: 5353
Re: Expression language wiki page updated
« Reply #14 on: August 28, 2013, 06:22:30 pm »

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.
Logged

MrC

  • Citizen of the Universe
  • *****
  • Posts: 10462
  • Your life is short. Give me your money.
Re: Expression language wiki page updated
« Reply #15 on: August 28, 2013, 06:36:30 pm »

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.
Logged
The opinions I express represent my own folly.

MrC

  • Citizen of the Universe
  • *****
  • Posts: 10462
  • Your life is short. Give me your money.
Re: Expression language wiki page updated
« Reply #16 on: August 28, 2013, 06:43:12 pm »

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

   http://www.codinghorror.com/blog/2007/10/revisiting-programming-fonts.html
Logged
The opinions I express represent my own folly.

MrC

  • Citizen of the Universe
  • *****
  • Posts: 10462
  • Your life is short. Give me your money.
Re: Expression language wiki page updated
« Reply #17 on: August 28, 2013, 07:46:44 pm »

@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.
Logged
The opinions I express represent my own folly.

kensn

  • MC Beta Team
  • Citizen of the Universe
  • *****
  • Posts: 1362
Re: Expression language wiki page updated
« Reply #18 on: August 28, 2013, 08:03:39 pm »

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
Logged
If(IsEmpty([Coffee Cup]), Coffee, Drink)

6233638

  • Regular Member
  • Citizen of the Universe
  • *****
  • Posts: 5353
Re: Expression language wiki page updated
« Reply #19 on: August 28, 2013, 08:33:34 pm »

@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! ;D



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…
Logged

MrC

  • Citizen of the Universe
  • *****
  • Posts: 10462
  • Your life is short. Give me your money.
Re: Expression language wiki page updated
« Reply #20 on: August 28, 2013, 08:55:04 pm »

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.
Logged
The opinions I express represent my own folly.

kensn

  • MC Beta Team
  • Citizen of the Universe
  • *****
  • Posts: 1362
Re: Expression language wiki page updated
« Reply #21 on: August 28, 2013, 09:29:07 pm »

Nice....

But I am still not giving you my money  ;D..
Logged
If(IsEmpty([Coffee Cup]), Coffee, Drink)

MrC

  • Citizen of the Universe
  • *****
  • Posts: 10462
  • Your life is short. Give me your money.
Logged
The opinions I express represent my own folly.

kensn

  • MC Beta Team
  • Citizen of the Universe
  • *****
  • Posts: 1362
Re: Expression language wiki page updated
« Reply #23 on: August 29, 2013, 07:58:29 pm »

MrC.. you're too good to us... 8)
Logged
If(IsEmpty([Coffee Cup]), Coffee, Drink)
Pages: [1]   Go Up