issue-#100 Review all the existing documentation

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 »

In practice, the normal user does not need Log and for avoiding any confusing
why it exists the fold text is enough.

> Let's be honest. I do not think, that any time we would change the Log module.

When Log is promoted to a general purpose logging framework, it would need
some generalization. Currently it supports only a single logging device.
A general purpose logging framework would have to support multiple
logging devices side by side. I guess, this limitation in its design
is why it was kept private.
Also, StdLog directly writes to the log window, bypassing Log.
It is questionable if this behavior is appropriate in the context of a
general purpose logging framework.
Also, StdLog behaves slightly different with respect to buffering.
So, what I want to say is that things are not so simple as they may look like
at the beginning.

We are here in the process of reviewing the existing docu and for that
it is enough to clarify the meaning of Log by means of some folded text.
Everything else goes beyond this issue.

- 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 »

Josef Templ wrote:We are here in the process of reviewing the existing docu and for that
it is enough to clarify the meaning of Log by means of some folded text.
Everything else goes beyond this issue.
Agree.
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 »

I added the documentation to Log as Josef suggested.
http://blackboxframework.org/unstable/i ... a1.504.zip

I suggest to vote now for this step of documentation improvement. Then we can continue discussion on the beta stage.
User avatar
DGDanforth
Posts: 1061
Joined: Tue Sep 17, 2013 1:16 am
Location: Palo Alto, California, USA
Contact:

Re: issue-#100 Review all the existing documentation

Post by DGDanforth »

Ivan Denisov wrote:I added the documentation to Log as Josef suggested.
http://blackboxframework.org/unstable/i ... a1.504.zip

I suggest to vote now for this step of documentation improvement. Then we can continue discussion on the beta stage.
I would like to see a summary of which modules have had their documentation changed.

-Doug
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 »

In "Help Contents" I always found the link named "Custom Commands" confusing.
Wouldn't it be better to simply call it "Std Subsystem"?

- 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 »

Josef Templ wrote:Wouldn't it be better to simply call it "Std Subsystem"?
Yes, it is better.
- 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 »

Why do you use StdCmds.OpenAux instead of StdCmds.OpenBrowser for the link in the docu of Log?
- 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 »

I fixed links in Log docu and in Help dialog.
http://blackboxframework.org/unstable/i ... a1.509.zip
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 »

DGDanforth wrote:I would like to see a summary of which modules have had their documentation changed.
Changes list:
- "Mac OS" was removed from all the docu and some of cross-development descriptions also were removed for making the documentation simpler to read
- Duplicating Docu/Tut-Tot.odc removed
- Direct-To-COM compiler integrated with documentation
- Several links in Help dialog were renamed and two new links (Ctl subsystem + Direct-To-COM compiler) was added
- The formatting was improved in all the Tour, User-Man and others documents (space for left and right sides, justify, space lines to paragraphs)
- Oberon logo was removed from all the documentation (so StdLogos was removed)
- Control element was moved from sources to documentation of ObxCtrls
- Center copyright was added to LICENSE.txt and year was fixed in Docu/BB-License.odc
- The documentation of Log module was added
- Authorship from DevAnalyzer was removed
- Callback flag description was added to Dev/Docu/P-S-I.odc
- References to old releases 1.2 and 1.3 from Docu/CP-New.odc and Docu/DTC-Intro.odc were removed
- Definition of the array was fixed in Docu/Tut-B.odc (should be 0..length-1)
- The restrictions of debugger distribution were removed from Std/Docu/Debug.odc
- StdLinks documentation was improved according new filter terminology
- Dates module documentation was significantly improved
- Preconditions were fixed in Meta module
- The description of SET syntax is fixed in Text/Docu/Mappers.odc
- Several typos fixed

Files changed:
Com/Docu/Connect.odc
Com/Docu/EnumRect.odc
Com/Docu/Koala.odc
Com/Docu/KoalaDll.odc
Com/Docu/KoalaExe.odc
Com/Docu/Object.odc
Com/Docu/PhoneBook.odc
Com/Docu/PhoneBookActiveX.odc
Ctl/Docu/Dev-Man.odc
Ctl/Docu/Excel9.odc
Dev/Docu/Analyzer.odc
Dev/Docu/Build-Tool.odc
Dev/Docu/Inspector.odc
Dev/Docu/Linker.odc
Dev/Docu/P-S-I.odc
Dev/Docu/User-Man.odc
Docu/BB-Chars.odc
Docu/BB-Docu.odc
Docu/BB-License.odc
Docu/BB-Road.odc
Docu/BB-Rules.odc
Docu/CP-Lang.odc
Docu/CP-New.odc
Docu/DTC-COM.odc
Docu/DTC-Comp.odc
Docu/DTC-Env.odc
Docu/DTC-HowTo.odc
Docu/DTC-Intro.odc
Docu/Help.odc
Docu/Tour.odc
Docu/Tut-1.odc
Docu/Tut-2.odc
Docu/Tut-3.odc
Docu/Tut-4.odc
Docu/Tut-5.odc
Docu/Tut-6.odc
Docu/Tut-A.odc
Docu/Tut-B.odc
Docu/Tut-TOC.odc
Docu/Tut-Tot.odc
Form/Docu/User-Man.odc
Obx/Docu/BB-Rules.odc
Obx/Docu/Buttons.odc
Obx/Docu/Ctrls.odc
Obx/Docu/Cubes.odc
Obx/Docu/Omosi.odc
Obx/Docu/Scroll.odc
Obx/Docu/Sys-Map.odc
Obx/Mod/Ctrls.odc
Sql/Docu/Dev-Man.odc
Std/Docu/Cmds.odc
Std/Docu/Debug.odc
Std/Docu/ETHConv.odc
Std/Docu/Folds.odc
Std/Docu/Links.odc
Std/Docu/Logos.odc
Std/Mod/Logos.odc
System/Docu/Controllers.odc
System/Docu/Controls.odc
System/Docu/Dates.odc
System/Docu/Dialog.odc
System/Docu/Files.odc
System/Docu/Fonts.odc
System/Docu/Log.odc
System/Docu/Meta.odc
System/Docu/Stores.odc
System/Docu/User-Man.odc
System/Mod/Dates.odc
Text/Docu/Mappers.odc
Text/Docu/User-Man.odc
Win/Docu/Api.odc
appbuild/newbbscript.txt
LICENSE.txt
Post Reply