Author Topic: BlackDoc documentation plugin  (Read 27387 times)

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9694
Re: BlackDoc documentation plugin
« Reply #15 on: April 22, 2012, 11:25:30 am »
Yes; compiled and tested on XP with the project file from my previous post.
But only, if hijacking the PCH chain.

To be correct: It would need some patches to work, but these are mainly missing includes. So nothing to worry about.

However, what I aalso noticed:

you are using wxString but then you are doing something like this:
Code
    // const wxString &data is defined
    size_t pos = data.find(m_pathsSeparator);
    if(wxNOT_FOUND == pos)
For a better style you should rather not use the STL version of find() but the wx one wxString provides. Especially if you compare with a wx constant (wxNOT_FOUND) afterwards. Either all wx or all STL... ;)
Compiler logging: Settings->Compiler & Debugger->tab "Other"->Compiler logging="Full command line"
C::B Manual: https://www.codeblocks.org/docs/main_codeblocks_en.html
C::B FAQ: https://wiki.codeblocks.org/index.php?title=FAQ

Offline oBFusCATed

  • Developer
  • Lives here!
  • *****
  • Posts: 13413
    • Travis build status
Re: BlackDoc documentation plugin
« Reply #16 on: April 22, 2012, 11:29:33 am »
The correct code (I think) is:
Code
wxString::size_type pos=str.find(...);
if (pos==wxString::npos) {
   ....
}
(most of the time I ignore long posts)
[strangers don't send me private messages, I'll ignore them; post a topic in the forum, but first read the rules!]

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9694
Re: BlackDoc documentation plugin
« Reply #17 on: April 22, 2012, 11:49:12 am »
The correct code (I think) is:
Code
wxString::size_type pos=str.find(...);
if (pos==wxString::npos) {
   ....
}
True, if you insist on using the STL compatibility layer of wxString. But then again why using wxString at all? If wxString is not needed, STL string will surely perform better.

Edit: BTW: I though more in a direction of wxString::Contains(...) or alike.
« Last Edit: April 22, 2012, 11:53:18 am by MortenMacFly »
Compiler logging: Settings->Compiler & Debugger->tab "Other"->Compiler logging="Full command line"
C::B Manual: https://www.codeblocks.org/docs/main_codeblocks_en.html
C::B FAQ: https://wiki.codeblocks.org/index.php?title=FAQ

Offline oBFusCATed

  • Developer
  • Lives here!
  • *****
  • Posts: 13413
    • Travis build status
(most of the time I ignore long posts)
[strangers don't send me private messages, I'll ignore them; post a topic in the forum, but first read the rules!]

Offline marked

  • Multiple posting newcomer
  • *
  • Posts: 10
Re: BlackDoc documentation plugin
« Reply #19 on: April 22, 2012, 01:00:07 pm »
Things turned even simpler: i just replaced the std::unique_ptr with the 'old bad' std::auto_ptr.

The use of gnu++0x flag is no more necessary. Sources are updated. Please, test them again. I hope, old GCC will be happy :)

MortenMacFly:
Yes, thank you for finding this mistake. I was changing the code to work the stl way and I've forgot some wxNOT_FOUND's. Now they are replaced in the way oBFusCATed suggested.

I deal with wxString the stl way wherever it is possible, because wxWidgets help is proposing this, for future compatibility etc. It is pointed exactly at the top of this doc
http://docs.wxwidgets.org/stable/wx_wxstring.html

Contains() returns the bool value, and in most cases I later need the start position of occurance to obtain substring.

Offline Jenna

  • Administrator
  • Lives here!
  • *****
  • Posts: 7255
Re: BlackDoc documentation plugin
« Reply #20 on: April 22, 2012, 01:14:55 pm »
On wx-dev they recommend to use std::string wherever possible, and use wxString only to interact with the gui.

Quote from: Vadim Zeitlin http://groups.google.com/group/wx-dev/msg/2790958146ff5665
In general, my advice is very simple: do *not* use wxString for textual
manipulation. Use std::string or std::wstring for this and only use
wxString to get data to or from the GUI.


Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9694
Re: BlackDoc documentation plugin
« Reply #21 on: April 22, 2012, 01:38:18 pm »
On wx-dev they recommend to use std::string wherever possible, and use wxString only to interact with the gui.
That's what I meant: either only STL or only wxString.

Mmmh... am I missing something here? Is there really a wx recommendation to use the STL methods of wxString instead of the wx ones? Can somebody enlighten me on this?
Compiler logging: Settings->Compiler & Debugger->tab "Other"->Compiler logging="Full command line"
C::B Manual: https://www.codeblocks.org/docs/main_codeblocks_en.html
C::B FAQ: https://wiki.codeblocks.org/index.php?title=FAQ

Offline marked

  • Multiple posting newcomer
  • *
  • Posts: 10
Re: BlackDoc documentation plugin
« Reply #22 on: April 22, 2012, 01:59:42 pm »
The use of std::string instead of wxString will increase the time of development, because std::string is missing some nice methods, like StartsWith/EndsWith, Replace(char* old, char* new, bool all = true) etc. It then will be necessary to implement this operations in my code. C::B SDK also wants wxString, so I decided to use it.

Also it is not very clear, how to add the support for unicode and non-unicode builds of wxWidgets while using std::string and std::wstring. Dealing with locales and convertions between them is a little bit tricky.

@MortenMacFly
I know only what I mentioned above. Here is the quote from wxString help page: "You may notice that wxString sometimes has many functions which do the same thing like, for example, Length(), Len() and length() which all return the string length. In all cases of such duplication the std::string-compatible method (length() in this case, always the lowercase version) should be used as it will ensure smoother transition to std::string when wxWidgets starts using it instead of wxString."

« Last Edit: April 22, 2012, 02:01:32 pm by marked »

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9694
Re: BlackDoc documentation plugin
« Reply #23 on: April 22, 2012, 02:04:15 pm »
In all cases of such duplication the std::string-compatible method (length() in this case, always the lowercase version) should be used as it will ensure smoother transition to std::string when wxWidgets starts using it instead of wxString."
This is really new to me. I really can't believe there will be a day without wxString. This would literally affect every wx application on earth!

An btw, Jens:
On wx-dev they recommend to use std::string wherever possible, and use wxString only to interact with the gui.

If you read further there is an answer of Julian Smart:
Quote
This is possibly the scariest thing I've heard in 2012 so far. I use
wxString *extensively* for data storage and manipulation. All the time,
for almost every class I ever write.
[...]
Am I mad to be using wxString? Well, it's a bit late now that's for sure...
I clearly share his thoughts.

Edit: Well, having said that I continued to read how VZ is arguing against that... interesting. I didn't expect such a "battle" on one of these core classes of wxWidgets to be honest.

So well, still: If you are with VZ you should only use std::string and not mixed. ;-)

But we shouln't continue on that an longer as IMHO everything has been said (and I learned something new). Back to the topic: lets talk about the plugin.
« Last Edit: April 22, 2012, 02:11:31 pm by MortenMacFly »
Compiler logging: Settings->Compiler & Debugger->tab "Other"->Compiler logging="Full command line"
C::B Manual: https://www.codeblocks.org/docs/main_codeblocks_en.html
C::B FAQ: https://wiki.codeblocks.org/index.php?title=FAQ

Offline Jenna

  • Administrator
  • Lives here!
  • *****
  • Posts: 7255
Re: BlackDoc documentation plugin
« Reply #24 on: April 22, 2012, 03:07:44 pm »
So well, still: If you are with VZ you should only use std::string and not mixed. ;-)

The problem is, that many users find wxString in wx2.9 much slower as in 2.8.

That might be (and is most likely) the cause for the much slower cc with wx2.9.

Offline marked

  • Multiple posting newcomer
  • *
  • Posts: 10
Re: BlackDoc documentation plugin
« Reply #25 on: April 22, 2012, 03:13:58 pm »
Ok, I am still waiting for some feedback about bugs and mistakes. Also feedback about autotools files I've added to the project will be very pleasant, just to be sure they work not only by me.

Now some ideas for the future to discuss.

The next large thing I want to implement in my plugin is the generation of help skeleton from C++ sources. This means, the plugin will parse project sources (maybe also doxygen comments) and then create BlackDoc files with appropriate names taken from classes/others names and fill this files with the info about class members etc. I need to do some research here: parsing the C++ code isn't simple because of preprocessor directives, and C++0x makes things even more scary. So this step may take time. This is only one more thing I really need from this plugin.

Several other ideas, I don't promise to create this all:
- BlackDoc project wizard to be able to create separate documentation project.
- 'Create BlackDoc file' item in the context menu, when you right-click over some name in the source code.
- Some text patterns which can be chosen while creating the BlackDoc file, for example 'class documentation file', 'namespace documentation file' etc.
- Export to other formats. At least *.chm is necessary, I think.
- Lists and tables with multiline items in the wiki-style lang.
- When the BlackDoc file is opened, some right-click or app menu features, like 'add current date', 'add table' etc.
- Maybe also the markup language highlighting, but is it possible without patching scintilla?
- Some other ideas?

Offline killerbot

  • Administrator
  • Lives here!
  • *****
  • Posts: 5490
Re: BlackDoc documentation plugin
« Reply #26 on: April 22, 2012, 03:49:56 pm »
wxwidgets in relationship to stl is a strange to my personally.
A few distro versions ago (I am using Opensuse) I couldn't build CB anymore. Why, the default wx library and dev files were the stl variant; and no longer the wxcontainer version. Switching to the wxcontainer version solved it.
Confusing is the least we can say.

If the language provides it, I would always prefer the language instead of abstractions like boost, wxwidgets, poco, qt.
Wxwidgets and qt, and poco add more functionality to their string classes for example, things lacking in the stl variant.
But enhancing the stl variant with for example boost string algo library brings nearly the same thing.
Nice thing about this : it is extending the stl string not replacing or reinventing the wheel.
But this is offcourse a matter of taste.

With respect to the C++0x, I am 100% in favor for using it, I think the compilers mostly used for building CB are gcc, and to some extend MSVC. Gcc is really taking the C++0x lead, and MSVC is not that far behind. That's the good news, .... the bad news we want to support distros with older gcc versions.
As has been mentioned as an example CentOS.
Here again I express my personal feeling, I have been running into CentOS and have been wishing it not so pleasant things ;-) . I know people want it to be stable, but its packages are so darn old, that it makes me turn into a synical mood and I want to suggest windows 3.11 to those users ;-)
Just kidding, but personal taste.

Waiting another 3 - 5 years before really using C++0x, I am sorry, that's what the C++ community can do without, we want things to move on, and we all hope to have another standard in 5 years (file system ? sockets ? string algorithm ,....).

Today is surely to soon to switch and put some people out in the cold, but we need to think about it and after the next CB release (whenever that might be ;-) ) we should consider putting it on the roadmap). By theway, that would be good for Centos, they can stick with that release of CB for like 20 years , to bad for the developer that wants to build CB him/her self on Centos  :(

As for a new plug-in, I think the plug-in developer should be allowed to use C++0x, meaning his plug-in wil probably never been promoted to a contrib plugin in our repository, unless we have makefiles, projects files that might determine that there's no C++0x support and then disables that specific plug-in from the build being carried out at hand.

As another brain teaser :  keep waiting on wxwidgets to move on, no thanks. Their 3.0 is even getting ready at a slower pace then the C++0x standard took  8).
And if you want to talk about a platform breaking code with every release , yes .. wxwidgets.
« Last Edit: April 22, 2012, 03:51:59 pm by killerbot »

Offline oBFusCATed

  • Developer
  • Lives here!
  • *****
  • Posts: 13413
    • Travis build status
Re: BlackDoc documentation plugin
« Reply #27 on: April 22, 2012, 11:06:17 pm »
Unfortunately, if you want to use a linux to write plugins for other commercial software products as I do (Autodesk Maya and  Katana/Nuke by The Foundry in my case), you have to stick to the compilers they have been build with and the easiest option to do so is to use the distro and version they have being built on.
In my case Centos 5.6. I don't like Centos, nor do I like yum/rpm, but this is the easiest option and the most secure one in terms of compatibility.
(most of the time I ignore long posts)
[strangers don't send me private messages, I'll ignore them; post a topic in the forum, but first read the rules!]

Offline ollydbg

  • Developer
  • Lives here!
  • *****
  • Posts: 5910
  • OpenCV and Robotics
    • Chinese OpenCV forum moderator
Re: BlackDoc documentation plugin
« Reply #28 on: April 23, 2012, 04:55:15 am »
So well, still: If you are with VZ you should only use std::string and not mixed. ;-)

The problem is, that many users find wxString in wx2.9 much slower as in 2.8.

That might be (and is most likely) the cause for the much slower cc with wx2.9.

Off thread question:
Do we need to fix the string type std::string<char> or std::string<wchar_t> in CodeCompletion plugin? A lot of the parsing work is text/buffer manipulation. Also when we need to do the GUI part, we can translate to wxString.

Another thing is: if the part buffer char type is fixed. I can use more extreme fast lexer like QUEX or FLEX. The Current Tokenizer is quite limited.
« Last Edit: April 23, 2012, 04:56:54 am by ollydbg »
If some piece of memory should be reused, turn them to variables (or const variables).
If some piece of operations should be reused, turn them to functions.
If they happened together, then turn them to classes.

Offline Alpha

  • Developer
  • Lives here!
  • *****
  • Posts: 1513
Re: BlackDoc documentation plugin
« Reply #29 on: April 24, 2012, 02:43:37 am »
Yes; compiled and tested on XP with the project file from my previous post.
But only, if hijacking the PCH chain.
Is this the proper way to do it?
Code
diff -r e8000aa19e1c BlackDoc-win.cbp
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/BlackDoc-win.cbp Mon Apr 23 20:39:43 2012 -0400
@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
+<CodeBlocks_project_file>
+ <FileVersion major="1" minor="6" />
+ <Project>
+ <Option title="BlackDoc" />
+ <Option pch_mode="2" />
+ <Option compiler="gcc" />
+ <Build>
+ <Target title="default">
+ <Option output="blackdoc" prefix_auto="1" extension_auto="1" />
+ <Option object_output="objs" />
+ <Option type="3" />
+ <Option compiler="gcc" />
+ <Option parameters="--debug-log --multiple-instance -na -ns -nd" />
+ <Option host_application="$(#cb)\devel\codeblocks.exe" />
+ <Option run_host_application_in_terminal="0" />
+ <Compiler>
+ <Add option="-g" />
+ <Add option="-pipe" />
+ <Add option="-mthreads" />
+ <Add option="-fmessage-length=0" />
+ <Add option="-fexceptions" />
+ <Add option="-Winvalid-pch" />
+ <Add option="-DBUILDING_PLUGIN" />
+ <Add option="-DHAVE_W32API_H" />
+ <Add option="-D__WXMSW__" />
+ <Add option="-DWXUSINGDLL" />
+ <Add option="-DcbDEBUG" />
+ <Add option="-DCB_PRECOMP" />
+ <Add option="-DWX_PRECOMP" />
+ <Add option="-DwxUSE_UNICODE" />
+ <Add directory="$(#cb)\include" />
+ <Add directory="$(#cb)\sdk\wxscintilla\include" />
+ <Add directory="$(#WX.include)" />
+ <Add directory="$(#WX.lib)\gcc_dll$(WX_CFG)\msw$(WX_SUFFIX)" />
+ </Compiler>
+ <Linker>
+ <Add option="-Wl,--enable-auto-import" />
+ <Add option="-mthreads" />
+ <Add library="wxmsw28$(WX_SUFFIX)" />
+ <Add library="codeblocks" />
+ <Add directory="$(#cb)\devel" />
+ <Add directory="$(#WX.lib)\gcc_dll$(WX_CFG)" />
+ </Linker>
+ <ExtraCommands>
+ <Add after="zip -j9 blackdoc.zip manifest.xml styles.css" />
+ <Add after="zip -j9 blackdoc.cbplugin blackdoc.dll blackdoc.zip" />
+ <Mode after="always" />
+ </ExtraCommands>
+ </Target>
+ <Environment>
+ <Variable name="WX_CFG" value="" />
+ <Variable name="WX_SUFFIX" value="u" />
+ </Environment>
+ </Build>
+ <VirtualTargets>
+ <Add alias="All" targets="default;" />
+ </VirtualTargets>
+ <Compiler>
+ <Add option="-Wall" />
+ </Compiler>
+ <Unit filename="Directory.cpp" />
+ <Unit filename="Directory.h" />
+ <Unit filename="ErrorMessage.cpp" />
+ <Unit filename="ErrorMessage.h" />
+ <Unit filename="FileCreationDialog.cpp" />
+ <Unit filename="FileCreationDialog.h" />
+ <Unit filename="FileSignature.cpp" />
+ <Unit filename="FileSignature.h" />
+ <Unit filename="FilesHandler.cpp" />
+ <Unit filename="FilesHandler.h" />
+ <Unit filename="HTMLActiveFileExporter.cpp" />
+ <Unit filename="HTMLActiveFileExporter.h" />
+ <Unit filename="HTMLActiveProjectExporter.cpp" />
+ <Unit filename="HTMLActiveProjectExporter.h" />
+ <Unit filename="HTMLBranchIndexBuilder.cpp" />
+ <Unit filename="HTMLBranchIndexBuilder.h" />
+ <Unit filename="HTMLContent.cpp" />
+ <Unit filename="HTMLContent.h" />
+ <Unit filename="HTMLDocument.cpp" />
+ <Unit filename="HTMLDocument.h" />
+ <Unit filename="HTMLExporter.cpp" />
+ <Unit filename="HTMLExporter.h" />
+ <Unit filename="HTMLFilesCreator.cpp" />
+ <Unit filename="HTMLFilesCreator.h" />
+ <Unit filename="HTMLFooter.h" />
+ <Unit filename="HTMLHeader.cpp" />
+ <Unit filename="HTMLHeader.h" />
+ <Unit filename="HTMLInnerParser.cpp" />
+ <Unit filename="HTMLInnerParser.h" />
+ <Unit filename="HTMLList.cpp" />
+ <Unit filename="HTMLList.h" />
+ <Unit filename="HTMLMainIndexBuilder.cpp" />
+ <Unit filename="HTMLMainIndexBuilder.h" />
+ <Unit filename="HTMLMenu.cpp" />
+ <Unit filename="HTMLMenu.h" />
+ <Unit filename="HTMLPageBuilder.cpp" />
+ <Unit filename="HTMLPageBuilder.h" />
+ <Unit filename="HTMLRemovePreviousFiles.cpp" />
+ <Unit filename="HTMLRemovePreviousFiles.h" />
+ <Unit filename="HTMLSourceCode.cpp" />
+ <Unit filename="HTMLSourceCode.h" />
+ <Unit filename="HTMLTable.cpp" />
+ <Unit filename="HTMLTable.h" />
+ <Unit filename="HTMLTags.cpp" />
+ <Unit filename="HTMLTags.h" />
+ <Unit filename="IFileData.h" />
+ <Unit filename="ProgressDialog.cpp" />
+ <Unit filename="ProgressDialog.h" />
+ <Unit filename="Project.cpp" />
+ <Unit filename="Project.h" />
+ <Unit filename="ProjectInfo.cpp" />
+ <Unit filename="ProjectInfo.h" />
+ <Unit filename="QuestionMessage.cpp" />
+ <Unit filename="QuestionMessage.h" />
+ <Unit filename="ReplacementDialog.cpp" />
+ <Unit filename="ReplacementDialog.h" />
+ <Unit filename="StringPreparator.cpp" />
+ <Unit filename="StringPreparator.h" />
+ <Unit filename="Text.cpp" />
+ <Unit filename="Text.h" />
+ <Unit filename="WarningMessage.cpp" />
+ <Unit filename="WarningMessage.h" />
+ <Unit filename="blackdoc.cpp" />
+ <Unit filename="blackdoc.h" />
+ <Unit filename="description-en.txt" />
+ <Unit filename="description-ru.txt" />
+ <Unit filename="documentation\html\help\description-en.html" />
+ <Unit filename="documentation\html\help\description-ru.html" />
+ <Unit filename="documentation\html\help\index.html" />
+ <Unit filename="documentation\html\help\styles.css" />
+ <Unit filename="documentation\html\index.html" />
+ <Unit filename="documentation\html\styles.css" />
+ <Unit filename="gpl-license.txt" />
+ <Unit filename="manifest.xml" />
+ <Unit filename="styles.css" />
+ <Extensions>
+ <code_completion />
+ <envvars />
+ <debugger />
+ </Extensions>
+ </Project>
+</CodeBlocks_project_file>
diff -r e8000aa19e1c HTMLExporter.cpp
--- a/HTMLExporter.cpp Sun Apr 22 14:29:08 2012 +0400
+++ b/HTMLExporter.cpp Mon Apr 23 20:39:43 2012 -0400
@@ -18,10 +18,15 @@
  * along with BlackDoc. If not, see <http://www.gnu.org/licenses/>.
  *
  */
+
+#include "sdk.h"
+
+#ifndef CB_PRECOMP
+    #include <projectmanager.h>
+    #include <editormanager.h>
+    #include <cbproject.h>
+#endif
 
-#include <projectmanager.h>
-#include <editormanager.h>
-#include <cbproject.h>
 #include "HTMLExporter.h"
 #include "QuestionMessage.h"
 #include "HTMLActiveFileExporter.h"