issue-#100 Review all the existing documentation

Zinn
Posts: 476
Joined: Tue Mar 25, 2014 5:56 pm
Location: Frankfurt am Main
Contact:

Re: issue-#100 Review all the existing documentation

Post by Zinn »

Please remember, I still not agree about to remove the StdLogos. We may change the logo, but not remove it.
- Helmut
Ivan Denisov
Posts: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Review all the existing documentation

Post by Ivan Denisov »

Zinn wrote:Please remember, I still not agree about to remove the StdLogos. We may change the logo, but not remove it.
You still does not give any arguments for keeping it. It was necessary when it was used in documentation. Now the logo is an image, so there is no need in StdLogos module.
User avatar
Josef Templ
Posts: 2047
Joined: Tue Sep 17, 2013 6:50 am

Re: issue-#100 Review all the existing documentation

Post by Josef Templ »

I have updated the docu for StdFolds according to the changes of the Folds dialog.

- Josef
Zinn
Posts: 476
Joined: Tue Mar 25, 2014 5:56 pm
Location: Frankfurt am Main
Contact:

Re: issue-#100 Review all the existing documentation

Post by Zinn »

Ivan Denisov wrote:I am suggesting everybody to find the time until weekend to suggest final changes to the Docu and then in the weekend I will try to incorporate the texts in the topic branch.
The line "This module has a private interface, it is only used internally." is removed in Docu of Log.

Is module Log now available for normal use?

What is the different between Log and StdLog?
When should I use Log and when should I use StdLog?

- Helmut
Zinn
Posts: 476
Joined: Tue Mar 25, 2014 5:56 pm
Location: Frankfurt am Main
Contact:

Re: issue-#100 Review all the existing documentation

Post by Zinn »

Ivan Denisov wrote:
Zinn wrote:Please remember, I still not agree about to remove the StdLogos. We may change the logo, but not remove it.
You still does not give any arguments for keeping it. It was necessary when it was used in documentation. Now the logo is an image, so there is no need in StdLogos module.
see http://forum.blackboxframework.org/view ... =419#p3634
- Helmut
User avatar
Josef Templ
Posts: 2047
Joined: Tue Sep 17, 2013 6:50 am

Re: issue-#100 Review all the existing documentation

Post by Josef Templ »

Zinn wrote:
Ivan Denisov wrote:I am suggesting everybody to find the time until weekend to suggest final changes to the Docu and then in the weekend I will try to incorporate the texts in the topic branch.
The line "This module has a private interface, it is only used internally." is removed in Docu of Log.

Is module Log now available for normal use?

What is the different between Log and StdLog?
When should I use Log and when should I use StdLog?

- Helmut
The current docu of Log IMHO is pretty confusing for the normal user.
It does not explain the difference of Log and StdLog and its intention.
Instead it repeats the trivial part of StdLog.

By making a private module (Log) available for the normal user,
we introduce the obligation to document it properly and
keep it stable in the future. By keeping it in the private part
we have more freedom in the future.

As a compromise I would suggest to keep Log in the private part for now
but add a fold very much like for Kernel but with only the relevant information.
Thereby it is easy for the low-level BB developer to see the meaning of the
module and its relation to StdLog.

Note: Log is not only a variant of StdLog that can be spelled with fewer letters.
It is the foundation of a little logging framework but it is currently intended only for
logging in low level modules that cannot import StdLog directly due to cyclic imports.
It is possible that it was intended to evolve into a more general purpose logging framework
but never reached this level of maturity and therefore it has been kept private.

My proposal for the folded text would be:

Module Log provides an abstract interface for logging. It can be used for logging in low-level modules that cannot import StdLog directly due to cyclic imports. The logging features are the same as for StdLog except that any logging before the installation of the logging hook is silently ignored. During the normal startup of BlackBox StdLog is loaded and installs a logging hook. In principle, it would also be possible to support other logging devices such as a console, a file, or a remote server by means of appropriate implementations of the logging hook.

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

Re: issue-#100 Review all the existing documentation

Post by Ivan Denisov »

Zinn wrote:
Ivan Denisov wrote:
Zinn wrote:Please remember, I still not agree about to remove the StdLogos. We may change the logo, but not remove it.
You still does not give any arguments for keeping it. It was necessary when it was used in documentation. Now the logo is an image, so there is no need in StdLogos module.
see http://forum.blackboxframework.org/view ... =419#p3634
- Helmut
Opinion is not an argument. Robert also did not give any arguments.
Robert and Helmut and others, please, say what is the utility of this module? Do you using it in any applications? If you are using it, whats for? In documentation?
User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: issue-#100 Review all the existing documentation

Post by Robert »

Ivan Denisov wrote:Now the logo is an image, so there is no need in StdLogos module. Robert also did not give any arguments.
Perhaps you are right. What is the new logo, a .png or .jpeg? How is in included in Docus? Does each Docu include a separate copy of the bitmap?

I was imagining that the new logo would be a custom View - implemented in a new version of StdLogos - and that its Restore would use the contents of some bitmap file rather than comprising many WinApi drawing calls. That way there would only be one copy of the bitmap on file, or in memory, and that it could be updated, if necessary, by only making one change.
Ivan Denisov
Posts: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Review all the existing documentation

Post by Ivan Denisov »

Robert wrote:
Ivan Denisov wrote:Now the logo is an image, so there is no need in StdLogos module. Robert also did not give any arguments.
Perhaps you are right. What is the new logo, a .png or .jpeg? How is in included in Docus? Does each Docu include a separate copy of the bitmap?

I was imagining that the new logo would be a custom View - implemented in a new version of StdLogos - and that its Restore would use the contents of some bitmap file rather than comprising many WinApi drawing calls. That way there would only be one copy of the bitmap on file, or in memory, and that it could be updated, if necessary, by only making one change.
Now the logo is used only once in About dialog. It is inserted as bitmap view. If we should insert Logo in many documents I agree with your argument about space reduction and easy logo replacement. Does it necessary to insert Logo in many places?
Ivan Denisov
Posts: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Review all the existing documentation

Post by Ivan Denisov »

Josef Templ wrote:Module Log provides an abstract interface for logging. It can be used for logging in low-level modules that cannot import StdLog directly due to cyclic imports. The logging features are the same as for StdLog except that any logging before the installation of the logging hook is silently ignored. During the normal startup of BlackBox StdLog is loaded and installs a logging hook. In principle, it would also be possible to support other logging devices such as a console, a file, or a remote server by means of appropriate implementations of the logging hook.
Good text!
Josef Templ wrote:By making a private module (Log) available for the normal user,
we introduce the obligation to document it properly and
keep it stable in the future. By keeping it in the private part
we have more freedom in the future.
Let's be honest. I do not think, that any time we would change the Log module.

I am suggest to put Josef text in Logo module. However I do not see the reason to hide it in folds... That do others think? Should we hide Log.

Log is the interface of StdLog. Using log, you make your application more portable. I mean, that it can be more easy adopted to console version. The example for alternative LogHook is WinConsole by Ivan Goryachev. I am attaching it to this message as en example.
Attachments
WinConsole.txt
(5.15 KiB) Downloaded 236 times
Post Reply