ThinBASIC: User defined types micro-book

[Petr Schreiber]

Hi,

I am experimenting with gitHub pages and mdBook to explore possibilities for documenting thinBasic.

Please have a look at the following online micro-book, to learn about everything related to UDT on one place:
thinBasic: User defined types (https://thinbasic.github.io/book-thinbasic_user_defined_types)

The format of documentation is verbose, detailed, so maybe not so good for thinBASIC helpfile, which should serve as quick reference.

What you can try:
- changing theme via the brush icon
- real-time full text search
- PDF generation via the printer icon

All these goodies we get with MDBook for free :)

The source code of the book is available at gitHub (https://github.com/ThinBASIC/book-thinbasic_user_defined_types). It basically consists just of markdown files, which makes collaboration easier - no HTML struggle.


Petr

[matthew]

It looks very clean and readable.

I've just taken a look at the thinBasic online documentation, I think it would really benefit from being displayed in this format.

[kcvinu]

Yes, I agree with matthew. Its a good format for a help file. :)

[Petr Schreiber]

Hi,

thank you for the kind words :)

Having thinBasic: the book as a primary goal is too big task to grasp, however I plan to map further various parts of thinBasic with this form of micro-books.

There are some complex areas which are asking for it - for example UI module or complete view on TBGL.

Which others subparts of thinBASIC would you like to see documented this way?

Step by step, we might get to the complete guide to thinBasic one day :)


Petr

[primo]

Hi Petr
certainly this is a good way to display Ebooks. the characters is clear and Big (suitable for my impaired eyes) also hide and show table of contents is a feature.
is it possible to include pictures in these Docs or ebooks ?
i have downloaded book-thinbasic_user_defined_types-master and then executed cargo install mdbook , it is added here: C:\Users\george\.cargo\bin\mdbook.exe
after that executing cargo build from within the "book-thinbasic_user_defined_types-master" folder but i get
error: could not find `Cargo.toml` in `C:\tst\book-thinbasic_use...
there is no Cargo.toml file but book.toml

i suggest a primary docs such as variables and its type, strings functions, tricks with arrays.

[Petr Schreiber]

Hi Primo,

thanks a lot for your feedback, highly appreciated!

As for the build problems - mea culpa! The command should be:

mdbook build

...so no 'cargo'. I fixed the README.md accordingly.

Thanks a lot - without you I would not notice there is something wrong. :drink:


Petr

[ReneMiner]

Good start...

I hope this topic - udts - will be continued and completed. Not just that udts in tB can contain functions but also the special variable ME should be explained and the Functions ._Create() and ._Destroy() should be mentioned. Special behavior of those - means if an array of an udt gets created or destroyed "Me" will not apply to every single array-element.
Subelements can be anything: primitive variables or other udts, both can be just one single element or non-dynamic up to 3-dimensinal arrays or dynamic arrays.

Also should be mentioned that a Type can be extended by another Type, that means the Type that extends a base-Type has all properties and functions of its base-Type, but if the extending type has functions with same function-names as its base-Type then the functions of the extending type will be used by the interpreter.


Also ability of having static udt-subelements should be mentioned, static subelements contain the same value in all dimensioned variables of the udt...


BTW.
Long time I wish the possibiliy to assign values to static subelements within Type-definition, did something happen here?
Example


Type tFont
' assign Value to Static members instantly:
Static Regular As Long Value 0
Static Italics As Long Value 1
Static Bold As Long Value 2
' is it possible now?
Flags As Long
' ...
End Type

Dim myFont As tFont
myFont.Flags = myFont.Bold Or myFont.Italics

[Petr Schreiber]

Hi Rene,

STATIC elements are already mentioned elements (https://thinbasic.github.io/book-thinbasic_user_defined_types/chapter_01-01-elements.html#static-elements) chapter, EXTENDing UDT is already mentioned in extension (https://thinbasic.github.io/book-thinbasic_user_defined_types/chapter_01-03-01-extension.html) and inclusion (https://thinbasic.github.io/book-thinbasic_user_defined_types/chapter_01-03-02-inclusion.html).

Thank to Eros I realised there was a mistake in documentation of UDT functions outside UDT block (https://thinbasic.github.io/book-thinbasic_user_defined_types/chapter_01-04-02-udt-function.html#user-defined-function-outside-type-definition), now fixed.

Also - basically all the other things you mention (ME, _create, _destroy (https://thinbasic.github.io/book-thinbasic_user_defined_types/chapter_01-04-02-udt-function.html)) are already documented. Maybe you missed there are other chapters?

If you are viewing page on mobile, just click the menu icon in the upper left corner - it will reveal all the chapters!

Which leads me to another advantage of mdbook, as it adapts for portable devices automagically :)
For suggestions regarding new UDT functions, please use new thread - this one is used for feedback on the UDT micro book itself. Thanks for undestanding :)


Petr

[ReneMiner]

There should be a possibility for authors of microbooks as this one to link these at least in thinBasic-online-help. Better of course if there were a way to find useful links as this also in the with tB shipped offline-help.
As far as I know does Petr have admin-access, maybe he can approve and place the links...?
It would take a lot of burden from Eros' shoulders I guess and tB-users can find more additional information, examples etc. since there's not always someone online who can answer their questions instantly.

I know that if I need some information I want it right away to continue coding...

[ReneMiner]

And some more information that should be added to the book itself:

Subelements of an UDT can be Public as well as Private .
Public means, the subelement can be accessed from anywhere of the project as long the UDT is dimensioned while Private means the subelement of the UDT is only accessible within functions of its Type.
Where to be aware of the keywords Public and Private are switches.
Means all subelements that are before any of the both keywords are Public by default.
As soon as Private or Public are specified everything that follows will be Private or Public until the other keyword follows.
Example:


Type tExample
' every Subelement here is Public by default
X as Single ' public scope
Y as Single ' public too

Private ' works as switch
X_last As Single
Y_last As Single ' both are Private here


Public
' anything that follows here
' will be Public
End Type

[DirectuX]

Subelements of an UDT can be Public as well as Private .
Public means, the subelement can be accessed from anywhere of the project as long the UDT is dimensioned while Private means the subelement of the UDT is only accessible within functions of its Type.

unless I'm mistaken, from this example, public or private had no effect when I tested it, it's how the udt is dimensioned that rules. "LOCAL myVar as tExample" or "GLOBAL myVar as tExample"

[Petr Schreiber]

Hi DirectuX,

you are right, there are currently reserved, but they do not have any effect yet.


Petr

[Petr Schreiber]

The ebook has been updated significantly and is immediately available:
https://thinbasic.github.io/book-thinbasic_user_defined_types/

What is new?
- new chapter on interfacing UDT with 3rd party languages
- new chapter listing known issues (https://thinbasic.github.io/book-thinbasic_user_defined_types/appendix-list-of-known-issues.html), to save you headache
- improved structure & up to date information

...I also added bug reports for all issues I am aware of.


Petr

[DirectuX]

Hi,
while this is super nice (thanks again Petr!) to have an up to date list of known problems with UDTs (https://thinbasic.github.io/book-thinbasic_user_defined_types/appendix-list-of-known-issues.html), I wonder why this was required. What about being able to display all known problems matching a given project/version ?

Eros , Petr , what is your position towards the under-exploitation of the Projects Support form (https://www.thinbasic.com/community/projectsearch.php?do=search) ?

[Petr Schreiber]

Hi Sebastian,

all the issues mentioned in the book are reported as issues in the Bug tracking/Project support.

I just wanted to provide view (via book chapter) to make them more visible.

I can imagine structuring the Project Support more could help the visibility.


Petr

[DirectuX]

I can imagine structuring the Project Support more could help the visibility.

This is more the sense of my post : on one hand we have thinBasic 1.11.1.0 BETA with latest known features and fixes, and on the other hand we have a bug tracking page where you can't filter issues relevant to this specific 'package'. Should this be effective, you could just have put in the book a link to the search result. Sort of 'one place' to see informations. More, at first it would even possibly not have been necessary. Do you agree ? :)

[Petr Schreiber]

I do :)

I will consult it with Eros.

Thank you,
Petr