Overview
Examples
Screenshots
Comparisons
Applications
Download
Documentation
Tutorials
Bazaar
Status & Roadmap
FAQ
Authors & License
Forums
Funding Ultimate++
Search on this site
Search in forums












SourceForge.net Logo
Home » Developing U++ » U++ Developers corner » Documentation and Topic++
Re: Documentation and Topic++ [message #16449 is a reply to message #16443] Mon, 16 June 2008 13:00 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Well, before going further into details, I guess we should consider:

- how much effort we are really able to put into it

- how much of it can be automated. E.g. IMO, that nice mockup posted a while ago can be fully generated using current Topic++ scheme

Re: Documentation and Topic++ [message #16450 is a reply to message #16449] Mon, 16 June 2008 13:58 Go to previous messageGo to next message
mdelfede is currently offline  mdelfede
Messages: 1307
Registered: September 2007
Ultimate Contributor
luzr wrote on Mon, 16 June 2008 13:00

Well, before going further into details, I guess we should consider:

- how much effort we are really able to put into it


Well, that depends on how comfortable are instruments to do it.
IMHO in current help engine, most of time is spent formatting documentation rather than documenting code.... Something to just write stuffs and that does automatically (and uniform) formatting would be of great help.

Quote:


- how much of it can be automated. E.g. IMO, that nice mockup posted a while ago can be fully generated using current Topic++ scheme



That depends also on tools. I don't know (I didn't go too in depth on it) if topic++ scheme can store as many information as needed and if it's easy to parse as xml. If so, we could easily separate data structure from viewer.

So, IMHO the question can be also separated in 2 :
1) How much effort can we put in coding new tools ?
2) How much effort can we put in writing docs ?

About point 1, I don't know... For the point 2, I'd be happy to contribute while using upp. But I'd need something to speed up stuffs.

Max
Re: Documentation and Topic++ [message #16451 is a reply to message #16450] Mon, 16 June 2008 15:34 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
mdelfede wrote on Mon, 16 June 2008 07:58

luzr wrote on Mon, 16 June 2008 13:00

Well, before going further into details, I guess we should consider:

- how much effort we are really able to put into it


Well, that depends on how comfortable are instruments to do it.
IMHO in current help engine, most of time is spent formatting documentation rather than documenting code.... Something to just write stuffs and that does automatically (and uniform) formatting would be of great help.

Quote:


- how much of it can be automated. E.g. IMO, that nice mockup posted a while ago can be fully generated using current Topic++ scheme



That depends also on tools. I don't know (I didn't go too in depth on it) if topic++ scheme can store as many information as needed and if it's easy to parse as xml. If so, we could easily separate data structure from viewer.



Topic++ stores reference points for all documented code entities - code items (methods, variables etc). It is easy to get document and place in the document for specific code item.

This is complemented (or should be Smile with ability to parse C++ and actually get the complete list of all these code items. IMO, with these two systems should give you ability to produce some pretty nice results...

Mirek
Re: Documentation and Topic++ [message #16453 is a reply to message #16449] Mon, 16 June 2008 17:21 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
luzr wrote on Mon, 16 June 2008 14:00

Well, before going further into details, I guess we should consider:

- how much effort we are really able to put into it

- how much of it can be automated. E.g. IMO, that nice mockup posted a while ago can be fully generated using current Topic++ scheme



I believe that the effort needed to enable Topic++ as a tool to do what we want is not a great one, so I say we should be willing to put all the effort that is needed into it. As you said, Topic++ can be used to generate pages similar to previous mock-ups and others also, so we should be able to do the coding changes in no time and get a tool that has all the issues regarding formating automated, or at least with minimal user input. It is more a question of style.

The more difficult part is actually writing comprehensive documentation for the parts where an API reference is not enough. Here we must ask how much effort are we going to put into it and who will do it. I for one like more to do coding and even just read code (I'm chewing through String and Value classes right now), but am not too fond of writing comprehensive and even witty manual style documentation pages. Still, I do have some ideas for some parts which I could try to put on paper Smile.
Re: Documentation and Topic++ [message #16457 is a reply to message #16453] Mon, 16 June 2008 19:38 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Quote:


I believe that the effort needed to enable Topic++ as a tool to do what we want is not a great one, so I say we should be willing to put all the effort that is needed into it.



Well, the effort for T++ is not that high.. however for it to work well, we absolutely need better C++ parser. And THAT is the problem.

Actually, I have restarted the work on parser this weekend. Unfortunately, with so many conflicting demands for the parser, it ain't easy...

Mirek
Re: Documentation and Topic++ [message #16459 is a reply to message #16449] Mon, 16 June 2008 20:48 Go to previous messageGo to next message
Mindtraveller is currently offline  Mindtraveller
Messages: 917
Registered: August 2007
Location: Russia, Moscow rgn.
Experienced Contributor

luzr wrote on Mon, 16 June 2008 15:00

Well, before going further into details, I guess we should consider:

- how much effort we are really able to put into it

- how much of it can be automated. E.g. IMO, that nice mockup posted a while ago can be fully generated using current Topic++ scheme

I may (and will - if it will be possible) contribute to the manual topics. As well as into the overall manuals structure (which is VERY important IMO). I can`t do it full-time, but I`ll try to lend some evening time for these topics. Because I believe in great importance of good docs in U++ future which is important for me - for now it is my main dev platform.

About an automation. Of course better parsing would be good, but this is more actual for reference docs, not for manuals.
What we really need for simplifying manuals creation process:
* Easy and visual hyperlinkage between pages and page parts (easy to use, support for i18n in 1-2 clicks, etc)
* Predefined template and styles support. Creating new standard-looking page should take seconds and 2-3 clicks
* Better embedded images support - no bluring, easy import (gif, jpg, png, Clipboard w/o bugs)
* Template-predefined hyperlink, headers and text styles.

For creating docs we shouldn`t really need Word functionality. We really don`t need to have a large choice of text, color, etc styles. We should have 1-2 styles for all common elements (2-3 heading levels, illustration, comment, code, hyperlink). We should have ability to set them in 1 click. Adding article to general manuals tree should be intuitive and take 1-2 clicks.

It is much more important than having office-wide rich text editing system. Our task is far away from what secretaries need. Smile
Re: Documentation and Topic++ [message #16460 is a reply to message #16459] Mon, 16 June 2008 20:54 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Mindtraveller wrote on Mon, 16 June 2008 14:48



It is much more important than having office-wide rich text editing system. Our task is far away from what secretaries need. Smile


Well, uhm, ok, but if we already have one? Should I start developing another editor only because rich-text is "too much"?

(And in fact, it WAS originaly developed for secretaries Smile In its second life, or maybe in the first, RichEdit is widely used in municipal agenda Smile

Mirek
Re: Documentation and Topic++ [message #16461 is a reply to message #16460] Mon, 16 June 2008 23:12 Go to previous messageGo to next message
mdelfede is currently offline  mdelfede
Messages: 1307
Registered: September 2007
Ultimate Contributor
I still think that the problem is not the richedit, but its usage... It should be used to browse docs (maybe with some addition....) but not to create them.
Creating docs, formatting and linking manually is too time expensive.

Max
Re: Documentation and Topic++ [message #16463 is a reply to message #16461] Tue, 17 June 2008 00:55 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
mdelfede wrote on Mon, 16 June 2008 17:12

I still think that the problem is not the richedit, but its usage... It should be used to browse docs (maybe with some addition....) but not to create them.
Creating docs, formatting and linking manually is too time expensive.

Max



So what you WANT to create docs?

Text processor? And putting all formatting into xml tags? Images into separate file?

Sorry, I am still more happy with RichText here.

Mirek
Re: Documentation and Topic++ [message #16464 is a reply to message #16463] Tue, 17 June 2008 01:02 Go to previous messageGo to next message
mdelfede is currently offline  mdelfede
Messages: 1307
Registered: September 2007
Ultimate Contributor
luzr wrote on Tue, 17 June 2008 00:55

mdelfede wrote on Mon, 16 June 2008 17:12

I still think that the problem is not the richedit, but its usage... It should be used to browse docs (maybe with some addition....) but not to create them.
Creating docs, formatting and linking manually is too time expensive.

Max



So what you WANT to create docs?

Text processor? And putting all formatting into xml tags? Images into separate file?
............



No, just a simple dialog to input docs in a quick way, with no formatting and some predefined fields, which in turn formats data and puts them in whathever you like... which can be also tpp.
I'd never use a text proc to write documents.
But well... that's just my opinion.

Max
Re: Documentation and Topic++ [message #16475 is a reply to message #12713] Tue, 17 June 2008 11:59 Go to previous messageGo to next message
mr_ped is currently offline  mr_ped
Messages: 825
Registered: November 2005
Location: Czech Republic - Praha
Experienced Contributor
Reading about first impressions from UPP in other thread I got idea for yet another type of doc.
A "Quick reference of UPP vs C++", i.e. docs for somebody who's very familiar with common C++ (I'm not even trying to define what is common C++, I think this one will be difficult to solve), so he can quickly check for common pitfalls when using UPP.
Like description of GUI_APP_MAIN, correct way of including packages to project, NTL basics, examples of common main's + inits for applications (but not the easy Hello world stuff, but rather complex things like MT app with GUI + some network + some timer events going on, all together .. BTW a working example application with complex behavior would be nice too).

And all this focused on things which are UPP specific, with omitting/ignoring the pure C++ stuff.

This may help some C++ coders to switch to UPP more easily.

I'm checking the current Manual pages, and this stuff is pretty much all the available topics there, so having a very bare quick reference linked well with other tutorials would be probably best form for this doc. It should be as short as possible, yet it should make any C++ coder, who's wondering how to make his "hello world" to work in "UPP way", happy.

I'm not sure how much this idea is reasonable, any comments/feels if you can imagine a helpful topic with such content, and what would you expect from it?
Re: Documentation and Topic++ [message #16477 is a reply to message #16475] Tue, 17 June 2008 13:40 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
mr_ped wrote on Tue, 17 June 2008 05:59

Reading about first impressions from UPP in other thread I got idea for yet another type of doc.
A "Quick reference of UPP vs C++", i.e. docs for somebody who's very familiar with common C++ (I'm not even trying to define what is common C++, I think this one will be difficult to solve), so he can quickly check for common pitfalls when using UPP.
Like description of GUI_APP_MAIN, correct way of including packages to project, NTL basics, examples of common main's + inits for applications (but not the easy Hello world stuff, but rather complex things like MT app with GUI + some network + some timer events going on, all together .. BTW a working example application with complex behavior would be nice too).

And all this focused on things which are UPP specific, with omitting/ignoring the pure C++ stuff.

This may help some C++ coders to switch to UPP more easily.

I'm checking the current Manual pages, and this stuff is pretty much all the available topics there, so having a very bare quick reference linked well with other tutorials would be probably best form for this doc. It should be as short as possible, yet it should make any C++ coder, who's wondering how to make his "hello world" to work in "UPP way", happy.

I'm not sure how much this idea is reasonable, any comments/feels if you can imagine a helpful topic with such content, and what would you expect from it?


Yes. Go for it Smile

BTW, get inspired (cz-cz only):

http://www.stdout.cz/projekty/2008/5/29/clanky/uvod-do-upp-c ast-1/

Mirek
Re: Documentation and Topic++ [message #16492 is a reply to message #16460] Wed, 18 June 2008 09:16 Go to previous messageGo to next message
Mindtraveller is currently offline  Mindtraveller
Messages: 917
Registered: August 2007
Location: Russia, Moscow rgn.
Experienced Contributor

luzr wrote on Mon, 16 June 2008 22:54

Mindtraveller wrote on Mon, 16 June 2008 14:48



It is much more important than having office-wide rich text editing system. Our task is far away from what secretaries need. Smile


Well, uhm, ok, but if we already have one? Should I start developing another editor only because rich-text is "too much"?

(And in fact, it WAS originaly developed for secretaries Smile In its second life, or maybe in the first, RichEdit is widely used in municipal agenda Smile

Mirek

Mirek, don`t get me wrong: U++ rich-text editing model is cool. All I want to say now is that for editing docs it would be more efficient to have toolbar like this:

[Common/Text] [Title] [Code] [Comment] ...

One of the buttons in switched on, others are switched off.
You should not change a lot - you just need to replace help editor`s standard formatting control with a multi-button control which is switching current text style with one of predefined types. And that`s all concerning text editing.

[Updated on: Wed, 18 June 2008 09:18]

Report message to a moderator

Re: Documentation and Topic++ [message #16493 is a reply to message #16492] Wed, 18 June 2008 09:55 Go to previous messageGo to next message
mdelfede is currently offline  mdelfede
Messages: 1307
Registered: September 2007
Ultimate Contributor
Or, even better, a page for each function, or class or whathever.
A dialog with fixed fields for input, like this :
Title : xxxxxxxxxxxxxxxxxxxxxx

Description :
xxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxx

Usage :
xxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxx

Parameters :
xxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxx

Result :
xxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxx

Caveats :
xxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxx

Example :
xxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxx

See also :
xxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxx


that's all. Click OK and you have it autoformatted in richedit or whathever you like. A button to insert links would be good also. Quick to enter documentation, not loosing time to format it.
Of course, a button to get it back into dialog for editing.
BTW, I'd prefere a doc page for one item, too... putting 30-40 items with short description in one page is not enough and time consuming to look for info, IMHO.

Max
Re: Documentation and Topic++ [message #16494 is a reply to message #16457] Wed, 18 June 2008 10:30 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
luzr wrote on Mon, 16 June 2008 20:38


Well, the effort for T++ is not that high.. however for it to work well, we absolutely need better C++ parser. And THAT is the problem.

Actually, I have restarted the work on parser this weekend. Unfortunately, with so many conflicting demands for the parser, it ain't easy...

Mirek

Well maybe we should take the demands one by one. Since you are already working on it, as far as parsers go, I think it would be better for the first upgrade to improve Assist++ and reduce the number of places where it does not work. If we fix this we can add further support with things needed for Topic++. I know that this will probably delay the work on documentation (but not by a significant amount of time), but I think that right now a better Assist++ would benefit those who already use U++ better than Topic++, and maybe even help attract new people. At times, it behaves a lot better than the one from VS6, which is still the de facto standard in some areas, and having a better parser than that is certainly going to be an asset. And then other times it outright fails.

As for the RichEdit, I don't think we need to touch it (other than maybe disable a couple of buttons). We just need an interface that allows us to manage the structures that we want to document above the standard control which is used to input the single document pages that are used right now.

PS: What dictionary formats can RichEdit handle?
Re: Documentation and Topic++ [message #16496 is a reply to message #16493] Wed, 18 June 2008 11:20 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
mdelfede wrote on Wed, 18 June 2008 03:55

Or, even better, a page for each function, or class or whathever.
A dialog with fixed fields for input, like this :
Title : xxxxxxxxxxxxxxxxxxxxxx

Description :
xxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxx

Usage :
xxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxx

Parameters :
xxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxx

Result :
xxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxx

Caveats :
xxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxx

Example :
xxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxx

See also :
xxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxx


that's all. Click OK and you have it autoformatted in richedit or whathever you like. A button to insert links would be good also. Quick to enter documentation, not loosing time to format it.
Of course, a button to get it back into dialog for editing.
BTW, I'd prefere a doc page for one item, too... putting 30-40 items with short description in one page is not enough and time consuming to look for info, IMHO.

Max



This is too long, if applied to each method.

Mirek
Re: Documentation and Topic++ [message #16497 is a reply to message #16494] Wed, 18 June 2008 11:23 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Heh, it is sort of funny how everybody apparently sees priority elsewhere Smile

For me, reference documentation is unavoidable prerequisite to anything else. Hence my fixation on improving C++ parser first...

Also, in the process, I think that the priority is to document things first and care about the "quality" later. Bad docs are better than no docs... (of course, we do not need to get to extremes here Wink

Mirek
icon14.gif  Re: Documentation and Topic++ [message #16498 is a reply to message #16497] Wed, 18 June 2008 11:39 Go to previous messageGo to next message
mr_ped is currently offline  mr_ped
Messages: 825
Registered: November 2005
Location: Czech Republic - Praha
Experienced Contributor
luzr wrote on Wed, 18 June 2008 11:23

For me, reference documentation is unavoidable prerequisite to anything else. Hence my fixation on improving C++ parser first...


I completely agree with you. Very Happy
Re: Documentation and Topic++ [message #16499 is a reply to message #16496] Wed, 18 June 2008 12:05 Go to previous messageGo to next message
mdelfede is currently offline  mdelfede
Messages: 1307
Registered: September 2007
Ultimate Contributor
luzr wrote on Wed, 18 June 2008 11:20



This is too long, if applied to each method.

Mirek


I'd say that it forces to document extensively each method... which is what we need Smile
BTW, usually when I look for help, I look for a cathegory in some index (graphics, strings, path, threading....), then inside it for the function I need.
So, a good topics "group" index, pointing to a group of related stuffs and so on. The alphabetical index is for reverse search.
Usually my problem with upp is that I don't know the name of a function that I'd like to use.... well, usually I don't ever know it it exists. It's quite less often that I know function name and I search for the purpose... that happens only when I dig inside upp code. Then, I'd like to have also some example of usage... and maybe a link to a reference project using it.

I think that we don't need all the fields filled immediately... that can be done on time while using it. We just need the skeleton to do it.
For example :
string
  string::cat()   <short description>
    string::cat()
      long desc    -\
      parameters      \ this is one page
      usage           /
      sample       -/
      .....
    string::Find()  <short desc>
    ............
image
  .....


My idea is :
1) Set up skeleton like this
2) Set up a public svn repository
3) When my svn class would be integrated on ide, use it to
extend documentation.

So, if I need something, and I don't find doc, I can add it on the fly (after searching inside upp code, maybe...).
That would be quite few effort to do like this... and docs could grow fast. After adding, just an <update svn doc> button and that would be available to all.

Your parser stuff it is important but also can be separated from it. It's needed for completion, to update doc skeleton and to quick locate stuffs from code inside docs, but it can be made independent from docs itself.

Ciao

Max
Re: Documentation and Topic++ [message #16501 is a reply to message #16499] Wed, 18 June 2008 13:22 Go to previous messageGo to previous message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
mdelfede wrote on Wed, 18 June 2008 06:05

luzr wrote on Wed, 18 June 2008 11:20



This is too long, if applied to each method.

Mirek


I'd say that it forces to document extensively each method... which is what we need Smile
BTW, usually when I look for help, I look for a cathegory in some index (graphics, strings, path, threading....), then inside it for the function I need.



Well, I think some nice fulltext works here pretty well. Actually, if I look for help (about anything), I always use google...

Mirek
Previous Topic: Task: How to read GTK/Gnome settings
Next Topic: U++ infrastructure server...
Goto Forum:
  


Current Time: Thu Mar 28 23:18:08 CET 2024

Total time taken to generate the page: 0.01108 seconds