FAQ  •  Register  •  Login

Suggestion for the Syntax section

<<

programandala.net

Posts: 98

Joined: Fri Apr 09, 2010 12:50 am

Location: España/Hispanujo/Spain

Post Fri Jun 18, 2010 4:42 pm

Suggestion for the Syntax section

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

Posts: 766

Joined: Mon Apr 27, 2009 7:26 pm

Location: Slough, Berkshire, UK

Post Fri Jun 18, 2010 5:10 pm

Re: Suggestion for the Syntax section

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

Site Admin

Posts: 1463

Joined: Wed Nov 01, 2006 6:18 pm

Location: Santa Cruz de Tenerife, Spain

Post Fri Jun 18, 2010 5:32 pm

Re: Suggestion for the Syntax section

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! :cry: :P). 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

Posts: 98

Joined: Fri Apr 09, 2010 12:50 am

Location: España/Hispanujo/Spain

Post Fri Jun 18, 2010 5:56 pm

Re: Suggestion for the Syntax section

britlion wrote: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

Posts: 98

Joined: Fri Apr 09, 2010 12:50 am

Location: España/Hispanujo/Spain

Post Fri Jun 18, 2010 6:02 pm

Re: Suggestion for the Syntax section

boriel wrote: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.

boriel wrote: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

Site Admin

Posts: 1463

Joined: Wed Nov 01, 2006 6:18 pm

Location: Santa Cruz de Tenerife, Spain

Post Fri Jun 18, 2010 8:35 pm

Re: Suggestion for the Syntax section

programandala.net wrote:
britlion wrote: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

Posts: 766

Joined: Mon Apr 27, 2009 7:26 pm

Location: Slough, Berkshire, UK

Post Sat Jun 19, 2010 12:58 am

Re: Suggestion for the Syntax section

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

LCD

Posts: 596

Joined: Fri Feb 13, 2009 3:11 pm

Location: Vienna, Austria

Post Sat Jun 19, 2010 12:03 pm

Re: Suggestion for the Syntax section

I agree too about this. lower case letters make it less readabel.
------------------------------------------------------------
http://lcd-one.da.ru redirector is dead
Visit my http://members.inode.at/838331/index.html home page!
<<

programandala.net

Posts: 98

Joined: Fri Apr 09, 2010 12:50 am

Location: España/Hispanujo/Spain

Post Sun Jun 20, 2010 12:51 pm

Re: Suggestion for the Syntax section

boriel wrote: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

Site Admin

Posts: 1463

Joined: Wed Nov 01, 2006 6:18 pm

Location: Santa Cruz de Tenerife, Spain

Post Sun Jun 20, 2010 12:57 pm

Re: Suggestion for the Syntax section

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

Posts: 98

Joined: Fri Apr 09, 2010 12:50 am

Location: España/Hispanujo/Spain

Post Sun Jun 20, 2010 2:33 pm

Re: Suggestion for the Syntax section

boriel wrote:Clock example.


Much more readable now, fine.

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

programandala.net

Posts: 98

Joined: Fri Apr 09, 2010 12:50 am

Location: España/Hispanujo/Spain

Post Sun Jun 20, 2010 2:40 pm

Re: Suggestion for the Syntax section

boriel wrote: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

Site Admin

Posts: 1463

Joined: Wed Nov 01, 2006 6:18 pm

Location: Santa Cruz de Tenerife, Spain

Post Sun Jun 20, 2010 2:41 pm

Re: Suggestion for the Syntax section

programandala.net wrote:
boriel wrote: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! :P) 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

Posts: 98

Joined: Fri Apr 09, 2010 12:50 am

Location: España/Hispanujo/Spain

Post Sun Jun 20, 2010 3:26 pm

Re: Suggestion for the Syntax section

boriel wrote:<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

Site Admin

Posts: 1463

Joined: Wed Nov 01, 2006 6:18 pm

Location: Santa Cruz de Tenerife, Spain

Post Sun Jun 20, 2010 3:54 pm

Re: Suggestion for the Syntax section

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

Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest

cron
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group.
Designed by Vjacheslav Trushkin for Free Forums/DivisionCore.

phpBB SEO