Do not panic. Ask here before giving up.
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
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'.
luzr wrote on Wed, 06 January 2010 17:54 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'. 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. 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
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
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 Ciao Max
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 . 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