Suggestion for the Syntax section

[programandala.net]

Hi all,

I've been thinking how to simplify and homogenize the docs; and also how to make them easier to create and mantain.

I'm preparing a list of detailed suggestions for your consideration, but the first one is ready:

I suggest for the Syntax section:

• to use <freebasic></freebasic>. I think it's easier to write and to read, and it looks nicer and more clear. The current combination of bold and italic is not comfortable to edit (besides, I think their Mediawiki notation is unhandy and hard to read).
  
• to show syntax variants simply one after another, without "or" or any kind of comment; simply one line of code per variant (no need to mark optional parameters). No text in the section, only clear code with proper parameter names.
  
• to use lowercase (it's a fact it's easier to read and to write) for everything (keywords and parameters).
  
• to use camelCase for parameters with compound names (they cannot be reserved words anymore, because of <freebasic>).

You can see and example in the peek page I just rearranged. Note I left both syntax layouts for you to compare. Also the rest of the page is changed to illustrate some of my future suggestions.

[britlion]

I think I agree with this.

It's not really life-altering, but it does look clearer. Might be better to keep the capital PEEK though - some people still program with reserved words capitalized

[boriel]

Okay then. I agree. Then I have to change either the yellow background or the yellow token color. Which one do you prefer?
Note: I used yellow background as a nostalgic homage to MicroHobby (a Spanish ZX Spectrum Magazine) yellow background listings (I somewhat miss it! ). Also a dark-blue (a la Borland Delphi's background) should be readable as is. Check the wiki now.

Update: No way. I will have to change some FreeBasic's coloring scheme, since it's so variable (dark and light colors) it's almost unreadable.

[programandala.net]

Might be better to keep the capital PEEK though - some people still program with reserved words capitalized

Don't worry, the docs won't impose any coding style

The facts are the task is huge, we are few people, and and the more clear, simpler and easier the better. Lowercase is easier to write, to edit and to read.

[programandala.net]

a nostalgic homage to MicroHobby (a Spanish ZX Spectrum Magazine)

A great magazine. I have the whole paper collection, and I still read it and consult it a lot after so many years. It's full of useful information for coding, any level.

No way. I will have to change some FreeBasic's coloring scheme, since it's so variable (dark and light colors) it's almost unreadable.

I had my own skin selected Now it went back to the default one, in order to see the changes.

[boriel]

Might be better to keep the capital PEEK though - some people still program with reserved words capitalized

Don't worry, the docs won't impose any coding style

The facts are the task is huge, we are few people, and and the more clear, simpler and easier the better. Lowercase is easier to write, to edit and to read.

That's right: lowercase letters turns to be more readable, but on the other hand, for tutorial/learning purposes, CAPITALIZED might be better (they're just short listings). Anyway, I will try the <freebasic></freebasic> tag to do it. Even better, maybe I will define a <zxbasic></zxbasic>? :roll:

[britlion]

I agree woth Boriel here - I think to highlight syntax in an example, capitalization does make a difference.

[LCD]

I agree too about this. lower case letters make it less readabel.

[programandala.net]

That's right: lowercase letters turns to be more readable, but on the other hand, for tutorial/learning purposes, CAPITALIZED might be better (they're just short listings). Anyway, I will try the <freebasic></freebasic> tag to do it. Even better, maybe I will define a <zxbasic></zxbasic>? :roll:

OK. I agree: in short tutorial listings, uppercase keywords help people to understand the programs.

The best solution would be a <zxbasic> tag to do the task. That would be great. Meanwhile, I'll use uppercase keywords in the syntax and examples.

May you simply "copy" the <freebasic> extension to a new one called <zxbasic>, even if it does the same? Then I would start to change it in the docs. I think those Mediawiki extensions are written in PHP (some time ago I adapted one of them to my own wiki engine, in order to call Python programs from the pages). If so, I could adapt the current code of <freebasic> to <zxbasic>, included the capitalization. Just send me the code.

[boriel]

Okay. <zxbasic>...</zxbasic> enabled. I will start to change syntax color, so I gets more readable.

Update: Have a look at Clock example.

[programandala.net]

Clock example.

Much more readable now, fine.

Do you think automatic capitals in keywords are easy to implement?

[programandala.net]

Okay. <zxbasic>...</zxbasic> enabled. I will start to change syntax color, so I gets more readable.].

Maybe the ASM sections could be highlighted too, but I guess it will be problematic. If only including the assembler opcodes in the extension code, there will be some coincidences with BASIC (e.g. AND, OR...). I think some rewriting of the extension would be needed, to detect the assembler keywords in the ASM regions.and treat them apart

[boriel]

Clock example.

Much more readable now, fine.

Do you think automatic capitals in keywords are easy to implement?

They already are. The extension do it automatically. Now there are (I've just find out! ) 2 ways to specify code:
<zxbasic>...</zxbasic> or
<code zxbasic n>...</code> (lines automatically numbered, and more interline spacing, much readable) or
<code <zxbasic f>...</code> like above, but "fancier" numbers (bold numbers every 3 lines).

The 1st form must be used with programs already having line numbers. The 2nd and 3rd form (better use always the 3rd) we must discuss.

[programandala.net]

<zxbasic>...</zxbasic> or
<code zxbasic n>...</code> (lines automatically numbered, and more interline spacing, much readable) or
<code <zxbasic f>...</code> like above, but "fancier" numbers (bold numbers every 3 lines).

Great. I had already started to use <zxbasic>.

I think code without line numbers should be respected and shown as is with <zxbasic>, without line numbers, unless the explaining text in the page has to mention certain lines.

[boriel]

Thanks a lot. I've already <zxbasic'ed> the examples and games listings. Also, note that instead of using

Code:

<zxbasic>
...
listing
...
</zxbasic>

use

Code:

<zxbasic>...
listing
...</zxbasic>

This way you avoid blank lines at top and bottom in the listings.