+- Forum (https://www.boriel.com/forum)
+-- Forum: Compilers and Computer Languages (https://www.boriel.com/forum/forumdisplay.php?fid=12)
+--- Forum: ZX Basic Compiler (https://www.boriel.com/forum/forumdisplay.php?fid=11)
+---- Forum: Documentation (https://www.boriel.com/forum/forumdisplay.php?fid=17)
+---- Thread: Suggestion for the Syntax section (/showthread.php?tid=256)
Pages:
1
2
Suggestion for the Syntax section - programandala.net - 06-18-2010
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.
Re: Suggestion for the Syntax section - britlion - 06-18-2010
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
Re: Suggestion for the Syntax section - boriel - 06-18-2010
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.
Re: Suggestion for the Syntax section - programandala.net - 06-18-2010
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.
Re: Suggestion for the Syntax section - programandala.net - 06-18-2010
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.
Re: Suggestion for the Syntax section - boriel - 06-18-2010
programandala.net 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: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.
Re: Suggestion for the Syntax section - britlion - 06-19-2010
I agree woth Boriel here - I think to highlight syntax in an example, capitalization does make a difference.
Re: Suggestion for the Syntax section - LCD - 06-19-2010
I agree too about this. lower case letters make it less readabel.
Re: Suggestion for the Syntax section - programandala.net - 06-20-2010
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.
Re: Suggestion for the Syntax section - boriel - 06-20-2010
Okay. <zxbasic>...</zxbasic> enabled. I will start to change syntax color, so I gets more readable.
Update: Have a look at Clock example.
Re: Suggestion for the Syntax section - programandala.net - 06-20-2010
boriel Wrote:Clock example.
Much more readable now, fine.
Do you think automatic capitals in keywords are easy to implement?
Re: Suggestion for the Syntax section - programandala.net - 06-20-2010
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
Re: Suggestion for the Syntax section - boriel - 06-20-2010
programandala.net Wrote:They already are. The extension do it automatically. Now there are (I've just find out!boriel Wrote:Clock example.
Much more readable now, fine.
Do you think automatic capitals in keywords are easy to implement?
) 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.
Re: Suggestion for the Syntax section - programandala.net - 06-20-2010
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.
Re: Suggestion for the Syntax section - boriel - 06-20-2010
Thanks a lot. I've already <zxbasic'ed> the examples and games listings. Also, note that instead of using
Code:
<zxbasic>
...
listing
...
</zxbasic>Code:
<zxbasic>...
listing
...</zxbasic>