Since?

Forum for discussion about the documentation project.
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Since?

Post by fxm »

fxm wrote:Indeed, the official version and therefore the reference for the moment is 1.08:
- It seems to me better that the differences due to the unofficial 1.09 version remain for the moment (up to the official release output of 1.09) where they are (in the sections Syntax, Usage, Parameters, Description).
- But, for the differences due to previous versions (versions < 1.08), let's try to put these differences in the Version section.
Presently, only 4 KeyPg* stay in this case:
- KeyPgExtendsZstring
- KeyPgExtendsWstring
- KeyPgOpProcptr
- KeyPgOpenCom
fxm wrote:After the official release output of 1.09, this 1.09 version will become the reference and therefore the differences of the 1.08 version with the 1.09 version will then be transferred to the Version section
IMHO, the purpose of the Version section is to identify deviations of past versions from the official version, not to also identify deviations of the future version from the official version.
The deviations of the future version from the official version are described by amending the text in the first sections describing the keyword.

Thus the user will have directly inserted in the description body of the keyword:
- for the wiki: the deviations induced by the upcoming official version of fbc,
- for the manual distributed with the official fbc update: the deviations of the new official version.
Less recent deviations will be summarized in the Version section.

Note
A particularization is for new keywords.
As the entire page of the new keyword can not be tagged with the upcoming fbc version number, the fbc version number is only placed in the Version section (anticipating the future state of the next official fbc revision).
Last edited by fxm on Oct 14, 2021 6:12, edited 3 times in total.
Reason: Update
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Since?

Post by fxm »

SARG wrote:I was just looking at some version sections and I guess a wrong copy/paste for typeof.
  • Version:
    Before fbc 1.08.0:
    Typeof was not returning the size of the data fields of a UDT.
Thanks.
Corrected.
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Since?

Post by fxm »

coderJeff wrote: - I am also in favor of only adding the sections for pages > 1.00.0 and reverting the CompilerOpt* pages <= 1.00.0
Done.
coderJeff
Site Admin
Posts: 4313
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Since?

Post by coderJeff »

fxm wrote:IMHO, the purpose of the Version section is to identify deviations of past versions from the official version, not to also identify deviations of the future version from the official version.
It is good of you to remind me of that. I almost always use the current development version for everything so I am at least one version ahead of everyone.
speedfixer
Posts: 606
Joined: Nov 28, 2012 1:27
Location: CA, USA moving to WA, USA
Contact:

Re: Since?

Post by speedfixer »

Maybe I am just simple.

The wiki is ALWAYS the next version, whatever that is. That is not listed in each keyword in the wiki. That is not expected or reasonable to ask.
A user is using a version, maybe or maybe not current, maybe or maybe not a daily, or any of the others suggested from the FB home site downloads.

WAY too much work to roll a suggestion of current or previous version through any/all the keywords. (Sure, someday, the cruft buildup can be cleaned after many versions roll through.)

"IMHO, the purpose of the Version section is to identify deviations of past versions from the official version, not to also identify deviations of the future version from the official version."

The official version is a moving target.
The current wiki, and the current development version (future version), is anticipated by the developer by labeling his current work, only applying it to that workspace in the repository.
That noted deviation from whatever version we are using to the current DEVELOPMENT version (which is the online wiki) IS WHAT IS NEEDED.

So, any new change must be noted going forward if the current development version MAY become the next 'official' version.

Is that what is expected to happen? Is my understanding correct?
I'm just trying to re-express what I think will happen, not criticize.

david
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Since?

Post by fxm »

I thought I was clear:
fxm wrote:Indeed, the official version and therefore the reference for the moment is 1.08:
- It seems to me better that the differences due to the unofficial 1.09 version remain for the moment (up to the official release output of 1.09) where they are (in the sections Syntax, Usage, Parameters, Description).
- But, for the differences due to previous versions (versions < 1.08), let's try to put these differences in the Version section.

After the official release output of 1.09, this 1.09 version will become the reference and therefore the differences of the 1.08 version with the 1.09 version will then be transferred to the Version section (but current changes put in the Syntax, Usage, Parameters, Description sections).
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Since?

Post by fxm »

@Jeff and the others,

I have a question when a deviation from the upcoming version is described in the 'Platform Differences' or 'Dialect Differences' or 'Differences from QB' sections: example of OPEN COM.
When this upcoming version will become official:
- this deviation should normally be transferred to the 'Version' section, but then this deviation would appear before the section where it applies,
- or it is better to leave the deviation in its initial '* Differences *' section in this particular case ?
Or it would have been better if the 'Version' section was rather placed almost at the end, just before the 'See also' section (it's not a problem for me to make this change) ?
coderJeff
Site Admin
Posts: 4313
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Since?

Post by coderJeff »

I think many users typically only use one platform & dialect. They will however use multiple versions, or at least upgrade from time to time. My opinion is that they will scan to the Version section before fully reading and consuming the other differences sections even if it's after the other differences section.

To build on something speedfixer is asking and If I had to do this all by myself, I would probably try to do in fewer steps. 1) Use the wiki to document current development as if it is about to be released at any moment. 2) Note important version differences in the Version section, 3) When a binary release is published the packaged documentation matches the binary release and no changes needed to move to the next development release.

fxm, you are doing nearly all the work, so you should feel free to use a policy that makes sense to you. And you may reserve the right to change your mind should find any reason to do so. :)
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Since?

Post by fxm »

1)
I think that when a difference between versions does not affect all platforms, you might as well leave this difference between versions in the 'Platform Differences' section.

2)
Regarding the differences due to the upcoming version, the additional step that I am currently applying allows users, who mostly only use the official version but on the other hand the wiki, to more easily identify in the description itself the recent changes which do not concern them yet (rather than going to see the 'Version' section every time systematically, or then believe in a bug).
Likewise, when the official version of the documentation is released, it is helpful if recent differences (due to this new version) in the use of keywords are highlighted in the descriptive text itself and not returned. in a section that represents for me the history but not the immediate one.

But if a majority emerges to skip this intermediate step, I am ready to do so, and not with regret (because it is not for me that I am doing it).
(today, this concerns only 3 keywords: KeyPgExtendsZstring, KeyPgExtendsWstring, KeyPgOpProcptr)
speedfixer
Posts: 606
Joined: Nov 28, 2012 1:27
Location: CA, USA moving to WA, USA
Contact:

Re: Since?

Post by speedfixer »

From the FreeBASIC home page, go to 'Downloads.'

On that page, three versions are in the repository:

1.08.1
1.08.0
1.07.3

The GREEN 'Download Latest Version' button is for 1.07.1

What is the 'official' version?
How does a person using that site supposed get any clue what the 'official' version might be?

david
adeyblue
Posts: 299
Joined: Nov 07, 2019 20:08

Re: Since?

Post by adeyblue »

The GREEN button points to 1.08.1, and has since July.
I think you should put labels on every glass thing in your house, you're clearly confused by them all and have put milk bottles in front of your eyes instead of your spectacles.
speedfixer
Posts: 606
Joined: Nov 28, 2012 1:27
Location: CA, USA moving to WA, USA
Contact:

Re: Since?

Post by speedfixer »

Yeah, I'm not seeing that.

A refreshed page I'm looking at right now still says 10.7.1

(Never pasted a pic before. Not simple, here.)

Where I am looking:
https://sourceforge.net/projects/fbc/files/

I don't doubt you see what you see. I'm just seeing something else.
I DO think maybe you should reserve insults for someone you know a little better.

david
SARG
Posts: 1755
Joined: May 27, 2005 7:15
Location: FRANCE

Re: Since?

Post by SARG »

Using the link you provided no problem : 1.08.
Cache issue ??

For pasting an image : upload it somewhere then put the link tagged with Img (use the button).

Image
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Since?

Post by fxm »

fxm wrote:Regarding the differences due to the upcoming version, the additional step that I am currently applying allows users, who mostly only use the official version but on the other hand the wiki, to more easily identify in the description itself the recent changes which do not concern them yet (rather than going to see the 'Version' section every time systematically, or then believe in a bug).
Likewise, when the official version of the documentation is released, it is helpful if recent differences (due to this new version) in the use of keywords are highlighted in the descriptive text itself and not returned. in a section that represents for me the history but not the immediate one.

But if a majority emerges to skip this intermediate step, I am ready to do so, and not with regret (because it is not for me that I am doing it).
(today, this concerns only 3 keywords: KeyPgExtendsZstring, KeyPgExtendsWstring, KeyPgOpProcptr)
As long as I do not have a certain number of user opinions on this subject, I will continue with this intermediate step for the behavior changes induced by the coming up (for the wiki) or last version (for the documentation file release).
dodicat
Posts: 7976
Joined: Jan 10, 2006 20:30
Location: Scotland

Re: Since?

Post by dodicat »

speedfixer wrote:Yeah, I'm not seeing that.

A refreshed page I'm looking at right now still says 10.7.1

(Never pasted a pic before. Not simple, here.)

Where I am looking:
https://sourceforge.net/projects/fbc/files/

I don't doubt you see what you see. I'm just seeing something else.
I DO think maybe you should reserve insults for someone you know a little better.

david
FreeBASIC 10.7.1 has not been done yet.
I can see FreeBASIC 1.08.1-winlibs-gcc-9.3.0.7z(33.3MB) in the green box, which I already have.
If I press get updates I get a box asking lots of questions.
Post Reply