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++ » Documentation » Documentation how-to...
Documentation how-to... [message #17607] Fri, 22 August 2008 13:45 Go to next message
mirek is currently offline  mirek
Messages: 14255
Registered: November 2005
Ultimate Member
Well, I think we need to clear several issues concerning documentation contributions...

First of all, you are supposed to work with three "T++ groups"

src - this group is dedicated to *REFERENCE* documentation. Topics there should be linked with the code

srcdoc - this is intended for tutorials, explanations etc...

srcimp - this is to describe implementation of things

Now, these groups are always hosted in some package and they are ".tpp" subdirs.

On infraserver there is crond script that lists the whole tree and grants write access to all directories ending with .tpp.

Note that it is not possible to create a generic pattern in authorization file for this.

One nasty implication is that you CANNOT create .tpp directories. Sorry, we do not know how to do that.

So from the practical standpoint: If you want to add e.g. SQL tutorial, you will add this (most likely) to "Sql" package as "srcdoc" group. If there is no .tpp directory yet in svn, you will get authorization error. In that case please just ask in the forum for directory to be created (I know, this is a bit stupid).

Mirek

Report message to a moderator

Re: Documentation how-to... [message #17609 is a reply to message #17607] Fri, 22 August 2008 13:54 Go to previous messageGo to next message
captainc is currently offline  captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA
Experienced Member
Please create all src, srcdoc, srcimp folders in 'Sql', 'Web', and 'Web/SSL' packages.

Report message to a moderator

Re: Documentation how-to... [message #17709 is a reply to message #17609] Wed, 27 August 2008 10:49 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 14255
Registered: November 2005
Ultimate Member
Thanks for the first contribution, captainc Smile It seem the process has finally begun....

Small notes:

- make sure you have a title, otherwise it looks bad in Help browser. The title is the first editfield at the top of toolbar. (I have added titles for contributed topics already).

- this code

while(sql.Fetch()){

    Cout() << Format("Row: %s %s %s \n", \

			    AsString(sql[NAME]), \

			    AsString(sql[BIRTH_DATE]), \

			    AsString(sql[NUM_CHILDREN]));

}


can be also written as

while(sql.Fetch()){

    Cout() << "Row: " << sql[NAME]
           << ' ' << sql[BIRTH_DATE]
           << ' ' << sql[NUM_CHILDREN] << '\n';

}


(not sure what form in this article is better...)

Mirek

Report message to a moderator

Re: Documentation how-to... [message #17737 is a reply to message #17709] Wed, 27 August 2008 18:43 Go to previous messageGo to next message
captainc is currently offline  captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA
Experienced Member
No problem, more to come soon. Good job on the automatic updating of the site too. One thing I think would be really useful is web interface like the one from gotapi.com where you have the tree-view list on the left with a search and the documentation in the main content area. It allows for easy navigation.

Quote:

(not sure what form in this article is better...)

Hmm, good question. I wrote it that way to be a little more verbose and show off some of the other functions available. The implicit way may be better for beginners though; it is definitely simpler to read. I could try to link to the proper documentation for Format, and I guess I should at least explain why they would use AsString; beginners may not understand the Value type.

Report message to a moderator

Re: Documentation how-to... [message #17751 is a reply to message #17737] Wed, 27 August 2008 23:51 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 14255
Registered: November 2005
Ultimate Member
captainc wrote on Wed, 27 August 2008 12:43

No problem, more to come soon. Good job on the automatic updating of the site too. One thing I think would be really useful is web interface like the one from gotapi.com where you have the tree-view list on the left with a search and the documentation in the main content area. It allows for easy navigation.



Well, uppbox/uppwww is all yours Smile

Mirek

Report message to a moderator

Re: Documentation how-to... [message #17951 is a reply to message #17751] Thu, 04 September 2008 10:32 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1427
Registered: September 2007
Ultimate Contributor
I decided to sit down and write a documentation page to see how hard it is and how Topic++ could be improved.

So actually writing the content is not that hard, but formatting the page is. It takes a lot more time when compared to filling in the content.

First some issues:
1. The text in Topic++ is too large. Just in the editor. When previewing the page, it is rendered with the normal size for the font that was given.
2. When I insert a table and drag it's left side a little to the left in the editor, in the preview mode the table position and size is all wrong.
3. Copy pasting from Topic++ to OpenOffice inserts some extra characters. I guess it is because of hidden formating fields or something.

Also some interface issues:
4. Insert table does not remember your previous options. I am not going to insert 10 different types of tables in a documentation page because of consistency. So if the default is not good, I have to change the options for each table.
5. Neither does Query nor Hyperlink remember my last position.
6. Inserting a function definition with Query kills my paragraph indent.
7. Inserting a function definition with Query will add String with ::String hyperlink, which points nowhere. Changing it is hard because you have to navigate to Core/src/String for every item.

And of course:
8. I know this came up before, but "src" and "srcdoc" have got to go. Why not rename them to "Reference" and "Manual" or something. Also, if you really want to keep these cryptic names, at least use capital letters. In a tree list there is nothing more unaesthetic that having a lower case leaf between full English text leaves, i.e. "Used Packages/Core/srcdoc/Doing some neat stuff".
9. And these 3 categories are not necessarily the best ones. The example of a possible documentation page that I attached does not fit that well in src, because it is just a bunch of functions with the title of the page and their logical connection the only thing that links them together. It does not fit in srcdoc, because it more like a reference.

Also, after creating this page, I though about a different layout. But manually changing it is tedious. A way to change stuff like CSS is used for web pages would simplify thing a lot. Maybe some tables with interchangeable styles.

Here is a test documentation page. It is not complete and uses some weird colors for headers. It is just a test. But we should settle on the style of a documentation page.

Edit: removed old attachment.

[Updated on: Thu, 04 September 2008 15:31]

Report message to a moderator

Re: Documentation how-to... [message #17954 is a reply to message #17951] Thu, 04 September 2008 13:25 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 14255
Registered: November 2005
Ultimate Member
I will try to fix these issues asap, anyway, here are some hints for now:

cbpporter wrote on Thu, 04 September 2008 04:32


1. The text in Topic++ is too large. Just in the editor. When previewing the page, it is rendered with the normal size for the font that was given.



You can make it smaller but making the view less wide. Klick on "tool" icon on the right side of ruler.

Quote:


2. When I insert a table and drag it's left side a little to the left in the editor, in the preview mode the table position and size is all wrong.



Well, there is a sort of problem as the editor works in "page" mode (reflecting actual page is it would be printed), while help browser works in "fit mode" (basically rescaling page down to pixels and then use current view as "page").

I guess it needs some more thinking and work...

Quote:


3. Copy pasting from Topic++ to OpenOffice inserts some extra characters. I guess it is because of hidden formating fields or something.



Here I would need more details. Host platform info and some text that does this at least Wink

Quote:


7. Inserting a function definition with Query will add String with ::String hyperlink, which points nowhere. Changing it is hard because you have to navigate to Core/src/String for every item.



Just a hint: You can insert more than single method - use shift+click.

Quote:


8. I know this came up before, but "src" and "srcdoc" have got to go. Why not rename them to "Reference" and "Manual" or something. Also, if you really want to keep these cryptic names, at least use capital letters. In a tree list there is nothing more unaesthetic that having a lower case leaf between full English text leaves, i.e. "Used Packages/Core/srcdoc/Doing some neat stuff".



Well, IMO, it would be nice if it is single C++ identifier (I can imagine that it somewhat reflects during .tpp inclusion in the future).

Other that, Reference and Manual (and Implementation?) sounds good. appdoc - Resources? (Well, in this case there will be some fixing of code, but I am gona sacrifice it).

Quote:


9. And these 3 categories are not necessarily the best ones. The example of a possible documentation page that I attached does not fit that well in src, because it is just a bunch of functions with the title of the page and their logical connection the only thing that links them together.



IMO, enclosed document is obvious case of src "Reference".

Quote:


Also, after creating this page, I though about a different layout. But manually changing it is tedious. A way to change stuff like CSS is used for web pages would simplify thing a lot. Maybe some tables with interchangeable styles.



Well, there are paragraph styles and stylesheets. Plus, stylesheets can be reapplied to whole groups.

Personally, I would stay with the simple style presented in Core/src/algo (and others). Besides, this is the format I will expect in future T++ enhancements.

Note: Your .tpp is old format. This is only a little problem, conversion is automatic, but still, it would be better to create docs in freshly compiled ide Smile

Mirek

Report message to a moderator

Re: Documentation how-to... [message #17957 is a reply to message #17954] Thu, 04 September 2008 14:00 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1427
Registered: September 2007
Ultimate Contributor
luzr wrote on Thu, 04 September 2008 14:25


You can make it smaller but making the view less wide. Klick on "tool" icon on the right side of ruler.


Oops, I didn't notice that it had zoom Embarassed. Good to know and nice feature. But I noticed that zoom dialog does not have an option to use "real" size, only proportional. Could this be added in the future (also useful for a very imprecise print preview).

Quote:


Well, there is a sort of problem as the editor works in "page" mode (reflecting actual page is it would be printed), while help browser works in "fit mode" (basically rescaling page down to pixels and then use current view as "page").

I guess it needs some more thinking and work...


I'll just avoid scaling tables until a solution comes up.

Quote:


Here I would need more details. Host platform info and some text that does this at least Wink


U++ 2008.1, openSuse, rpm install, text is the one I attached, copied directly from "editor" mode.

Quote:


Just a hint: You can insert more than single method - use shift+click.


I'm aware of that. I still have to manually change the hyperlink of all classes.

Quote:


Other that, Reference and Manual (and Implementation?) sounds good. appdoc - Resources? (Well, in this case there will be some fixing of code, but I am gona sacrifice it).


Yes, these names sound good and are English.

Quote:


Personally, I would stay with the simple style presented in Core/src/algo (and others). Besides, this is the format I will expect in future T++ enhancements.


I'll try to mimic better that style. Still, I would like to use indentation and colored headers plus a small description on al pages, with either class hierarchy for class References, or location with bunch of functions,to make the text more easy on the eye, to give it structure and make it more manual find friendly. I'll post later an updated .tpp with changed style which also tries to use more predefined styles.

Quote:


Note: Your .tpp is old format. This is only a little problem, conversion is automatic, but still, it would be better to create docs in freshly compiled ide Smile


Well, since this documentation was mean to be included after styling issues have been settled on, I wanted to have a stable base so I used the 2008.1 rpm. This is what I got. Should I build a new ide from svn?

Report message to a moderator

Re: Documentation how-to... [message #17958 is a reply to message #17957] Thu, 04 September 2008 14:43 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1427
Registered: September 2007
Ultimate Contributor
Here is an updated file which uses you styles as much as possible. Not sure about the tables, but better than just a simple enumeration.

New issues:
1. After selecting "param" style for my params (which sometimes I have to do more than once), I get a varying size of the dots that make out that doted big tab character that separates the parameter name from it's description.
2. Setting an "after" space in points for a table causes again huge misalignments. I guess it is related to other table issue.
3. How can I enable spell checking. Do I need a dictionary or something?

Report message to a moderator

Re: Documentation how-to... [message #17959 is a reply to message #17957] Thu, 04 September 2008 15:29 Go to previous messageGo to next message
mr_ped is currently offline  mr_ped
Messages: 826
Registered: November 2005
Location: Czech Republic - Praha
Experienced Contributor
Quote:

Well, since this documentation was mean to be included after styling issues have been settled on, I wanted to have a stable base so I used the 2008.1 rpm. This is what I got. Should I build a new ide from svn?


So 2008.1 is already obsolete? And there's no more release planned for 2008? Very Happy
Mirek: I think some fast (ahead of xmess) 2008.2 would be good in such case.. what about taking 2008.1, fixing just the T++ stuff, and releasing 2008.2? Oh, the C++ parser ruins that. Sad
Very unlucky status.

Report message to a moderator

Re: Documentation how-to... [message #17961 is a reply to message #17959] Thu, 04 September 2008 21:51 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1427
Registered: September 2007
Ultimate Contributor
OK, I find Topic++ barely usable. You can't hit backspace without destroying the previous paragraphs formating. When copy & pasting multiple paragraphs, it sometime forgets the style of some of them, or it does not forget it but does not render it correctly and I have to change the style to something else and back. And forget about doing this for and “item” (those links to function declarations) because you get a dangling item out of it. And forget about copy pasting or cut pasting items. Most of the time I'm left with a grayed out function definition, other times if I click query I see that my function has 2-3 references, even though it is no longer contained anywhere. Right now I'm stuck with most counters set to 2, even though most of the functions are no longer there.

Table properties list tho color pickers with the label "color". Also you can't choose a border color for an individual cell. In "view" mode there are buttons without tooltips. And why can't I select anything out of a table in view mode. And other minor stuff I have forgotten.

I guess I'll have to wait for some of Topic++'s issues to be fixed. But when that happens I'll document all the functions and classes from Core that are not in any of groups (groups like Container, Concretes, Other Files, etc.).

Report message to a moderator

Re: Documentation how-to... [message #17964 is a reply to message #17957] Thu, 04 September 2008 22:00 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 14255
Registered: November 2005
Ultimate Member
cbpporter wrote on Thu, 04 September 2008 08:00

luzr wrote on Thu, 04 September 2008 14:25


You can make it smaller but making the view less wide. Klick on "tool" icon on the right side of ruler.


Oops, I didn't notice that it had zoom Embarassed. Good to know and nice feature. But I noticed that zoom dialog does not have an option to use "real" size, only proportional. Could this be added in the future (also useful for a very imprecise print preview).



Sigh... What is the "real size"?

Quote:


Quote:


Personally, I would stay with the simple style presented in Core/src/algo (and others). Besides, this is the format I will expect in future T++ enhancements.


I'll try to mimic better that style.



You do not have to try hard, that style is produced by T++ Smile

Quote:


Still, I would like to use indentation and colored headers plus a small description on al pages, with either class hierarchy for class References, or location with bunch of functions,to make the text more easy on the eye, to give it structure and make it more manual find friendly.



Anything unrelated to actual code links (I mean, method/description/parameters) is definitely possible.


I'll post later an updated .tpp with changed style which also tries to use more predefined styles.

Quote:


Well, since this documentation was mean to be included after styling issues have been settled on, I wanted to have a stable base so I used the 2008.1 rpm. This is what I got. Should I build a new ide from svn?


Yes.

Anyway, I have also found that for some mysterious reasons, links back to the code are now missing in existing T++.

I shall investigate soon.

Mirek

Report message to a moderator

Re: Documentation how-to... [message #17965 is a reply to message #17961] Thu, 04 September 2008 22:04 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 14255
Registered: November 2005
Ultimate Member
cbpporter wrote on Thu, 04 September 2008 15:51

You can't hit backspace without destroying the previous paragraphs formating.



Just like in most word-processors. Hitting backspace concatenates paragraphs, means you have to decide the style of result. It is logical that the style of paragraph you are in is chosen.

Quote:


When copy & pasting multiple paragraphs, it sometime forgets the style of some of them, or it does not forget it but does not render it correctly and I have to change the style to something else and back. And forget about doing this for and “item” (those links to function declarations) because you get a dangling item out of it. And forget about copy pasting or cut pasting items. Most of the time I'm left with a grayed out function definition, other times if I click query I see that my function has 2-3 references, even though it is no longer contained anywhere. Right now I'm stuck with most counters set to 2, even though most of the functions are no longer there.

Table properties list tho color pickers with the label "color". Also you can't choose a border color for an individual cell. In "view" mode there are buttons without tooltips. And why can't I select anything out of a table in view mode. And other minor stuff I have forgotten.

I guess I'll have to wait for some of Topic++'s issues to be fixed. But when that happens I'll document all the functions and classes from Core that are not in any of groups (groups like Container, Concretes, Other Files, etc.).


Well, definitely looks like some work to do Wink

Mirek

Report message to a moderator

Re: Documentation how-to... [message #17966 is a reply to message #17965] Thu, 04 September 2008 22:15 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1427
Registered: September 2007
Ultimate Contributor
Quote:


Just like in most word-processors. Hitting backspace concatenates paragraphs, means you have to decide the style of result. It is logical that the style of paragraph you are in is chosen.


Yes, sure, merging is OK. But not when my current paragraph is empty. If I have and extra new line, I have to go one line up and hit delete to not cause the merge of my current empty paragraph with one full of text.

Quote:


Sigh... What is the "real size"?


Well, in editor mode, it would be nice to be able to define a paper size.

Report message to a moderator

Re: Documentation how-to... [message #17967 is a reply to message #17966] Thu, 04 September 2008 22:20 Go to previous messageGo to next message
captainc is currently offline  captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA
Experienced Member
Write it in open office and post it here. I'll format it and upload to svn. We just need to get the stuff written down; we cannot wait till T++ is perfect.

Report message to a moderator

Re: Documentation how-to... [message #17968 is a reply to message #17967] Thu, 04 September 2008 22:59 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1427
Registered: September 2007
Ultimate Contributor
captainc wrote on Thu, 04 September 2008 23:20

Write it in open office and post it here. I'll format it and upload to svn. We just need to get the stuff written down; we cannot wait till T++ is perfect.

I might just do that for now, but I wouldn't want to have someone do the hard work, when the computer is perfectly capable of doing it (or it will be someday Smile).

So I thought that for starters we should settle on a style. I posted 3 different styles. Such styling should definitely be handled one day by Topic++ without me going in and editing the file. First style is the classic one, used in documentation. The second is something more like I would like to have, but there is still a lot of tweaking. This style maybe should be updated to the JavaDoc style. I like this style and with slight tweaks could be made more C++ friendly. Third is a variant of two.

These are just samples. If anybody has any great ideas, please post a mock-up. But I think that the classical flat style, with a bunch of text just thrown at you must go.
  • Attachment: 01.pdf
    (Size: 83.88KB, Downloaded 554 times)

Report message to a moderator

Re: Documentation how-to... [message #17969 is a reply to message #17968] Thu, 04 September 2008 23:00 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1427
Registered: September 2007
Ultimate Contributor
No Message Body
  • Attachment: 02.pdf
    (Size: 85.89KB, Downloaded 620 times)

Report message to a moderator

Re: Documentation how-to... [message #17970 is a reply to message #17969] Thu, 04 September 2008 23:02 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1427
Registered: September 2007
Ultimate Contributor
No Message Body
  • Attachment: 03.pdf
    (Size: 86.00KB, Downloaded 605 times)

Report message to a moderator

Re: Documentation how-to... [message #17973 is a reply to message #17966] Fri, 05 September 2008 00:35 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 14255
Registered: November 2005
Ultimate Member
cbpporter wrote on Thu, 04 September 2008 16:15

Quote:


Just like in most word-processors. Hitting backspace concatenates paragraphs, means you have to decide the style of result. It is logical that the style of paragraph you are in is chosen.


Yes, sure, merging is OK. But not when my current paragraph is empty.



Could be a good point. I will check with openoffice and if it behaves this way, I can adopt RichEdit too...

Mirek

Report message to a moderator

Re: Documentation how-to... [message #17974 is a reply to message #17970] Fri, 05 September 2008 01:32 Go to previous messageGo to previous message
captainc is currently offline  captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA
Experienced Member
I'm a fan of 03.pdf. I like how the colors separate the sections. I don't like the borders around everything in 02.pdf though.

Report message to a moderator

Previous Topic: The very first taste of T++ icons in the left bar..
Next Topic: Notes on using T++ (comment on singals)
Goto Forum:
  

[ Syndicate this forum (XML) ] [ RSS ] [ PDF ]

Current Time: Fri Apr 25 19:05:26 CEST 2025

Total time taken to generate the page: 0.00832 seconds
.:: Contact :: Home ::.

Powered by: FUDforum 3.0.5.
Copyright ©2001-2013 FUDforum Bulletin Board Software