MULTIKEY missing on page FBWiki : CatPgInput [SOLVED]

[MrSwiss]

IMHO one person (fxm) only should tend to the FBWIKI.

No, don't agree on that one.

The WIKI is, and also described to be, a community effort.
Relying on a single person (to do whatever) is IMHO, a bad idea, to start with.

Example: dkl, as a sole compiler developer, and him now quitting!
(result: ... to be seen, in the future)

[Trinity]

The WIKI is, and also described to be, a community effort.
Relying on a single person (to do whatever) is IMHO, a bad idea, to start with.

You are completely right. It is and must be a community effort though there ought to be senior editor(s) to prevent chaos and technical errors in description...
What is a big job for one man can be a smaller effort for the individual if forces are joined :-)

[dodicat]

decrypt md5!
That task is brute force and not analytical.
I wasn't asking for help.
My theme was the chm help file, fbide and using the .chm file.
That's fine MrSwiss.
Somebody oversees the new content/ideas, considers it and publishes it.
That is the idea is it not?

[St_W]

To be honest, I didn't see the reason for having two separate category pages for user input functions at first either - and I wouldn't consider myself as beginner. However, when one knows the structure of the library reference it perfectly makes sense, as the runtime library and the graphics library are documented separately (as been explained by fxm).

I think the problem is that different things are mixed here: a technical reference is something different than a tutorial. A technical reference by nature describes the functionality in a more theoretical, technical language and requires being somewhat familiar with general - in this case: programming - topics. In contrast a tutorial also describes basics for beginners and uses a more practical, explanatory approach to describe things, maybe even combined with the use of easier language. The FreeBasic manual contains both a technical/function reference and tutorials, however the former is more extensive and complete than the latter. fxm did contribute a lot of work to make the reference part of the manual as good as it currently is. Criticising him for not maintaining the programmer's guide / tutorials (at least not as well as the technical reference) is inappropriate and unfair IMHO. The programmer's guide is incomplete and marked as "work in progress" since ages. However, everyone is free to help maintaining that section of the manual. I guess many people would be happy if that work would be done by somebody with a passion and carefulness similar to fxm, but up to now I can't remember anybody wanting to do that. Unfortunately, because that is the part of the manual that is intended for beginners rather than the function reference. And that part would also be the place to describe user input from a programmer's (user's) point of view rather than from a technical point of view.

So if anybody wants to improve the current situation of the tutorials part of the manual feel free to do so. Just be aware that writing documentation/tutorials for beginners is not an easy task at all and usually requires expert knowledge. I'd suggest to discuss changes (except subtle ones) on the forums first as long as you're new to documentation or if you're planning bigger changes. A reason for is also the lack of a suitable review functionality in our wiki software and a rather limited modification history overview.

[Trinity]

I wasn't asking for help.

OK , then in that case please accept my apology for misunderstanding :-)

[MrSwiss]

To be honest, I didn't see the reason for having two separate category pages for user input functions at first either - and I wouldn't consider myself as beginner. However, when one knows the structure of the library reference it perfectly makes sense, as the runtime library and the graphics library are documented separately (as been explained by fxm).

That's exactly, what IMHO needs to be explained to beginners but, as part of the Manual,
call it "Introduction to using this Manual" (or similar), not anywhere else (it's a integral part of it).

Oh, btw: there are no confusions here (as you seem to think).

[St_W]

IMHO one person (fxm) only should tend to the FBWIKI.

I'm not totally sure whether you meant the same as I'm thinking, but I quite agree. Just to describe my thoughts a bit more in detail: IMHO there should be a single person (fxm) or small team managing the wiki. However, that does not mean that that is the only person providing content and updates for the wiki. That is just the person that reviews proposed changes and decides whether to accept or reject a proposed change. Just think of Linux Torvalds and the Linux kernel. Or dkl and FBC.
Ok, I agree that the last example is not the best one, but this is only because dkl also was the sole developer besides managing commits and pull requests for the FBC.

[St_W]

That's exactly, what IMHO needs to be explained to beginners but, as part of the Manual,
call it "Introduction to using this Manual" (or similar), not anywhere else (it's a integral part of it).

Explain what? The technical background information (existance of a runtime library and a graphics library, implemented as separate libraries) that is the reason for structuring the documentation as-is? I'm not sure whether it would be something that a beginner cares about ...
However, that doesn't mean that this shouldn't be documented - I just don't think that this is a topic suitable for beginners, who often have no idea about libraries at all.

Regarding the "Introduction to using this Manual" page: as far as I can see there already exists something like that, giving some basic guidance for using the manual:
Welcome to FreeBASIC
Getting help with FreeBASIC

Both pages point to the Programmer's Guide as a starting point for beginners. But I agree that the references are not placed very prominently. The unfinished state of the programmer's guide might be a reason for that.

btw, the the programmer's guide and the community tutorials are part of the FB manual just like the function reference. They just aren't placed as prominently on the TOC / start page as mentioned before, probably for the reason mentioned before. IIRC you also wrote somewhere in this thread that the community tutorials are old and at least to some part outdated. I guess if the content would be improved they could also be presented more prominently and thus get more attention by beginners and users of the manual in general.

[MrSwiss]

The technical background information (existance of a runtime library and a graphics library, implemented as separate libraries) that is the reason for structuring the documentation as-is? I'm not sure whether it would be something that a beginner cares about ...

As described further below (in this thread), a beginner is actually FORCED, to know those things,
to be able to understand the structure of the Manual (and therefore, the way to search for what's
of current interest and, actually finding it).

This is the real point, at issue ... (currently).

Rewriting Community Tutorials, as opposed to adding a additional page or two, to the Manual, are
IMHO, two different pairs of shoes.

[St_W]

As described further below (in this thread), a beginner is actually FORCED, to know those things,
to be able to understand the structure of the Manual (and therefore, the way to search for what's
of current interest and, actually finding it).
This is the real point, at issue ... (currently).

I agree on the issue, but I think the reason for that is the incomplete Programmer's Guide, because that should describe user input (among other topics) for beginners.

Anyway, I'd suggest to link to each other user input category page in a "see also" section like on this category page: https://freebasic.net/wiki/wikka.php?wakka=CatPgError The link title could e.g. say something like "User input functions (graphics library)".
Maybe also changing the title of the category pages to "User Input Functions (graphics library)" and "User Input Functions (runtime library)" might be a good idea, because of the duplicate title possibly causing confusion. I wouldn't add the "(graphics library)" suffix to other category pages with unique titles.

[MrSwiss]

Anyway, I'd suggest to link to each other user input category page in a "see also" section like on this category page: https://freebasic.net/wiki/wikka.php?wakka=CatPgError The link title could e.g. say something like "User input functions (graphics library)".
Maybe also changing the title of the category pages to "User Input Functions (graphics library)" and "User Input Functions (runtime library)" might be a good idea, because of the duplicate title possibly causing confusion. I wouldn't add the "(graphics library)" suffix to other category pages with unique titles.

Yes, agreed, definitely a improvement ...

[Trinity]

At this point I am not sure that I am fully able to understand and follow the discussion between different parties here in this topic (it gets a bit technical with the libraries that I do not know enough about) .
The only thing I can point at is the problems that I have had which forced me to seek assistance in the forum.
The greatest problem I think that I have had was to understand functions due to the for me mis-leading syntax description for all built-in functions that were meant to be used for over-loading compiler which I as a newbie had no chance at all to understand (and know) when reading it. (Which I think is the blue text that MrSwiss wrote about at some point in this topic.

Also I know that I think that the GFX_FULLSCREEN , #include "fbgfx.bi" , Using FB ' namespace , and the use of &h08 (no frame)(fbgfx.bi) all in connection with the use of Screen and ScreenRes has been something that others have had to try to learn me about (I still don't understand it all)
(I am not asking for more help here , merely suggesting that people could look into if they think that it is properly documented or if I have just not been good enough at using documentation. )

[St_W]

Rewriting Community Tutorials, as opposed to adding a additional page or two, to the Manual, are
IMHO, two different pairs of shoes.

I'm aware that updating the programmer's guide (or the community tutorials) is a lot of work, but that would be the clean solution IMHO. I don't really like hacky solutions that tamper with the existing function reference part of the manual. That is why I'm against turning the existing function reference into a tutorial-style documentation to some extent, making it inconsistent. However, that doesn't mean I'm disliking any changes. IMHO they just have to comply with the style of a/FB's function reference. Of course that style is also not really fixed, but open for discussion.

At this point I am not sure that I am fully able to understand and follow the discussion between different parties here in this topic (it gets a bit technical with the libraries that I do not know enough about) .
The only thing I can point at is the problems that I have had which forced me to seek assistance in the forum.
The greatest problem I think that I have had was to understand functions due to the for me mis-leading syntax description for all built-in functions that were meant to be used for over-loading compiler which I as a newbie had no chance at all to understand (and know) when reading it.

Sorry for getting a bit off-topic or too general. The problems you encountered seem to confirm that the function reference is not really suitable for beginners to start with. Have you ever stumbled across the "Programmer's Guide" section of the manual? especially the "Procedures Overview" and related pages about procedures? May be worth a look.

I'd be also interested how you used the FB manual. Did you read some "getting started" topic or similar? where did you start? did you search for something and how did you navigate (links/category pages/search/index/...)?

if I have just not been good enough at using documentation.

In such a case it's nearly always the documentation that should be improved, because you won't be the only one not finding something. That's why describing your experience and giving feedback is important for us to be able to improve it.

[Trinity]

Sorry for getting a bit off-topic or too general.

For me any discussion about improving the documentation is completely on topic here and even if technical quite alright with me.

I'd be also interested how you used the FB manual. Did you read some "getting started" topic or similar? where did you start? did you search for something and how did you navigate (links/category pages/search/index/...)?

To be honest then I am rather confused due to a big overload of my person.
What I can say is this :
I think that I started with FreeBASIC on September 16 , 2017 and since then I have used what time and energy that I could muster on learning about FreeBASIC either by reading about it , trying to program or participating in the forum.
I am sure that I have visited the "getting started" , I must have but I visited so many pages that I simply cannot tell how many and exactly which , the freebasic.net webmaster probably have a list of that ;-) I have studied so many pages , and also used the off-line documentation but that mostly because it has a search facility that actually works - for me the on-line search has not worked as expected.
I have navigated any way that looked useful on the online pages trying any link that looked useful , and visited e.g. the keywords list pages to help locate what functions I needed.
Generally I prefer the On-line documentation to the extend that I don't need to search for the stuff , because I can then have many pages open in browser which I can not in the help file.
Thank you for your interest in improving stuff for beginners :-)

That's why describing your experience and giving feedback is important for us to be able to improve it.

Thank you :-)

[MrSwiss]

I've just been over the doc again, and I think that I've found the *most important page, for beginners*.
No, it's NOT: ... "hello World" ;-)
The main problem seems to be, finding it, since it is *buried* in a rather difficult to find place:
too far down the ladder, so to speak.

It's called "FreeBASIC primer #1" (which explains the few, most common keywords, for beginners):
Enter in browser: https://www.freebasic.net/wiki/ (result: https://www.freebasic.net/wiki/wikka.php?wakka=FBWiki/)
click on: FreeBASIC Manual (result: https://www.freebasic.net/wiki/wikka.php?wakka=DocToc) = Main page on .chm
click on: Programmer's Manual (result: https://www.freebasic.net/wiki/wikka.ph ... Programmer)
finally, click on: FreeBASIC primer #1 (result: https://www.freebasic.net/wiki/wikka.ph ... oPgPrimer1)

This is IMHO far too deep down, to be easily found (especially, for a beginner)!

A solution proposal: insert in "FreeBASIC Manual" (below title: Tutorials, but above: Programmer's Manual) a
direct link called: FreeBASIC primer #1 (recommended first step, for beginners) or (FreeBASIC in a Nutshell).
(I'd personally prefer the "Nutshell", it appears to be, less presumptuous but, maybe also, less "clear" ?)

It won't help anybody, to have "the best intro", if it can't be found, by the people, needing it the most ...