U++ forum: Welcome to the forum

Search on this site

Search in forums

Home » Developing U++ » Documentation » Documentations and others

Show: Today's Messages :: Show Polls :: Message Navigator
E-mail to friend

Documentations and others [message #24222]

Wed, 06 January 2010 17:43

mdelfede
Messages: 1307
Registered: September 2007

Ultimate Contributor

After some time using Upp, I realized that most of my time is spent searching for doc/help and to reimplement stuffs that are already present on Upp but few/not at all documented.
So, I got a couple of ideas, maybe not so news but....

1) Export the manual in PDF/RTF format. I know, there's HTML already, but PDF is quite better for searching and indexing stuffs.
Mirek told me that Koldo is already working on this...
What's the status ? Do you need help on it ?

2) Add a "true search text" inside THEIDE. That's really a miss, each time I look inside Ctrl help page I becomes crazy !
Maybe it'll not that easy to look inside QTF, but I think it's becoming a must.

3) Last but not least.... we could join efforts and write an Upp book. It could be done on an opensource tool like Openoffice Word, for example. It could contain the docs, some step by step guides, some guided samples and so on. I'd be glad to partecipate, but we should be at least 4-5 people on it, it's a big effort.

Ciao

Max

Report message to a moderator

Re: Documentations and others [message #24223 is a reply to message #24222]

Wed, 06 January 2010 17:54

mirek
Messages: 13975
Registered: November 2005

Ultimate Member

mdelfede wrote on Wed, 06 January 2010 11:43

3) Last but not least.... we could join efforts and write an Upp book. It could be done on an opensource tool like Openoffice Word, for example. It could contain the docs, some step by step guides, some guided samples and so on. I'd be glad to partecipate, but we should be at least 4-5 people on it, it's a big effort.

My take is that book should be based on examples. Tutorials, e.g.:

http://www.ultimatepp.org/srcdoc$Core$CoreTutorial$en-us.htm l

were meant as sort of basis for such book. reference examples could be documented with T++ (we can devise some simple standard topic name for that) - later we would just gather these to form a 'book'.

Report message to a moderator

Re: Documentations and others [message #24226 is a reply to message #24223]

Wed, 06 January 2010 18:35

koldo
Messages: 3356
Registered: August 2008

Senior Veteran

luzr wrote on Wed, 06 January 2010 17:54

mdelfede wrote on Wed, 06 January 2010 11:43

BOOK:...
Yes, I have the same opinion. This way we do not need to document twice.

We have done a first 1050 pages .pdf prototype and in the programming side the things are easy. It is more a matter of structuring in a more standardized way the T++ docs.

mdelfede: Let me a day and I will prepare a "proposition" about it and other things...

TRUE SEARCH:...

Quote:

2) Add a "true search text" inside THEIDE. That's really a miss, each time I look inside Ctrl help page I becomes crazy !
Maybe it'll not that easy to look inside QTF, but I think it's becoming a must.

I have the same opinion too. Smile

Lets look for, for example, "ProcessEvents":

Ctrl class is well documented..., 44 pages, but you need to look in those 44 pages for ProcessEvents method.

Because of it I am using for help the 1050 pages pdf because it is sometimes better than our help.

Best regards
Koldo

Best regards
Iñaki

Report message to a moderator

Re: Documentations and others [message #24229 is a reply to message #24226]

Wed, 06 January 2010 19:38

mirek
Messages: 13975
Registered: November 2005

Ultimate Member

koldo wrote on Wed, 06 January 2010 12:35

Ctrl class is well documented..., 44 pages, but you need to look in those 44 pages for ProcessEvents method.

Because of it I am using for help the 1050 pages pdf because it is sometimes better than our help.

Best regards
Koldo

Ops, the problem there is that Ctrl documentation predates current state of T++, so it is not properly linked back to the code...

I have sort of forgot to do so.

Mirek

Report message to a moderator

Re: Documentations and others [message #24249 is a reply to message #24229]

Thu, 07 January 2010 12:00

mdelfede
Messages: 1307
Registered: September 2007

Ultimate Contributor

I agree, documentation (when present) is not bad at all; in particular Core and CtrlLib are well documented, besides some missing (and quite interesting) stuffs like Xml and others.

The main problem is documentation usage; to find help inside Ctrl or ArrayCtrl docs is painful.
Things thar (imho) are missing :

1- Some sort of index, both alphabetical and by cathegory.
Look for example in Ctrl docs... members are somehow grouped by cathegory, but completely scrambled alpabetically. If you look for a particular func, you must read all pages. Ditto for ArrayCtrl and others.

2- A sort of "see-also" link in each topic. That would greatly help topic and argument search.

BTW, a nice plot of class hyerarchy would be nice Smile

Ciao

Max

Report message to a moderator

Re: Documentations and others [message #24357 is a reply to message #24249]

Tue, 12 January 2010 10:01

koldo
Messages: 3356
Registered: August 2008

Senior Veteran

Hello mdelfede

uppbox/uppweb package is the one that from T++ documentations creates and uploads U++ web package.

Now it has been changed so that it also generates a big raw .pdf from that T++ doc. This part of the program is version 0, very bad so it has to be improved but well, it is the first U++ .pdf Smile

.

In http://www.ultimatepp.org/forum/index.php?t=msg&goto=243 42&#msg_24342 ("Ultimate Book") there is a proposal:

Quote:

Ultimate documentation is growing and is available in TheIde and Upp applications through Topic++ help technology.
However some of us think that there is a space for a well structured book including the documentation from the beginners side to the reference guide and appendixes with Bazaar projects. Easy to read in the introduction areas, but complete in the reference areas, with many examples and following Upp design style. All the docs in one place instead of in different help pages, so easier to be distributed.
To do it from the scratch would be an astonishing job. Not only to build it up, it has to be maintained updated.
So why not have both things at the same time ?: Based in Upp technology we can have a help system and a book with only one effort.
Join to prepare the required software and redefine the actual help pages to be compatible with the book.

This work requires a lot a coordination, so I think it is also a prerequisite to develop someting like the "Development Projects" in later post.

Best regards
Koldo

Best regards
Iñaki

Report message to a moderator

Previous Topic:	How to print documentation ?
Next Topic:	Manual page

Goto Forum:

-=] Back to Top [=-

[ Syndicate this forum (XML) ] [

] [

]

Current Time: Fri Apr 19 03:10:09 CEST 2024

Total time taken to generate the page: 0.02930 seconds