Documentation visual style feedback

[Zedna]

This is not a vote per-se. The theme stays or goes for mostly bureaucratic reasons rather than aesthetic reasons. Your dislike puts you in the minority of those who have been vocal anyway.

Then at least changes mentioned by Valik in post #32 are neccesarry.

[trancexx]

Why are changes, not already done, necessary?

... Let's be construcive. Why?

edit: this is what it looks now, or this maybe, and this is new intro. (server will be up for few hours)

May I read constructive critic?

Edited December 13, 2011 by trancexx
removed links

[guinness]

I've been following the updates you've been making and can say the whitespace is reduced.

[Valik]

The size of font for examples is not small. The size of it is 11px to match the size of the font used for the rest of the page (because they are different type of fonts they are rendered differently; Courier New generally takes more space than Segoe UI).

This size could have been 12px but for some reason inside chm that 1px makes bigger difference than it would be expected (making the font much skinnier, to my experience).

Or someone mean even bigger font? That would break the style totally.

Also the new font is rendered bigger than the old one within other browsers than IE for online documentation.

So use a different font if Courier New becomes too large when you change it. Use a proportional font, I don't care. The current example font is too small making it harder to read than it needs to be.

White space is constructive element of new style. It does not distract attention from content, it serves it. Amount of white space around function name is like that not to visually differ from amount of it used for sections separations.

The whitespace isn't the problem, it's the lack of information at the top. I never said "reduce the whitespace". I said reduce the font of the function name or remove the "Function reference" line. The idea is to get more information visible. I prefer the latter approach. You can keep the whitespace above and below the function name and even keep it the same size. It will bring more information into initial frame. It even matches MSDN closer which should make you happy.

You ask me to trust you to make a change yet you do not trust me. I have to explain in verbose detail ad nauseum why I want something done. I have to bring this fight public to get you to try and see the style is not going to be bad when it receives a few usability improvements.

Jos, here are my custom colors:

expandcollapse popup

custom.style.string=fore:#FF0000
custom.style.number=fore:#0000FF
custom.style.comment=fore:#008000,italics
custom.style.keyword=fore:#0000FF
custom.style.operator=fore:#FF8000
custom.style.preprocessor=fore:#808000
custom.style.variable=fore:#5A5A5A
custom.style.function=fore:#000090

# White space
style.au3.0=fore:#000000
# Comment line
style.au3.1=$(custom.style.comment)
# Comment block
style.au3.2=$(custom.style.comment)
# Number
style.au3.3=$(custom.style.number)
# Function
style.au3.4=$(custom.style.function)
# Keyword
style.au3.5=$(custom.style.keyword)
# Macro
style.au3.6=fore:#808000
# String
style.au3.7=$(custom.style.string)
# Operator
style.au3.8=$(custom.style.operator)
# Variable
style.au3.9=$(custom.style.variable)
# Send keys in string
style.au3.10=fore:#808080
# Pre-Processor
style.au3.11=$(custom.style.preprocessor)
# Special
style.au3.12=fore:#DC143C
# COM Objects
style.au3.14=fore:#993399
#Standard UDF's
style.au3.15=fore:#0080FF

[GEOSoft]

Valik

I haven't been vocal for a reason; I'll just be accused of resisting change again. To me there was nothing that needed changing as far as styles were concerned.

That being said it makes 0% difference to me what happens with it.

[AZJIO]

Help-Example.7z 6KB, default.css, Assign.htm

Edited December 12, 2011 by AZJIO

[funkey]

On page "Standard Windows Fonts" the operating systems are not visible (wrong color).

[trancexx]

The whitespace isn't the problem, it's the lack of information at the top. I never said "reduce the whitespace". I said reduce the font of the function name or remove the "Function reference" line. The idea is to get more information visible. I prefer the latter approach. You can keep the whitespace above and below the function name and even keep it the same size. It will bring more information into initial frame. It even matches MSDN closer which should make you happy.

There is no lack of information. All of the information that needs be there is there.

If you think there is not enough data for used space then you are referring to whitespace so even if your first sentence says the whitespace is not the problem, the rest is saying otherwise.

Adding "Function" to function name isn't valid option because we have really long names for some UDF functions and help file's html body space is not wide as browser page.

You ask me to trust you to make a change yet you do not trust me. I have to explain in verbose detail ad nauseum why I want something done.

Yes.

The only difference is that I trust you. Your last post in that other thread shows to me that I may be not completely right about that.

Anyway, I have made few more changes going to your direction. I hope this time you will actually see them done before making conclusions.

Next change I do will be reverting. I want this done one way or the other, too much time is lost.

[Jos]

Jos, here are my custom colors:

expandcollapse popup

custom.style.string=fore:#FF0000
custom.style.number=fore:#0000FF
custom.style.comment=fore:#008000,italics
custom.style.keyword=fore:#0000FF
custom.style.operator=fore:#FF8000
custom.style.preprocessor=fore:#808000
custom.style.variable=fore:#5A5A5A
custom.style.function=fore:#000090

# White space
style.au3.0=fore:#000000
# Comment line
style.au3.1=$(custom.style.comment)
# Comment block
style.au3.2=$(custom.style.comment)
# Number
style.au3.3=$(custom.style.number)
# Function
style.au3.4=$(custom.style.function)
# Keyword
style.au3.5=$(custom.style.keyword)
# Macro
style.au3.6=fore:#808000
# String
style.au3.7=$(custom.style.string)
# Operator
style.au3.8=$(custom.style.operator)
# Variable
style.au3.9=$(custom.style.variable)
# Send keys in string
style.au3.10=fore:#808080
# Pre-Processor
style.au3.11=$(custom.style.preprocessor)
# Special
style.au3.12=fore:#DC143C
# COM Objects
style.au3.14=fore:#993399
#Standard UDF's
style.au3.15=fore:#0080FF

For anyone that want to have a look at the new proposed scheme for SciTE:

- Download the attached file into "C:Program Files (x86)AutoIt3SciTESciTEConfig" and rename it to remove the ".txt" at the end.

- Start SciTEConfig (Ctrl+1)

- Click Tab 'Color Settings"

- Click "New Scheme" button"

- Select "NewSciTEScheme ==>New SciTE Standard Color scheme"

To reverse select " SciTE4AutoIt3" in the last step.

Jos

Edited December 12, 2011 by Jos

[guinness]

By the looks of things this new style closely resembles Valik's MSDEV2.SciTEConfig file.

Edit: At first I wasn't convinced by the proposed new SciTE style, I was concerned it would be difficult to distinguish between variables and normal text. But having used it for 30 minutes I'm really liking the clean effect it has on the screen and the fact it mimics the style of Visual Studio 2010 (which I don't use) leads me that little bit closer to looking like a real programmer.

Edited December 12, 2011 by guinness

[Melba23]

trancexx,

Thank you for making the changes you have - but although I can live with it, I still feel there is too much whitespace between the different sections. I notice in AZJIO's top picture that a reduction in font size for the section titles has greatly reduced this whitespace - is it something as simple as making sure that the intervening blank line has the text size and not that of the title? That has caught me out in PowerPoint more times that I care to remember.

As I said before, I think the new style is a great improvement over the old one - we are talking subtle changes to your suggested format here and I reiterate that I would be very happy with the first of the 3 function examples you showed (the Introduction example is already perfect in my eyes).

Again thanks for taking the time to do it - and please excuse the moans of those of us who come along and poke holes in your work.

M23

[AZJIO]

Updated css. Restored in some texts the font Verdana

Help-Example.7z 6KB, default.css, Assign.htm

[GEOSoft]

AZJIO

If the help file ever became even remotely like the black one; I for one wouldn't take the time of day to open it even to help someone out. There is nothing professional looking about it.

[trancexx]

trancexx,

Thank you for making the changes you have - but although I can live with it, I still feel there is too much whitespace between the different sections. I notice in AZJIO's top picture that a reduction in font size for the section titles has greatly reduced this whitespace - is it something as simple as making sure that the intervening blank line has the text size and not that of the title? That has caught me out in PowerPoint more times that I care to remember.

As I said before, I think the new style is a great improvement over the old one - we are talking subtle changes to your suggested format here and I reiterate that I would be very happy with the first of the 3 function examples you showed (the Introduction example is already perfect in my eyes).

Again thanks for taking the time to do it - and please excuse the moans of those of us who come along and poke holes in your work.

M23

Thank you for really nice words.

However I didn't ask what should be done, I asked why. That's the whole thing. Constructive comment.

You whole post in that context can be reduced to "because I have a feeling".

Thanks once again.

[Melba23]

trancexx,

I asked why

It is pretty subjective - as shown by the wide range of comments that you have received.

As I mentioned in my first comments, the excessive (to my eyes) whitespace makes the page looked "washed out". The section headers already divide the page clearly into the various sections - the whitespace over-accentuates the separation and reduces the overall cohesion of the information displayed. It is not a matter of scrolling - many of the pages demand that and no-one (I hope) is suggesting that we try and cram everything into a 25cm high box.

-------------------------------------------------------------------------------------------------------------

Section 1

The special flag $GUI_BKCOLOR_LV_ALTERNATE can be used with Listview control to give alternate background of the ListviewItems lines.

The odd lines will get the color set by GUICtrlSetBkColor of the Listview control.

The even lines will get the color set by GUICtrlSetBkColor of the ListviewItem control.

Section 2

For ListView, ListViewItem controls :

To update a specific column just forget about the others ie "||update" to update 3rd column.

If "update" is empty the column/subitem will be erased. For example "|" will erase the second column/subitem, "" will erase the first.

-------------------------------------------------------------------------------------------------------------

Section 1

The special flag $GUI_BKCOLOR_LV_ALTERNATE can be used with Listview control to give alternate background of the ListviewItems lines.

The odd lines will get the color set by GUICtrlSetBkColor of the Listview control.

The even lines will get the color set by GUICtrlSetBkColor of the ListviewItem control.

Section 2

For ListView, ListViewItem controls :

To update a specific column just forget about the others ie "||update" to update 3rd column.

If "update" is empty the column/subitem will be erased. For example "|" will erase the second column/subitem, "" will erase the first.

-------------------------------------------------------------------------------------------------------------

Personally, I find the first of those examples much nicer to look at - although not necessarily easier to read.

As to concrete reasons for adopting the first example, I have had a lot of training on PowerPoint over the years and in all of the various courses and manuals the suggested spacing between sections is as the first example - the second example would not be accepted by any of the people/organisations (of various nationalities) that I have worked for. Now I know PowerPoint is not the be-all-and-end-all of the matter, but it does tend to be the de facto standard for visual presentation.

I hope that goes some way to explaining my position - I can offer nothing more concrete. And as I stated earlier I am not going to throw my toys out of the cot if the whitespace remains as it is.

M23

[AZJIO]

GEOSoft

My eyes are tired of the white Help_AutoIt for a few hours of work, so I use a black style in the editor and in the Help_AutoIt. Well, when people have choices.

[Valik]

You whole post in that context can be reduced to "because I have a feeling".

This is probably the most important "why" to listen to. I'll listen to my gut instinct over "experts" any day of the week.

If you think there is not enough data for used space then you are referring to whitespace so even if your first sentence says the whitespace is not the problem, the rest is saying otherwise.

If I wanted to say the whitespace was a problem I would say the whitespace is a problem. Did I say that? No, I didn't. So if you fail to comprehend the rest of the post that's your own problem. I assert once again, the whitespace is not the issue. Much like we will have issues if you make more work for me, we will also have issues if you attempt to misinterpret or misconstrue the things I say. I say what I mean; I do not say one thing when I really mean another.

[Valik]

I just re-built the documentation and it looks much better now after those changes. The readability has gone up but the aesthetic has not changed.

[czardas]

I just tried Valik's NewSciTEScheme. At a first glance I would have to say it's very clear to read. The only thing is that I'm not too keen on the red strings. Depending on how much text (wrapped in quotes) your script contains, the script can turn out looking very red. I think it's possible that such a stark contrast may play tricks on some tired eyes.

[wraithdu]

I set a light gray background to the red strings. It's a bit easier on the eyes while making the strings stand out better (good when you're building strings and paths from variables, for example).