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 » Style & T++....
Style & T++.... [message #18074] Tue, 09 September 2008 16:34 Go to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
After introducing some minor improvements, I have tried to fix Size documentation using them.

I think we can use Size as "development example" for the final style...

Mirek
Re: Style & T++.... [message #18075 is a reply to message #18074] Tue, 09 September 2008 18:16 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
Well, the ruler is a much better solution than that tab thing. But I do not like the fact that the ruler is displayed above the current paragraph, not below. Also, this way the first item has a ruler also, which is ugly. Also, you can not have an expression like: "here is the list with something: <ruler> item1". That would work with an obvious table, but with rulers as separators, it is IMO a very poor stylistic choice. It also makes "break" style redundant.

Also, "Size" and "Sizef" type description have their type name with a dark gray color. Is this part of the style?

Next step would be to make the inserted definitions obey the style. Right now a lot of manual fine tuning is needed.
Re: Style & T++.... [message #18076 is a reply to message #18075] Tue, 09 September 2008 20:35 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Tue, 09 September 2008 12:16

Well, the ruler is a much better solution than that tab thing. But I do not like the fact that the ruler is displayed above the current paragraph, not below. Also, this way the first item has a ruler also, which is ugly.



You can remove it from the first...

Another possibility is to use single paragraph as ruler.

Anyway, I must admit that this solution is much easier w.r.t. paging issues.

Quote:


Also, you can not have an expression like: "here is the list with something: <ruler> item1".



Note that even now, there is "item_next" style without ruler exactly to solve this problem....

You need this also when documenting a set of methods with single description (BTW, one more reason to use T++ instead of Doxygen).

Quote:


Also, "Size" and "Sizef" type description have their type name with a dark gray color. Is this part of the style?



No. A mistake. BTW, in the process I have introduced some bug into RichText which I then have fixed (and it caused gray in some cases) -> make sure you update your ide....

Quote:


Next step would be to make the inserted definitions obey the style. Right now a lot of manual fine tuning is needed.


Well, that is why I have started this thread Smile

Let us make it perfect and I will then try to provide tools to automate the process....

Mirek
Re: Style & T++.... [message #18080 is a reply to message #18076] Tue, 09 September 2008 23:42 Go to previous messageGo to next message
Mindtraveller is currently offline  Mindtraveller
Messages: 917
Registered: August 2007
Location: Russia, Moscow rgn.
Experienced Contributor

I`d like to add some thoughts about template. If it is appropriate.

1. I think template should contain summary table of functions. Columns: function name (hyperlink to long description), function parameters, description. Table should be divided by functional groups. And functions inside each group are to be sorted alphabetically. Talking about size, summary table of constructors would look good.
2. Template variants could be summarized into table too.
3. Long descriptions of functions should go below summary tables.
4. Halftone logo on the right-top side of page would look good IMO. If it is needed I may draw one and upload here. Couldn`t find where to set background image.

index.php?t=getfile&id=1359&private=0

Bugs? (found while editing sample help page)
-1. Strange behavour of tables with width less than 100% of page. Left & right margins are much bigger than in edit mode.
-2. Add background logo?
-3. Table doesn`t change it`s frame colour and even can`t disable frame at all.
  • Attachment: size_h.JPG
    (Size: 99.32KB, Downloaded 976 times)
Re: Style & T++.... [message #18081 is a reply to message #18080] Wed, 10 September 2008 01:50 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Mindtraveller wrote on Tue, 09 September 2008 17:42

I`d like to add some thoughts about template. If it is appropriate.

1. I think template should contain summary table of functions. Columns: function name (hyperlink to long description), function parameters, description. Table should be divided by functional groups. And functions inside each group are to be sorted alphabetically. Talking about size, summary table of constructors would look good.
3. Long descriptions of functions should go below summary tables.



IMO, this is not quite necessary. I have tried before and had always had problems distinguishing "short" and "long" description.

Moreover, table format does not work well - long singatures of methods go into more lines (at least, more likely) and are unreadable.

Mirek
Re: Style & T++.... [message #18083 is a reply to message #18081] Wed, 10 September 2008 04:20 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
I reordered the styles with HR in regard. I attached the file rather than commit it. No use committing every stylistic change until it is more stable.

So how can we make styling more easy and consistent?
By having inserted definition be formated correctly:
1. Keywords must be all colored with the keyword color. Ideally it would be chooseable and not hardcoded, but since Qtf styles are paragraph related, I don't know how to best do this.
2. Other elements like <, >, (, & can maintain their dark gray color, but most be consistent again.
3. Typenames or function names must be black and consistent.
4. Template parameters should have their own color, as green in the example.
5. After the definition, a new paragraph with the "desc" style must be created, but without two spaces on it.
6. The nest paragraph must be auto inserted with style "breakhead", which is a short space up to the HR. This style must have the next paragraph style set to "breakline".
7. The next paragraph must be inserted as "breakline" which is a HR with small font size, the same size as breakhead. These names can be changed, but "breakhead" nad "breakline", or their new names must sort lexicographically this way. The next paragraph style of breakline is "item".
8. There are two definition styles: item and class. This can be fine tuned.

Other stuff:
1. Styles like "item" should have a flag to disable spell checking.
2. In the future, the Topic++ Browser should do a substitution on styles according to a configuration dialog, to allow a bigger font size for example, or a different color scheme for the visually impaired or people with just poor LCDs where a font 10 can not be read.

Edit: attachment removed

[Updated on: Wed, 10 September 2008 04:42]

Report message to a moderator

Re: Style & T++.... [message #18084 is a reply to message #18083] Wed, 10 September 2008 04:44 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
cbpporter wrote on Wed, 10 September 2008 05:20


Other stuff:
1. Styles like "item" should have a flag to disable spell checking.


I noticed this can be achieved with language settings.
Updated doc.
Re: Style & T++.... [message #18085 is a reply to message #18084] Wed, 10 September 2008 05:00 Go to previous messageGo to next message
captainc is currently offline  captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA
Experienced Member
Quote:

I noticed this can be achieved with language settings.
Updated doc.

Ahh ha, good pick up...
Re: Style & T++.... [message #18089 is a reply to message #18084] Wed, 10 September 2008 10:42 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Tue, 09 September 2008 22:44

cbpporter wrote on Wed, 10 September 2008 05:20


Other stuff:
1. Styles like "item" should have a flag to disable spell checking.


I noticed this can be achieved with language settings.
Updated doc.



Yes, and generator should do this...

Mirek
Re: Style & T++.... [message #18091 is a reply to message #18083] Wed, 10 September 2008 11:15 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Tue, 09 September 2008 22:20

I 3. Typenames or function names must be black and consistent.



The problem is that typenames in signatures are links (and links are blue underlined).

Quote:


5. After the definition, a new paragraph with the "desc" style must be created, but without two spaces on it.
6. The nest paragraph must be auto inserted with style "breakhead", which is a short space up to the HR. This style must have the next paragraph style set to "breakline".
7. The next paragraph must be inserted as "breakline" which is a HR with small font size, the same size as breakhead. These names can be changed, but "breakhead" nad "breakline", or their new names must sort lexicographically this way. The next paragraph style of breakline is "item".



Show me in Size Smile

Quote:


8. There are two definition styles: item and class. This can be fine tuned.



Yes, there already are. Anyway, I believe we will have to find some way how to deal with that parameter list (at T++ user level).

Well, of course, the most simple way is to forget about it and describe parameters in 'desc'. I would vote for this, it leads to most dense style. Anyway, maybe we should have listing parameters as option or maybe even be able to insert them later?

Actually, inserting later makes the most sense.


Quote:


2. In the future, the Topic++ Browser should do a substitution on styles according to a configuration dialog, to allow a bigger font size for example, or a different color scheme for the visually impaired or people with just poor LCDs where a font 10 can not be read.



You can increase the font size in help browser by clicking the icon with "A" Smile

Mirek
Re: Style & T++.... [message #18092 is a reply to message #18091] Wed, 10 September 2008 11:18 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
luzr wrote on Wed, 10 September 2008 12:15


Show me in Size Smile


I think I already did. See Size.
Re: Style & T++.... [message #18096 is a reply to message #18092] Wed, 10 September 2008 13:03 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Wed, 10 September 2008 05:18

luzr wrote on Wed, 10 September 2008 12:15


Show me in Size Smile


I think I already did. See Size.



- You have left rulers everywhere. I thought you do not like it for the first elements? ("item_next" - the name can be changed, of course).

- Size_(T cx, T cy) - why is description all red?

BTW, see screenshot, maybe it does not look bad too...



  • Attachment: pic.jpg
    (Size: 13.98KB, Downloaded 415 times)
Re: Style & T++.... [message #18099 is a reply to message #18096] Wed, 10 September 2008 13:23 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
Did you check it on SVN or the attachment?
Re: Style & T++.... [message #18101 is a reply to message #18099] Wed, 10 September 2008 14:20 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Sorry, svn. Missed *second* attachment Smile

Mirek
Re: Style & T++.... [message #18112 is a reply to message #18101] Wed, 10 September 2008 20:38 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
I am mostly OK with recent Size layout.

Notes:

Maybe we should not call sections "detail", I mean instead of "Method detail" I would use simple word "Method" or perhaps "Methods".

friend T Squared(Size_ a)
Returns a Size_ with it's dimension equal to the square of the dimension of a.

is IMHO quite confusion and/or incorrect description Smile

Also, now thinking about it... Maybe it would be a good idea to "upgrade" "breakline" and "breakhead" styles to sentinels of one description. In that case, "breakhead" should be something like "section end" and "breakline" as "section begin".

This 'section' (better word needed) would be then used when description of single code item is required to delimit it.

Mirek

[Updated on: Wed, 10 September 2008 20:41]

Report message to a moderator

Re: Style & T++.... [message #18114 is a reply to message #18112] Wed, 10 September 2008 20:46 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
luzr wrote on Wed, 10 September 2008 21:38


Maybe we should not call sections "detail", I mean instead of "Method detail" I would use simple word "Method" or perhaps "Methods".


"Method" doesn't sound too English to me when followed by a list. Maybe "Methods".

Quote:


friend T Squared(Size_ a)
Returns a Size_ with it's dimension equal to the square of the dimension of a.

is IMHO quite confusion and/or incorrect description Smile


Yes, I'll fix that. Don't know what I was trying to say there Razz.

Quote:


Also, now thinking about it... Maybe it would be a good idea to "upgrade" "breakline" and "breakhead" styles to sentinels of one description. In that case, "breakhead" should be something like "section end" and "breakline" as "section begin".

This 'section' (better word needed) would be then used when description of single code item is required to delimit it.

Mirek



And how can I do that?
Re: Style & T++.... [message #18115 is a reply to message #18114] Wed, 10 September 2008 20:49 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Wed, 10 September 2008 14:46

Quote:


Also, now thinking about it... Maybe it would be a good idea to "upgrade" "breakline" and "breakhead" styles to sentinels of one description. In that case, "breakhead" should be something like "section end" and "breakline" as "section begin".

This 'section' (better word needed) would be then used when description of single code item is required to delimit it.

Mirek



And how can I do that?



Eh, that is nothing that should concern you now Smile What I said is that those two sentinel styles will be understand by code that will be processing T++ documents....

Another small note: I think Upp at the start of document is, in the best case, redundant Smile

Mirek
Re: Style & T++.... [message #18133 is a reply to message #18115] Fri, 12 September 2008 11:08 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
I am playing with the style more and more... Smile

Suggestion: Maybe only the method name and parameters should be bold? IMO, it looks better.

Mirek
Re: Style & T++.... [message #18138 is a reply to message #18133] Fri, 12 September 2008 13:16 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
I have made many fixes in T++ and tried to support "The Style".

You can try from svn. Rebuild theide, then use "Reference" template and tell me what you think Smile

Mirek
Re: Style & T++.... [message #18140 is a reply to message #18138] Fri, 12 September 2008 15:27 Go to previous messageGo to previous message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
I can see some nice progress. Unfortunately, applying the style destroy the formating for function definition, so they must be reformatted or reinserted. Small price to pay.

As for the no bolds formating, I don't know what to say: it doesn't feel wrong but it doesn't fell right either. But fine by me.

A couple of issues:
1. Latest SVN doesn't compile (under Linux). There is a _DBG_ somewhere. Sorry, I corrected it before I could take a note where it was, but is is easy to find.
2. When entering a multi line declaration, like a template one, both lines have a code reference set, so all references will have a counter of 2. This is worst in the case of classes, where clicking on a link towards them will open up a dialog letting me choose between two links that point to the same item.
3. Also, when inserting the same templated method, the second line starts with a non breaking space. That space is ugly. On the same second line, a template parameter like "T" is not green, only on the first line. I think all instances of template parameters should be colored distinctively.

And congratulations on the parser progress. I loaded up some problem code that I had by hand, and it worked! I must test all my code that had problems, but things look very promising Very Happy.

[Updated on: Fri, 12 September 2008 15:27]

Report message to a moderator

Previous Topic: SVN Folder Creation Requests
Next Topic: The very first taste of T++ icons in the left bar..
Goto Forum:
  


Current Time: Thu Mar 28 13:32:11 CET 2024

Total time taken to generate the page: 0.01480 seconds