U++ framework: Documentation » Documentation how-to...

Home » Developing U++ » Documentation » Documentation how-to...

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

Documentation how-to... [message #17607]

Fri, 22 August 2008 13:45

mirek
Messages: 14291
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

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

mirek
Messages: 14291
Registered: November 2005

Ultimate Member

Thanks for the first contribution, captainc Smile

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

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

mirek
Messages: 14291
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

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

cbpporter
Messages: 1428
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

mirek
Messages: 14291
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

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

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

cbpporter
Messages: 1428
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

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

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

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

cbpporter
Messages: 1428
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?

Attachment: AppEnv$en-us.tpp
(Size: 4.07KB, Downloaded 768 times)

Report message to a moderator

Re: Documentation how-to... [message #17959 is a reply to message #17957]

Thu, 04 September 2008 15:29

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

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

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

cbpporter
Messages: 1428
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

mirek
Messages: 14291
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

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

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

mirek
Messages: 14291
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

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

cbpporter
Messages: 1428
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

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

cbpporter
Messages: 1428
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

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 671 times)

Report message to a moderator

Re: Documentation how-to... [message #17969 is a reply to message #17968]

Thu, 04 September 2008 23:00

cbpporter
Messages: 1428
Registered: September 2007

Ultimate Contributor

No Message Body

Attachment: 02.pdf
(Size: 85.89KB, Downloaded 743 times)

Report message to a moderator

Re: Documentation how-to... [message #17970 is a reply to message #17969]

Thu, 04 September 2008 23:02

cbpporter
Messages: 1428
Registered: September 2007

Ultimate Contributor

No Message Body

Attachment: 03.pdf
(Size: 86.00KB, Downloaded 759 times)

Report message to a moderator

Re: Documentation how-to... [message #17973 is a reply to message #17966]

Fri, 05 September 2008 00:35

mirek
Messages: 14291
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

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

Re: Documentation how-to... [message #17975 is a reply to message #17974]

Fri, 05 September 2008 10:06

mirek
Messages: 14291
Registered: November 2005

Ultimate Member

captainc wrote on Thu, 04 September 2008 19:32

I'm a fan of 03.pdf.

Same here

Smile

Looks like I have to add horizontal rulers to the RichText ? Smile

Smile

Anyway, from practical standpoint, I have to repeat that for the future, we absolutely need semi-fixed structure there, so that we can display according documentation in class browser etc...

Mirek

Report message to a moderator

Re: Documentation how-to... [message #17976 is a reply to message #17975]

Fri, 05 September 2008 13:32

cbpporter
Messages: 1428
Registered: September 2007

Ultimate Contributor

luzr wrote on Fri, 05 September 2008 11:06

Same here

Smile

Looks like I have to add horizontal rulers to the RichText ? Smile

Smile

I guess it is easier than upgrading the tabling possibilities of RichEdit.

Quote:

Anyway, from practical standpoint, I have to repeat that for the future, we absolutely need semi-fixed structure there, so that we can display according documentation in class browser etc...

I'm not sure that I understand what you mean.

OK, so the documentation process isn't of to a great start, but it is still a start.

I feel that for better results, we need to have a (better) plan. I'm still busy as I announced earlier so I can't really sit down and code (maybe for very small things). But I can sit down and document. So I'll try to produce 3 documentation pages in the next week. I'll write them in open office, without any special formating, and wait for us to decide on the style. When Topic++ is a little bit more stable with the function references, we should start moving the pages to Topic++. It won't be that fun, but will go quite fast.

It would be also great if possible other volunteers that are willing to document something would say so in this thread.

My first targets are: the stuff in Defs.h and Cpu.cpp for one. Not that much work and a little help on this part maybe would clear up some confusion regarding endianess. A question here: wouldn't this be a good time to clean up Defs.h a little. There are some useful macros, but also a lot of macros which could be implemented as inlines, like MAKEWORD.

Another target is Lang. I saw a fair number of question related to how one set's the application language and related. But here I can't shake the feeling that Lang is in need of major clean-up and refactoring.

VectorMap<String, String> GetLanguage(int lang);//rename...

Rename indeed. Other stuff is commented with deprecated.

Also, judging by the way functions and LanguageInfo is implemented, I really don't see the sense of a function like:

String GetLangName(int language)
{
	return GetLanguageInfo(language).english_name;
}

It should be IMO:

LanguageInfo(language).GetName();

or at least:

GetLangInfo(language).GetName();

The question is if it is worth documenting such stuff right now, or is better to wait a little and clean up some stuff? As I said, time is a little scarce for me right now, but I could replace that time that I allocated for doc writing with refactoring time. And we could move all the deprecated function in a separate .h and gradually phase them out. Such functions that are deprecated and grouped together will eventually get so out of sync with the rest of the code base, that at a release we'll choose just to drop those files. By then everybody should have had ample time to adapt to the new API.

Report message to a moderator

Re: Documentation how-to... [message #17977 is a reply to message #17976]

Fri, 05 September 2008 14:17

mirek
Messages: 14291
Registered: November 2005

Ultimate Member

[quote title=cbpporter wrote on Fri, 05 September 2008 07:32]

luzr wrote on Fri, 05 September 2008 11:06

Same here

Smile

Looks like I have to add horizontal rulers to the RichText ? Smile

Smile

I guess it is easier than upgrading the tabling possibilities of RichEdit.

Quote:

Anyway, from practical standpoint, I have to repeat that for the future, we absolutely need semi-fixed structure there, so that we can display according documentation in class browser etc...

I'm not sure that I understand what you mean.

[quote]

Actually, the .pdf you have posted all qualify... Smile

Smile

The point is: The method documentation shall start with paragraph of its declaration, which should have "label" to connect it to the code. Then should be a paragraph with description of method and list of parameters.

Quote:

I'll write them in open office, without any special formating, and wait for us to decide on the style.

It would be a lot of work to put code labels back, I am afraid.

Anyway, I hope to fix some problems during weekend. Next week I plan a bigger assault on the problem.

.

Quote:

Another target is Lang. I saw a fair number of question related to how one set's the application language and related. But here I can't shake the feeling that Lang is in need of major clean-up and refactoring.

Yes! Alternatively, I will post you parts that are "final".

Quote:

Also, judging by the way functions and LanguageInfo is

LanguageInfo is not Wink

Wink

Mirek

Report message to a moderator

Re: Documentation how-to... [message #17978 is a reply to message #17977]

Fri, 05 September 2008 14:20

cbpporter
Messages: 1428
Registered: September 2007

Ultimate Contributor

Quote:

LanguageInfo is not

Is not what?

Report message to a moderator

Re: Documentation how-to... [message #17979 is a reply to message #17607]

Fri, 05 September 2008 15:10

mr_ped
Messages: 826
Registered: November 2005
Location: Czech Republic - Praha

Experienced Contributor

03.pdf looks best to me, although a mix 01 vs 03 would be maybe interesting for me too... 02 has too many graphical things to distract from the content itself.

Report message to a moderator

Re: Documentation how-to... [message #17980 is a reply to message #17979]

Fri, 05 September 2008 15:47

captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA

Experienced Member

Quote:

A way to change stuff like CSS is used for web pages would simplify thing a lot. Maybe some tables with interchangeable styles.

I'm just throwing ideas out, but you got me thinking about this now.
If code documentation is exported as XML, all we would need to do is use a stylesheet to either display the information locally or on the web. We could also leave it up to others who know css well to design different interfaces. Also, tools like doxygen output in XML. We may be able to leverage that fact, just like a program called Dox has (http://dox.narechk.net/index_en.html) or Natural Docs (http://www.naturaldocs.org/). Either that, or give T++ functionality to be a minimal WYSIWYG html editor? We could look at Amaya's code or even the better javascript based WYSIWYG editors.
Oh yeah, and I've used this successfully before too: http://www.doxys.dk/doxys_homepage/index.html
Anyway, just ideas that come to mind...

[Updated on: Fri, 05 September 2008 15:56]

Report message to a moderator

Re: Documentation how-to... [message #17981 is a reply to message #17980]

Fri, 05 September 2008 16:52

cbpporter
Messages: 1428
Registered: September 2007

Ultimate Contributor

I must confess that I find Dox style quite fetching and extremely easy to read. It is quite similar to style number 3, which seems to be the winner here, but the colors are more fitting.

Try and browse a little some pages <a href="http://libagp.narechk.net/manual/api/html/[main]-index.html">Here</a>. I also attached a quick mock-up of the style.

The real challenge is going to be to get topic to do that.

Attachment: 04.pdf
(Size: 43.54KB, Downloaded 660 times)

Report message to a moderator

Re: Documentation how-to... [message #17982 is a reply to message #17981]

Fri, 05 September 2008 17:15

captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA

Experienced Member

cbpporter, Can you upload your Upp styles?

Edit: Oh wait, these are OpenOffice right?

[Updated on: Fri, 05 September 2008 17:17]

Report message to a moderator

Re: Documentation how-to... [message #17983 is a reply to message #17982]

Fri, 05 September 2008 18:11

cbpporter
Messages: 1428
Registered: September 2007

Ultimate Contributor

captainc wrote on Fri, 05 September 2008 18:15

cbpporter, Can you upload your Upp styles?

Edit: Oh wait, these are OpenOffice right?

I'll try to reproduce the style in Topic.

Report message to a moderator

Re: Documentation how-to... [message #17989 is a reply to message #17983]

Fri, 05 September 2008 20:29

cbpporter
Messages: 1428
Registered: September 2007

Ultimate Contributor

This was the best I could come up with.

I was very careful not to do something to upset Topic++, and the conclusion is that it can be used (with care) even now to create the docs. Just a lot harder than it should be.

Also, I'm starting to have doubts in Qtf as a good format for large texts.

Anyway, it would be great help if we could enhance Topic++ to do the following: user creates a new documentation page, browses to some definitions and inserts them. A full template corresponding to out chosen style is generated and all all there is left to do is to fill in the description texts. Also, don't insert two spaces where one needs to insert text, because it is very annoying to delete them. And set proper style for parameters, together with the tab character (and again, no two spaces).

Attachment: AppEnv$en-us.tpp
(Size: 5.82KB, Downloaded 670 times)

Report message to a moderator

Re: Documentation how-to... [message #17990 is a reply to message #17989]

Fri, 05 September 2008 20:35

mirek
Messages: 14291
Registered: November 2005

Ultimate Member

cbpporter wrote on Fri, 05 September 2008 14:29

A full template corresponding to out chosen style is generated

Should not there be just one style?

Mirek

Report message to a moderator

Re: Documentation how-to... [message #17991 is a reply to message #17990]

Fri, 05 September 2008 20:37

cbpporter
Messages: 1428
Registered: September 2007

Ultimate Contributor

Sure.

Report message to a moderator

Re: Documentation how-to... [message #17992 is a reply to message #17989]

Fri, 05 September 2008 20:53

mirek
Messages: 14291
Registered: November 2005

Ultimate Member

cbpporter wrote on Fri, 05 September 2008 14:29

I was very careful not to do something to upset Topic++, and the conclusion is that it can be used (with care) even now to create the docs.

Smile

Quote:

Anyway, it would be great help if we could enhance Topic++ to do the following: user creates a new documentation page, browses to some definitions and inserts them. A full template corresponding to out chosen style is generated and all all there is left to do is to fill in the description texts.

If I remember well, that is what it does now (?). Except those two spaces, of course.

Quote:

Also, don't insert two spaces where one needs to insert text, because it is very annoying to delete them.

Ops, two spaces was temporary workaround that just stayed there for too long....

Quote:

And set proper style for parameters, together with the tab character (and again, no two spaces).

Again, what should be different? (except the spaces).

Mirek

Report message to a moderator

Re: Documentation how-to... [message #17993 is a reply to message #17992]

Fri, 05 September 2008 20:59

cbpporter
Messages: 1428
Registered: September 2007

Ultimate Contributor

luzr wrote on Fri, 05 September 2008 21:53

If I remember well, that is what it does now (?). Except those two spaces, of course.

Almost. I still need to get in, insert some newlines, change some fonts, etc. I would like to have a perfect template, with no housekeeping, just writing or copy pasting descriptions. Right now I spend more time adjusting formats, even when using the style drop down, which even gets it wrong often.

Quote:

Again, what should be different? (except the spaces).

The formating perfect and the tab preinserted. Right now I have to delete the spaces, press tab, and often have to switch to "default" style and then back to "item" so that my tab is picked up and formated correctly.

Report message to a moderator

Re: Documentation how-to... [message #17994 is a reply to message #17991]

Fri, 05 September 2008 20:59

captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA

Experienced Member

I added some socket documentation to the Web package in srcdoc. I may have to clean it up though to make the distinction between other parts of the web package (http, smtp, auth, etc.).

Report message to a moderator

Re: Documentation how-to... [message #18015 is a reply to message #17994]

Sat, 06 September 2008 21:05

cbpporter
Messages: 1428
Registered: September 2007

Ultimate Contributor

Documentation for Size_. Friend methods an OS dependent stuff not covered.

Attachment: Size$en-us.tpp
(Size: 8.01KB, Downloaded 624 times)

Report message to a moderator

Re: Documentation how-to... [message #18017 is a reply to message #18015]

Sat, 06 September 2008 21:17

mirek
Messages: 14291
Registered: November 2005

Ultimate Member

cbpporter wrote on Sat, 06 September 2008 15:05

Documentation for Size_. Friend methods an OS dependent stuff not covered.

Ehm, I guess you are missing svn access to commit docs...

Something to fix.

Mirek

Report message to a moderator

Re: Documentation how-to... [message #18022 is a reply to message #18015]

Sun, 07 September 2008 08:59

mirek
Messages: 14291
Registered: November 2005

Ultimate Member

cbpporter wrote on Sat, 06 September 2008 15:05

Documentation for Size_. Friend methods an OS dependent stuff not covered.

Well, it seems like we are picking some steam now Smile

Smile

Style discussion:

Size_(const�Point_<T>&�pt)
Creates a Size_ object and initializes it with a Point object.
pt.......the point object

Well, maybe the separate list of parameters is not really needed, especially if parameter names are there with different color. You use the same style in other methods:

Size_(const Point_<T>& pt)
Creates a Size_ object and initializes it with a Point object *pt*.

(besides, I would not call pt the object, but "Point value" or just "Point" Smile

Smile

Mirek

Report message to a moderator

Re: Documentation how-to... [message #18023 is a reply to message #18022]

Sun, 07 September 2008 09:00

mirek
Messages: 14291
Registered: November 2005

Ultimate Member

PS.: Interesting way how to achieve horizontal ruler Smile

Smile

Report message to a moderator

Re: Documentation how-to... [message #18024 is a reply to message #18022]

Sun, 07 September 2008 09:20

cbpporter
Messages: 1428
Registered: September 2007

Ultimate Contributor

luzr wrote on Sun, 07 September 2008 09:59

Well, it seems like we are picking some steam now Smile

Smile

Yes! I'll document the pages that I promised now, and I'll do more when Topic++ becomes better. captainc is doing great with Sql and Web. Little by little we'll get there. Maybe you could do MT one day? I'm not touching that one Razz

Razz

.

Quote:

Well, maybe the separate list of parameters is not really needed, especially if parameter names are there with different color. You use the same style in other methods:

It is harder to document such a straight forward class than a complicated one. It's harder to expree in words the obvious. I was trying to decide between being consistent and concise. But I guess it's okay to skip parameter list with such simple cases, and only use them when really needed.

Quote:

PS.: Interesting way how to achieve horizontal ruler

Yeah, it is a good stand-in, but will replace with proper HR when available. And I have no idea how it behaves when exported as html.

Report message to a moderator

Pages (2): [1 2 › »]

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

Goto Forum:

-=] Back to Top [=-

[ Syndicate this forum (XML) ] [

] [

PDF

]

Current Time: Sun Jul 05 22:56:14 GMT+2 2026

Total time taken to generate the page: 0.01403 seconds