U++ forum: Welcome to the forum

Re: Documentation of Documentation [message #32812 is a reply to message #32810]

Sun, 12 June 2011 19:41

dolik.rce
Messages: 1789
Registered: August 2008
Location: Czech Republic

Ultimate Contributor

Hi kiri

Welcome to the forum Cool

Documentation of documentation is a nice recursive problem... I'll try to sum up how the documentation works, and how it can be modified.

First some technical background: All the docs are written in Topic++, or tpp, which is U++ specific format. Each part of documentation consist of a directory, e.g. (uppsrc/Core/srcdoc.tpp/) which contains one *.tpp file for every topic. Usually there is two such directories per package, one for general documentation usually called "implementation topics" and one for the code description (classes, functions, ...) called "reference topics". All *.tpp files are written in QTF, which is U++ specific rich formatted text format. In case you wonder about the documentation available on this web site, it is the very same text as is stored in the packages, transformed to html and updated every night.

Now the interesting part comes. To edit U++ documentation, you don't actually need to know anything from the previous paragraph Wink

Theide has inbuilt editor that lets you create and manage topics as well as write the actual docs. Look for the {src,srcdoc,srcimp}.tpp entries in package files lists. If you click on them (as if opening files) an editor will show up. On its left side is a list of existing topics, right click here to add/delete/manage topics etc. At the top are several bars with formatting tools and also few handy documentation tools (e.g. code references). The actual process of writing the docs is very similar to writing anything in common rich text editor. You can add hyperlinks to any other documentation topic as well as to the internet. You can also add code reference, which associates given paragraph with a piece of code which can then be accessed from the documentation (via the red "C" icon or Alt+I) and also the other way around, from code you can access the docs (via the little green square an the left gutter at code editor).

You should also know, that if you are willing to help us by writing any kind of documentation, it is very appreciated. Even if you don't feel comfortable with our standard tools, there is many kind people on this forum which can take your notes in almost any format and convert it.

To get the code back to U++, to be available to anyone, it must be committed to the svn. Since you don't have access to the production svn repository, you can just post anything you write here in the forum, as an attachment (preferably zipped archive of the changed *.tpp files).

If you have some further questions or if I'm not clear enough, feel free to ask more Wink

Best regards,
Honza

Report message to a moderator