Since?

[TJF]

What about adding a further headline to each of the keyword pages in the documentation named

Since

where the reader gets informed when (at which version) the related keyword got implemented in the compiler?

[fxm]

Present principle:

I set myself this rule on the wiki (which could be re-discussed in the Documentation Forum):
- The documentation on wiki is updated daily if possible (after each change without waiting for the release of a new fbc version) so that users of the current (unofficial) version have reference documentation.
- For already existing keywords, any recent behavior change is reported in the description with the fbc version number for which it will be or was recently applied.
- For new keywords, nothing is reported because it is obvious to realize that the fbc version that one is using does not support them.

On the other hand, with each official fbc version release, a matching downloadable documentation is associated with it (from the wiki version sampled at this time).

[TJF]

- For new keywords, nothing is reported because it is obvious to realize that the fbc version that one is using does not support them.

Why is that obvious? A user may use an old compiler and read the up-to-date docs online.

I got positive feedback from users about that 'Since' info in my documentations; they know when they need an update to get a certain feature.

BTW: \since is a standard keyword in the Doxygen documentation tool.

[fxm]

- For new keywords, nothing is reported because it is obvious to realize that the fbc version that one is using does not support them.

Why is that obvious?

When user compiles, the compilation error message is quite clear.

Otherwise, it's a big job updating all the keywords with their creation history.
In this case, it would also be necessary to indicate the history of modification of their behavior.

[TJF]

When user compiles, the compilation error message is quite clear.

An old compiler doesn't inform when a new feature gets implemented.

In this case, it would also be necessary to indicate the history of modification of their behavior.

This indded may be an issue. From my point of view it's sufficient to just add Since < 1.09 to the existing keyword pages, but be precise for further ones.

Please consider that I maintain megabytes of C header file translations, and often it's useful to know from which version on a certain feature is available in fbc, ie to handle bad translations like in https://github.com/DTJF/gir_headers/blo ... ros-2.0.bi lines 468 to 470 (an issue related to the underscore macro problem).

[speedfixer]

There are at least three versions 'working': 1.09, 1.08. 1.07.
Like me, many, many have not yet moved beyond 1.07 in production.

Intentional or not, many are using earlier versions as evidenced by the questions in the forums.

The numbers of new keywords and differences in function/operation of just those three 'new' versions create both confusion AND interest in possible new features. Should someone have to load FB 3 times to find the feature he is looking for? Or escape problems as a result of the newer changes?

If development were to take a long pause for some reason, would a new user just assume that something is broken/abandoned?
Or that FB is not complete or unfixable?

Or like so many other promising projects, docs are just poor?

The version numbers imply relatively minor changes to a project; though as feature changes, some are nearly game changing.
Not including WHEN a feature appeared is a communication breakdown, in my opinion.

david

[fxm]

Each official release of fbc contains a matching official release of the documentation:
- For example, the user who uses release 1.07.0 of fbc can also use the manual FB-1.07.0.
- For the current (unofficial) fbc version, the user can use the wiki which is updated daily.

In addition, a 'changelog.txt' file, updated with each release, traces the history of all changes (release by release) since the origin of fbc.

[coderJeff]

fxm, I hear what you are saying. It's mostly just you and me now.
Already you provide detailed reports on bugs and compiler issues. I update comments in the compiler source, write the change log, the TODO, and pull requests. We discuss changes together on the forums and the documentation. Then, you get all the documentation updated almost immediately. I like working with you and I am thankful. I certainly wouldn't want to ask you to do more and jeopardize that.

My opinion is I don't want to see a detailed change log of every little difference and bug fix. The primary focus of the current documentation should be to document the current compiler.

Let me investigate a little and see if I can do some part:
- add {{fbdoc item="version"}} action to the wiki
- update fbdoc generator to recognize it
- refresh my old project FreeBASIC Dialect / Version Comparison
- build a list of initial "Since fbc x.xx.x" entries for each page
- write a script to inject the new section to all KeyPg*

[caseih]

There are at least three versions 'working': 1.09, 1.08. 1.07.
Like me, many, many have not yet moved beyond 1.07 in production.

Why? Surely 1.09 is the version you should be on (or whatever is the latest stable... haven't looked in a while I admit). It's fully backwards compatible with 1.07, and has bug fixes, both in the compiler, and the current on-line documentation. If you're using 1.07 and want to use the on-line wiki, you're possibly missing a couple of bug fixes and features.

Should someone have to load FB 3 times to find the feature he is looking for?

Of course not. Just install the latest version. Sometimes there are regressions, unfortunately. But generally speaking, FB goes forward, albeit very slowly. Bear in mind that FB is maintained and developed by just a couple of talented volunteers. I don't know why you'd want to go back through old versions looking for a feature.

[fxm]

Let me investigate a little and see if I can do some part:
- add {{fbdoc item="version"}} action to the wiki
- update fbdoc generator to recognize it
- refresh my old project FreeBASIC Dialect / Version Comparison
- build a list of initial "Since fbc x.xx.x" entries for each page
- write a script to inject the new section to all KeyPg*

Indeed, there are currently 621 keywords for which you have to search the creation history and insert on the corresponding page a new first section such as (imho):

INSTR
Locates the first occurrence of a substring or character within a string

Version:

• Since fbc x.yy.z

Syntax:

• .....

.....

Very tedious to do all this manually !

[TJF]

Indeed, there are currently 621 keywords for which you have to search the creation history and insert on the corresponding page a new first section such as (imho):

INSTR
Locates the first occurrence of a substring or character within a string

Version:

• Since fbc x.yy.z

Syntax:

• .....

.....

Very tedious to do all this manually !

Users can help, once the principe is fixed. Manually just the 'list of initial "Since fbc x.xx.x" entries for each' keyword (not page) needs to be generated. The code injection can get automated.

I wouldn't place it that high on the page. Better place it at the lower end after Example and before Platform Differences or Differences from QB.

The 'FreeBASIC Dialect / Version Comparison' is a good idea (haven't it seen before), but more on the nice-to-have side.

[speedfixer]

I would never suggest that anyone should go back to document *all* the keywords. Only some of the more recently modified or new one since, say, 1.01. It may not seems so to others, but I feel that there have been many improvements and changes behind the scenes that make FB stronger and more capable.

However, there are some few of the old ones that have had, or will have, changes to how they may be used.
Strings are a good example and one of FB major strong points as a modern compiled, fast language.

Everyone is always looking for string 'tricks' and the improvements are an effort to provide more horsepower in using them. Terrific.
Simple use has not changed. But, if I had a major app and my own string libs, I would be a little worried to spend the effort to use those new features if I found they were only available in the latest version.

I read the conversations at the forums and am well aware of the changes that are making their way into FB.

From the homepage 'Get FeeBASIC' button, you are presented with three versions, none of which are 1.09.

Who says I should only be using 1.09?

david

[coderJeff]

Having "Since 1.00.0" would cover most pages. Tracing history back to version 0.14.0 probably not too useful. But here it is anyway. Does not mean was bug free, or on all targets, etc, just indicates the earliest appearance. Or more acurately, the first version on which the test case I've written compiles/links/executes.

COMPILER OPTIONS
Since fbc 1.09.0: -entry
Since fbc 1.07.0: -earray, -eassert, -edebug, -edebuginfo, -elocation, -enullptr, -nostrip, -strip
Since fbc 1.06.0: -noobjinfo
Since fbc 1.02.0: -showincludes
Since fbc 1.00.0: -pic
Since fbc 0.90.1: -asm, -print, -rr, -RR
Since fbc 0.24.0: -prefix, -static
Since fbc 0.21.1: -forcelang, -fpmode, -O, -pp, -vec, -Wc
Since fbc 0.20.0: -C, -fpu, -R, -z
Since fbc 0.17.0: -gen, -lang, -Wa, -Wl
Since fbc 0.16.0: -include, -maxerr
Since fbc 0.14.0: -a, -arch, -b, -c, -d, -dll, -dylib, -e, -ex, -export, -exx, -g, -i, -l, -lib, -m, -map, -mt, -nodeflibs, -noerrline, -o, @file, -p, -profile, -r, -s, -t, -target, -v, -version, -w, -x

KEYWORDS
Since fbc 1.09.0: __FB_OPTIMIZE__, __FB_PPC__, #CMDLINE, #PRAGMA RESERVE

Since fbc 1.08.0: __FB_ARG_COUNT__, __FB_ARG_EXTRACT__, __FB_ARG_LEFTOF__, __FB_ARG_RIGHTOF__, __FB_EVAL__, __FB_JOIN__, __FB_QUOTE__, __FB_UNIQUEID__, __FB_UNIQUEID_POP__, __FB_UNIQUEID_PUSH__, __FB_UNQUOTE__, __FB_X86__, FBARRAY (descriptor), FB_MEMMOVE, FILEFLUSH, FILESETEOF, __Thiscall, THREADSELF

Since fbc 1.07.1: __FB_BUILD_DATE_ISO__, __FB_BUILD_SHA1__

Since fbc 1.07.0: CVA_ARG, CVA_COPY, CVA_END, CVA_LIST, CVA_START, EXTENDS WSTRING, EXTENDS ZSTRING

Since fbc 1.06.0: ALIAS (Modifier), __FB_GUI__

Since fbc 1.04.0: BOOLEAN, BYREF (Variable), CBOOL, FALSE, TRUE

Since fbc 1.02.0: __FB_ASM__

Since fbc 1.00.0: __FB_64BIT__, __FB_ARM__, ISREDIRECTED, ENVIRON Statement, THREADDETACH

Since fbc 0.90.1: ABSTRACT, BYREF (Function), OVERRIDE, #ASSERT, VIRTUAL

Since fbc 0.24.0: BASE (Member Access), BASE (Initializer), __DATE_ISO__, __FB_DARWIN__, __FB_FREEBSD__, __FB_NETBSD__, __FB_OPENBSD__, EXTENDS, OBJECT, IS (Operator), THREADCALL

Since fbc 0.22.0: __FB_BACKEND__

Since fbc 0.21.1: __FB_FPMODE__, __FB_FPU__, __FB_GCC__, __FB_VECTORIZE__, NAKED

Since fbc 0.20.0: __FB_OPTION_GOSUB__, __FB_SSE__, IMAGEINFO, $LANG, ANDALSO (Short Circuit Conjunction), ORELSE (Short Circuit Inclusive Disjunction), OPTION(), OPTION GOSUB, OPTION NOGOSUB, #LANG

Since fbc 0.18.4: INSTRREV, NEW[], NEW[] (Placement), NEW (Placement)

Since fbc 0.18.3: CONST (Member), CONST Qualifier, STICK, STRIG Function

Since fbc 0.18.2: LET() Operator

Since fbc 0.17.0: CALL, CONSTRUCTOR, CULNG, __FB_BUILD_DATE__, __FB_LANG__, __FB_MIN_VERSION__, __FILE_NQ__, __FUNCTION_NQ__, __PATH__, DESTRUCTOR, END OPERATOR, END PROPERTY, END DESTRUCTOR, END CONSTRUCTOR, EVENT, EXIT CONSTRUCTOR, EXIT PROPERTY, EXIT OPERATOR, EXIT DESTRUCTOR, FRAC, ISDATE, LOCAL, FUNCTION (Member), SUB (Member), CAST (Operator), &= (Concatenate and Assign), ^= (Exponentiate and Assign), DELETE[], DELETE (Statement), DELETE (Operator Overload), " à, OPERATOR, FOR (Operator), LET Operator, NEW (Expression), NEW (Operator Overload), NEXT (Operator), ! (Escaped String), STEP (Operator), #ENDMACRO, #MACRO, ONCE (Pragma), #PRAGMA, PROPERTY, SCREENCONTROL, SCREENEVENT, SCREENGLPROC, STATIC (Member), THIS, TYPEOF, ULONG, VAR, (Access Control), (Access Control), (Access Control)

Since fbc 0.16.1: ADD (Put Graphics), CUSTOM (Put Graphics), __FB_DEBUG__, __FB_ERR__, FILEATTR, FILECOPY, FILEDATETIME, FILEEXISTS, FILELEN, ONCE (Include), #LINE

Since fbc 0.16.0: ANY (Initializer), __FB_ARGC__, __FB_ARGV__, __FB_OPTION_BYVAL__, __FB_OPTION_DYNAMIC__, __FB_OPTION_ESCAPE__, __FB_OPTION_EXPLICIT__, __FB_OPTION_PRIVATE__, __FB_OUT_DLL__, __FB_OUT_EXE__, __FB_OUT_LIB__, __FB_OUT_OBJ__, DIR, DRAW STRING, END NAMESPACE, ERFN, ERMN, EXIT SELECT, EXTERN (Block), IMAGECONVERTROW, NAMESPACE, $ (Non-Escaped String), TYPE (Temporary), USING (Namespaces)

Since fbc 0.15.0: CAST, CONDWAIT, DATEADD, DATEDIFF, DATEPART, DATESERIAL, DATEVALUE, DAY, __FB_CYGWIN__, __FB_MAIN__, __FB_MT__, ENCODING, END SCOPE, FORMAT, HOUR, LPOS, LPRINT, LPRINT USING, MINUTE, MONTH, MONTHNAME, NOW, & (String concatenation with conversion), COM Keyword, OPEN COM, CONS, OPEN CONS, OPEN ERR, OPEN LPT, LPT, OPEN PIPE, PIPE, OPEN SCRN, SCRN, POS, SCOPE, SECOND, TIMESERIAL, TIMEVALUE, VALLNG, VALUINT, VALULNG, WBIN, WCHR, WEEKDAY, WEEKDAYNAME, WHEX, WINPUT, WOCT, WSPACE, WSTR, WSTRING (Data Type), WSTRING (Function), YEAR

Since fbc 0.14.0: OPTION, ABS, ACCESS, ACOS, ALIAS, ALLOCATE, ALPHA (Put Graphics), AND (Put Graphics), ANY POINTER, ANY (Parameter Type), APPEND, AS, ASC, ASIN, ASM, ASSERT, ASSERTWARN, ATAN2, ATN, BEEP, BIN, BINARY, BIT, BITRESET, BITSET, BLOAD, BSAVE, BYREF (Parameter), BYTE, BYVAL, CALLOCATE, CASE ELSE, CASE, CBYTE, CDBL, CDECL, CHAIN, CHDIR, CHR$, CINT, CIRCLE, CLEAR (memory), CLNG, CLNGINT, CLOSE, CLS (Graphics), CLS (Text), COLOR (Graphics), COLOR (Text), COMMAND$, COMMON, CONDBROADCAST, CONDCREATE, CONDDESTROY, CONDSIGNAL, CONST, CONTINUE, COS, CPTR, CSHORT, CSIGN, CSNG, CSRLIN, CUBYTE, CUINT, CULNGINT, CUNSG, CURDIR, CUSHORT, CVD, CVI, CVL, CVLONGINT, CVS, CVSHORT, DATA, DATE$ Function, __DATE__, __FB_BIGENDIAN__, __FB_DOS__, __FB_LINUX__, __FB_PCOS__, __FB_SIGNATURE__, __FB_UNIX__, __FB_VER_MAJOR__, __FB_VER_MINOR__, __FB_VER_PATCH__, __FB_VERSION__, __FB_WIN32__, __FB_XBOX__, __FILE__, __FUNCTION__, __LINE__, __TIME__, DEALLOCATE, DECLARE, DEFBYTE, DEFDBL, DEFINED, DEFINT, DEFLNG, DEFLONGINT, DEFSHORT, DEFSNG, DEFSTR, DEFUBYTE, DEFUINT, DEFULONGINT, DEFUSHORT, DIM, DO, DO...LOOP, DOUBLE, DRAW, DYLIBFREE, DYLIBLOAD, DYLIBSYMBOL, ELSE, ELSEIF, END Statement, END FUNCTION, END ENUM, END SUB, END WITH, END IF, ENUM, ENVIRON$ Function, EOF, ERASE, ERL, ERR, ERROR, EXEC, EXEPATH, EXIT FUNCTION, EXIT WHILE, EXIT DO, EXIT FOR, EXIT Statement, EXIT SUB, EXP, EXPORT, EXTERN, FB_MEMCOPY, FB_MEMCOPYCLEAR, FIELD (Member Alignment), FIX, FLIP, FOR Statement, FOR...NEXT, FRE, FREEFILE, FUNCTION = ReturnValue, FUNCTION, FUNCTION PTR, GET (File I/O), GET (Graphics), GETJOYSTICK, GETKEY, GETMOUSE, GOSUB (Procedure Level), GOSUB (Module Level), GOTO, HEX$, HIBYTE, HIWORD, IF...THEN, IF...THEN...ELSE, IF, IIF, IMAGECREATE, IMAGEDESTROY, IMPORT, #INCLIB, #INCLUDE, INKEY$, INP, INPUT Statement, INPUT (File mode), INPUT$, INPUT #, INSTR, INT, INTEGER, IS, KILL, LBOUND, LCASE$, LEFT$, LEN, LET Statement, LIB, LINE (Graphics), LINE INPUT, LINE INPUT #, LOBYTE, LOC, LOCATE, LOCK, LOF, LOG, LONG, LONGINT, LOOP, LOWORD, LSET, LTRIM$, $DYNAMIC, $INCLUDE, $STATIC, MID$ Function, MID$ Statement, MKD$, MKDIR, MKI$, MKL$, MKLONGINT, MKS$, MKSHORT, CONSTRUCTOR (Module), DESTRUCTOR (Module), MULTIKEY, MUTEXCREATE, MUTEXDESTROY, MUTEXLOCK, MUTEXUNLOCK, NAME, NEXT, OCT$, OFFSETOF, ON ERROR, ON...GOSUB (Module Level), ON...GOSUB (Procedure Level), ON...GOTO, + (Add), AND (Conjunction), () (Array index), = (Assignment), @ (Address of), += (Add and Assign), AND= (Conjunction and Assign), /= (Divide and Assign), EQV= (Equivalence and Assign), IMP= (Implication and Assign), \= (Integer Divide and Assign), MOD= (Modulus and Assign), *= (Multiply and Assign), OR= (Inclusive Disjunction and Assign), SHL= (Shift Left and Assign), SHR= (Shift Right and Assign), -= (Subtract and Assign), XOR= (Exclusive Disjunction and Assign), + (String concatenation), / (Divide), OPEN (File I/O), = (Equal), EQV (Equivalence), ^ (Exponentiate), > (Greater than), >= (Greater than or equal), IMP (Implication), \ (Integer divide), < (Less than), <= (Less than or equal), . (Member access), MOD (Modulus), * (Multiply), - (Negate), NOT (Complement), <> (Not equal), OR (Inclusive Disjunction), ## (Argument concatenation), # (Argument stringize), PROCPTR (Procedure pointer), [] (Pointer index), -> (Pointer to member access), SHL (Shift left), SHR (Shift right), [] (String index), STRPTR (String pointer), - (Subtract), OPTION BASE, BASE (Options), OPTION BYVAL, OPTION DYNAMIC, DYNAMIC, OPTION ESCAPE, ESCAPE, EXPLICIT, OPTION EXPLICIT, OPTION NOKEYWORD, NOKEYWORD, OPTION PRIVATE, OPTION STATIC, PRIVATE (Option), STATIC (Option), * (Value of), VARPTR (Variable pointer), VARPTR$, XOR (Exclusive Disjunction), OR (Put Graphics), OUT, OUTPUT, OVERLOAD, PAINT, PALETTE, PASCAL, PCOPY, PEEK, PMAP, POINT, POINTCOORD, POKE, #DEFINE, #ELSE, #ELSEIF, #ENDIF, #ERROR, #IF, #IFDEF, #IFNDEF, #LIBPATH, #PRINT, #UNDEF, PRESERVE, PRESET, PRINT, PRINT #, PRINT USING, USING, PRIVATE (Procedure), PSET, PSET (Put Graphics), POINTER, PTR, PUBLIC, PUT (File I/O), PUT (Graphics), RANDOM, RANDOMIZE, READ, READ (file access), READWRITE (file access), REALLOCATE, REDIM, REM, RESET, RESTORE, RESUME, RESUME NEXT, RETURN (from GOSUB, module level), RETURN (from GOSUB, procedure level), RETURN (from procedure), RETURN (Gosub), RGB, RGBA, RIGHT$, RMDIR, RND, RSET, RTRIM$, RUN, SADD, SCREEN (Console), SCREENCOPY, SCREEN Function, SCREEN (Graphics), SCREEN Statement, SCREENINFO, SCREENLIST, SCREENLOCK, SCREENPTR, SCREENRES, SCREENSET, SCREENSYNC, SCREENUNLOCK, SEEK Function, SEEK Statement, SELECT CASE, SELECT, SETDATE, SETENVIRON, SETMOUSE, SETTIME, SGN, SHARED, SHELL, SHORT, SIN, SINGLE, SIZEOF, SLEEP, SPACE$, SPC, SQR, STATIC (Storage), STDCALL, STEP, STOP, STR$, STRING (Data Type), STRING$ Function, SUB, SUB PTR, SWAP, SYSTEM, TAB, TAN, THEN, THREADCREATE, THREADWAIT, TIME$ Function, TIMER Function, TO, TRANS (Put Graphics), TRIM, TYPE, TYPE (Alias), UBOUND, UBYTE, UCASE$, UINTEGER, ULONGINT, UNION, UNLOCK, UNSIGNED, UNTIL, USHORT, VA_ARG, VA_FIRST, VAL, VALINT, VA_NEXT, VIEW (Graphics), VIEW PRINT, WAIT, WEND, WHILE, WHILE...WEND, WIDTH, WINDOW, WINDOWTITLE, WITH, WRITE (Screen I/O), WRITE (file access), WRITE (File I/O), XOR (Put Graphics), ZSTRING

[fxm]

Great job !

How do we proceed for the rest ?
If we limit to fbc >= 1.00.0, there are only a little over 40 keywords to enter.
So we could do it manually, but only after creating a new 'item="ver"' (for 'Version:' paragraph) and deciding where to place it on the keyword page.

[coderJeff]

How do we proceed for the rest ?
If we limit to fbc >= 1.00.0, there are only a little over 40 keywords to enter.

I will try to write a script to insert the new section automatically to all pages. It's been a while since I made new fbdoc tools, but I think I can still do it.
Less the boiler-plate code it's something like this:

Code: Select all

	var sPage = "KeyPgDdfboptimize"

	var wiki = new CWiki
	var sBodyIn = ReadTextFile( sPage & ".wakka" )
	wiki->Parse( sPage, sBodyIn )

	'' TODO: wakka modifying script
	'' - search for insertion point
	'' - insert wakka tokens
	
	var sBodyOut = wiki->Build()
	WriteTextFile( sPage & ".wakka", sBodyOut )

Then I use other fbdoc tools to post my local changes back up to the public wiki.

So we could do it manually, but only after creating a new 'item="ver"' (for 'Version:' paragraph)

I'll try to add the 'ver' item today. There are a few live changes on www.freebasic.net/wiki that are not yet in the github repo. I'd like to synchronize those from the server in to the repository before I add in the new 'ver' item.

and deciding where to place it on the keyword page.

I like TJF's suggestion of after the examples but before qb, dialect, platform differences, and see also sections.