issue-#35 Add docu for DevSelectors

Bernhard
Posts: 68
Joined: Tue Sep 17, 2013 6:56 am
Location: Munich, Germany

issue-#35 Add docu for DevSelectors

Post by Bernhard »

Ivan Denisov wrote:
Josef Templ wrote:What is DevSelectors?
I have never used it.
Useful feature for testing and cross-platform development. Used rare at final stages.
In our case it is an example of text in-line controls which are drawn without fonts.

http://oberoncore.ru/wiki/blackbox/devselectors
oops that looks like the Oberon-V4 Version elements, which I liked and for which I have abused labeled folds. Very interesting.

Maybe we should add/create documentation for it (instead of: "This module has a private interface, it is only used internally.").

But this would be a new feature request, correct? And it should be moved to a new Topic, or?

--
Bernhard
Ivan Denisov
Posts: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#35 Improve documentation

Post by Ivan Denisov »

There are also the documentation for the Kernel and the ObxCtrls demo is placed after the sources, that can be moved to documentation also.
User avatar
Josef Templ
Posts: 2047
Joined: Tue Sep 17, 2013 6:50 am

Re: issue-#35 Improve documentation

Post by Josef Templ »

there is no issue-#35 in redmine so there must not be an issue-#35 in the forum.
Why? Because the numbering is done in redmine!!
So please create an issue-#35 in redmine as long as it is available, i.e. it is not taken
for another issue. There is no way to influence the numbering in redmine.
redmine is the root for our issue numbers.

And please don't call it "Improve documentation" if you actually mean "add docu for DevSelectors".
I am fine with adding docu to DevSelectors if anybody does it.
However, Ivan may complain about bad programming style because this is really used for
conditional compilation very much like the 'hated' ifdef in C.

- Josef
Ivan Denisov
Posts: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#35 Add docu for DevSelectors, Kernel and ObxCtrls

Post by Ivan Denisov »

I have added. I have made the Bernhard responsible for this feature, hoping that he does not against this. I have worse English, preparing the documentation requiring better English.

Josef Templ wrote:However, Ivan may complain about bad programming style because this is really used for
conditional compilation very much like the 'hated' ifdef in C.
Yes, I will complain :) because this is negative side of this feature and it should be reported for the full picture before voting. Also Selectors is incompatible with OdcToText converters and the code with them should not occur in repository.
User avatar
Josef Templ
Posts: 2047
Joined: Tue Sep 17, 2013 6:50 am

Re: issue-#35 Add docu for DevSelectors, Kernel and ObxCtrls

Post by Josef Templ »

There are many more undocumented modules in BB1.6.
The random combination of just 3 of them does not give any sense.
Please restrict to DevSelectors in this issue.
Documenting Kernel is a huge task and we will never come to
a release if we engage in such issues now.

It should also be noted that the undocumented modules are undocumented
intentionally. They are internal and can be changed any time.
An old idea was to write up some memos on interesting aspects of undocumented modules
and put them on our wiki. I find this approach much better then
including it in the standard distribution because then it is clearly visible
what is internal and what is published officially.
It would also be much faster because it does not need to go through our
voting process.

I would strongly suggest to concentrate first on the CPC 1.7 changes list,
which is far from resolved by now.

- Josef
Ivan Denisov
Posts: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#35 Add docu for DevSelectors, Kernel and ObxCtrls

Post by Ivan Denisov »

I think, that this is not easy choice. From one point of view, you are right, however we should document as mush as we can. This is very important from tactical point of view. Because today there is lack of people with deep understanding of BlackBox. If we will not change this soon, the project will be predetermined do die. We can mark out the intentions at the beginning of the documentation file. I chose this three modules, because it is clear what to do with them. We have good documentation in Russian for DevSelectors and Kernel, that can be translated. And ObxCtrls requiring minimal changes.

According CPC version, the process is not fast. I do not agree, that we need fast copy from there without discussion. I respect Helmut work on collecting all this fixes. As you can see I am started to copy from StdFolders, then you split my code for two issues and after some discussion better solution comes without Wine detection at all. That is how the Center is working today.
Ivan Denisov
Posts: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#35 Add docu for DevSelectors

Post by Ivan Denisov »

A lot of time has passed...

So, restricting on DevSelectors ?

Bernhard, what do you think? Will you prepare DevSelectors documentation first?
User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: issue-#35 Add docu for DevSelectors

Post by Robert »

I once used DevSelectors about 15 years ago, and remember thinking they could be useful. However I never used them again!

After the previous post I thought I would offer to draft a Docu file.

However when I started I could not remember how to use them, and despite some experiments could not work out what use they are.

If someone can give me some brief clues to refresh my memory I offer to expand it out into a larger document in the usual style.
Regards - Robert
User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: issue-#35 Add docu for DevSelectors

Post by Robert »

I have had another look at the OberonCore description, and suddenly it now makes some sense to me.

I will have a go at writing a draft of a Docu file.

Don't expect anything for a few days at least.
cfbsoftware
Posts: 204
Joined: Wed Sep 18, 2013 10:06 pm
Contact:

Re: issue-#35 Add docu for DevSelectors

Post by cfbsoftware »

A Google translation of the OberonCore documentation is:

Description

Selectors - Special display, placed in the text. They allow you to enter into text documents (including source code) different options:
selector = "[" name {"|" variant} "]".

There »[», «|» and "]" refer to the left, middle and right selectors respectively.

Selectors allow you to easily switch between options: click on «|» to the desired option, and the rest are hiding, and once all the selectors with the same name. Clicking on the "[" and "]" reveals the selector showing all options.

Note (if you want to keep the option after the change), the transactions with the selectors do not document modified ("dirty").

To insert the text of the selectors can use the following menu commands:
"Insert left" "* F5" "DevSelectors.DepositLeft; StdCmds.PasteView" "StdCmds.PasteViewGuard"
"Insert the middle" "* F6" "DevSelectors.DepositMiddle; StdCmds.PasteView" "StdCmds.PasteViewGuard"

Selectors in the source code

Selectors may be useful in the following cases:

◾ the intermediate stages of development when there is a desire to experiment with different options;
◾ to insert comments in code in different languages;
◾ the translation of header files from the C language as a counterpart to the conditional compilation.

Conveniently somewhere in the beginning of the module to make comments such as:
(* [Feature | On | Off] *)
(* [Comment | en | ru | fr] *)
(* [MacrosId | value1 | value2 | value3] *)

Then it is easy to switch options. Besides the compiler understands commands like:
DevCompiler.CompileThis MyModule (feature: On, macrosId: value1)

Note: The names in the team selector and options must be strings. For example:
DevCompiler.CompileThis MyModule ("BlackBox version": "1.5")
Post Reply