U++ forum: Welcome to the forum

Re: Documentation how-to... [message #17954 is a reply to message #17951]

Thu, 04 September 2008 13:25

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