Intrinsic defines

Forum for discussion about the documentation project.
speedfixer
Posts: 326
Joined: Nov 28, 2012 1:27
Location: California

Intrinsic defines

Postby speedfixer » Mar 27, 2019 21:04

should have a link from 'PREPROCESSOR' topic
badidea
Posts: 1358
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Intrinsic defines

Postby badidea » Mar 27, 2019 22:45

speedfixer wrote:should have a link from 'PREPROCESSOR' topic

In the form of a "See also: Preprocessor" like on the bottom of the Compiler Switches page?
speedfixer
Posts: 326
Joined: Nov 28, 2012 1:27
Location: California

Re: Intrinsic defines

Postby speedfixer » Mar 28, 2019 8:18

Actually, should be on CatPgPreProcess as a key component of the preprocessor information as one of the large groups, but there just isn't room there.

Just because CatPgPreProcess starts with "Commands that ..." doesn't mean that these should be excluded. That wording can be changed.

I won't suggest how the page can be changed. Anything that helps connect the dots would be better. More cross-links everywhere makes things easier to find for someone new and really curious. There are a lot of nuggets of info buried throughout the docs. Frequently, for me, that little extra on an 'unrelated' page was the key to understanding how a keyword could be used more precisely and effectively.

Also, I just think we shouldn't forget that the preprocessor isn't just for macros: those intrinsics are what makes your program, source, library and build system simple and truly multi-platform.
fxm
Posts: 8965
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Intrinsic defines

Postby fxm » Mar 28, 2019 8:55

We could start with the very simple proposal of badidea before considering a possible merging or something else regarding these 2 CatPg.
speedfixer
Posts: 326
Joined: Nov 28, 2012 1:27
Location: California

Re: Intrinsic defines

Postby speedfixer » Mar 28, 2019 18:11

Anything for now is good.

When a table or list is presented, it is better to stay all on one page to be able to see it all at once. Easy to collate in your head. If you have to go to another page, make it a real (visual) page and concept break - couple of blank lines, even. I, personally, would spend way too much time rethinking the whole presentation. Better to just get it done.

AetherFox had given a tiny intro on how to use conditional compiling(TutConditionalCompilation), but another example embedded in real FB code might better show its value as a debugging tool (simple stuff: value dumps - like an assert, runtime pause, etc.). Then point to a longer debug article somewhere. In that article I would add a SIMPLE example to show how OS, multithread, platform detection can be used to make a single source, multi-platform program. If only __FB_GUI__ were multi-platform (which it can be, hint, hint) - then a simple example to drop values to the console during runtime away from the graphic screen would be a fine example. I do this in Linux all the time, but making a clean, simple program to display this would not be a good example for a beginner.

At CatPgProgrammer, there was an intent by someone to add more discussion about the preprocessor that never got fulfilled. Good Idea, but just empty placeholders now.

BTW, all those empty placeholders everywhere contributes to the perception by someone browsing/shopping for a language that FB is not mature, and lacks polish and completion. ESPECIALLY when some of the topics are very, very basic to understanding the difference between this language and another. Immediately, I would change the title in CatPgProgrammer of 'Variable Scope' to 'Variable Scope (and lifetime)' and extend the ProPgVariableScope page a little. They aren't the same topic, but most beginners confuse the two and need to know more about scope than lifetime, anyway. Then get rid of the empty placeholder for 'Variable Lifetime' in CatPgProgrammer. Beginners don't need a discussion of static/dynamic variables, etc. if they don't know about scope. They will get there when they need to.

All of you that want to get involved but aren't sure about you're expertise or ability to express yourself, these are good places to start.
Any article proposed, then argued over, will stretch your own knowledge and talents, and maybe expose places for improvement. A POOR ARTICLE is better than a constant reminder that basic language foundation documents are incomplete.

I think (hope) everyone can appreciate that our contributors and readers are a very international mix and you can then forgive/overlook/tolerate language errors and not be overly sensitive to (in English) poor word choices or expressions. This an international world, now. Stretch to understand what someone has as an intent. Assume the best, not the worst.

I don't know him; he doesn't know me. Why ever take it/make it personal? If you disagree - say so, forget it - then shut up. A criticism gets accepted, or it doesn't. If THEY make it personal - you don't have to respond. History clearly shows when someone seems to have their own personal agenda, ego or adjustment problem, lack of understanding, etc. Be patient.

But at least TRY.
badidea
Posts: 1358
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Intrinsic defines

Postby badidea » Mar 28, 2019 18:51

"See also: Intrinsic Defines" added to CatPgPreProcess
(doh, forgot to comment my wiki change)
fxm
Posts: 8965
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Intrinsic defines

Postby fxm » Mar 29, 2019 6:51

speedfixer wrote:All of you that want to get involved but aren't sure about you're expertise or ability to express yourself, these are good places to start.
Any article proposed, then argued over, will stretch your own knowledge and talents, and maybe expose places for improvement.

For almost a year, I have also offered users to freely write articles, even incomplete drafts, rather on the documentation forum less formal than the FBWiki, thinking that it would dispel their reluctance, but without much success so far.
fxm
Posts: 8965
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Intrinsic defines

Postby fxm » Mar 29, 2019 8:48

speedfixer wrote:At CatPgProgrammer, ...
... all those empty placeholders everywhere contributes to the perception by someone browsing/shopping for a language that FB is not mature, and lacks polish and completion...
A POOR ARTICLE is better than a constant reminder that basic language foundation documents are incomplete.

I think there are certain topics in the programmer's guide that I know quite a bit, and that with a little time I could complete, with perhaps something already said in the keyword pages, but presented under a other angle.
For example:
- Passing Arrays to Procedures
- New and Delete
- Recursion
- Constructors and Destructors

But, I would like to leave room for other users too!
Tourist Trap
Posts: 2756
Joined: Jun 02, 2015 16:24

Re: Intrinsic defines

Postby Tourist Trap » Mar 30, 2019 13:40

fxm wrote:For almost a year, I have also offered users to freely write articles, even incomplete drafts, rather on the documentation forum less formal than the FBWiki, thinking that it would dispel their reluctance, but without much success so far.

I tried myself modestly to contribute, but rather in the form of tips and tricks. I've made one or two infographics about byval and byref (viewtopic.php?f=7&t=24951&p=223278&hilit=byval#p223278, some images are broken it seems), made some macros to explore arrays and variadic macros, and also a written article on how to give an alias (name) to a variable in many contexts in freebasic.

I find it a lot more difficult to write an article on a classical stuff, since it seems forbidden to start with a peculiar approach (biased). About me however, I can only see things via my prism since I really lack of solid background, as well on width, and on length of time of practice.

However, the worst issue for a talkative guy like me is a matter of time. Anyway as a documentation reader on a regular basis I hope I can help signaling typos and misleading wording in my eyes. As for the other users, there seems to be really a lot of specialists of such or such topics that I would be pleased to find writting articles. I can thing of dahfi for instance for alpha blending, and this is just for the example.
dodicat
Posts: 5758
Joined: Jan 10, 2006 20:30
Location: Scotland

Re: Intrinsic defines

Postby dodicat » Mar 31, 2019 10:58

An old adage here is "Too many cooks spoil the broth".
For fxm perhaps
"Trop de cuisiniers gâtent la sauce"
This is why I don't interfere and clutter the documentation pages.
But I do read fxm's posts, and liked the threading articles.
Also liked Mr Swiss's little change to my code, using threadwait rather than threaddetatch.

Return to “Documentation”

Who is online

Users browsing this forum: No registered users and 1 guest