Posts: 98
Threads: 39
Joined: Apr 2010
Reputation:
0
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.
Posts: 805
Threads: 135
Joined: Apr 2009
Reputation:
5
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
Posts: 1,763
Threads: 55
Joined: Aug 2019
Reputation:
24
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! ![Tongue Tongue](https://www.boriel.com/forum/images/smilies/tongue.png) ). 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.
Posts: 98
Threads: 39
Joined: Apr 2010
Reputation:
0
britlion Wrote:Might be better to keep the capital PEEK though - some people still program with reserved words capitalized ![Wink Wink](https://www.boriel.com/forum/images/smilies/wink.png)
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.
Posts: 98
Threads: 39
Joined: Apr 2010
Reputation:
0
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 ![Smile Smile](https://www.boriel.com/forum/images/smilies/smile.png) Now it went back to the default one, in order to see the changes.
Posts: 1,763
Threads: 55
Joined: Aug 2019
Reputation:
24
programandala.net Wrote:britlion Wrote:Might be better to keep the capital PEEK though - some people still program with reserved words capitalized ![Wink Wink](https://www.boriel.com/forum/images/smilies/wink.png)
Don't worry, the docs won't impose any coding style ![Wink Wink](https://www.boriel.com/forum/images/smilies/wink.png)
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:
Posts: 805
Threads: 135
Joined: Apr 2009
Reputation:
5
I agree woth Boriel here - I think to highlight syntax in an example, capitalization does make a difference.
Posts: 615
Threads: 49
Joined: Feb 2009
Reputation:
2
I agree too about this. lower case letters make it less readabel.
Posts: 98
Threads: 39
Joined: Apr 2010
Reputation:
0
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.
Posts: 1,763
Threads: 55
Joined: Aug 2019
Reputation:
24
Okay. <zxbasic>...</zxbasic> enabled. I will start to change syntax color, so I gets more readable.
Update: Have a look at Clock example.
Posts: 98
Threads: 39
Joined: Apr 2010
Reputation:
0
boriel Wrote:Clock example.
Much more readable now, fine.
Do you think automatic capitals in keywords are easy to implement?
Posts: 98
Threads: 39
Joined: Apr 2010
Reputation:
0
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
Posts: 1,763
Threads: 55
Joined: Aug 2019
Reputation:
24
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! ![Tongue Tongue](https://www.boriel.com/forum/images/smilies/tongue.png) ) 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.
Posts: 98
Threads: 39
Joined: Apr 2010
Reputation:
0
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.
Posts: 1,763
Threads: 55
Joined: Aug 2019
Reputation:
24
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.
|