Copyright (c) 2000-2002 toolsfactory Inc, All rights reserved.
Doc-O-Matic 2 Documentation Content 1 Introduction 1 1-1 Getting Started 1 2 Using Doc-O-Matic 2 2-1 Main Menu 2 2-1-1 File Menu 3 2-1-2 View Menu 3 2-1-3 Project Menu 4 2-1-4 Tools Menu 5 2-1-5 Help Menu 5 2-2 Doc-O-Matic Views 6 2-2-1 Info View 6 2-2-2 Symbols View 6 2-2-3 QA View 7 2-2-4 Topic View 8 2-2-5 Project Files View 8 2-2-6 Topic Files View 9 2-2-7 Message View 10 2-2-8 Topic Preview 10 2-3 Topic Editor 11 2-3-1 New Topic 13 2-3-2 Topic Properties 13 2-3-3 Select Color 15 2-3-4 Edit Link 15 2-3-5 Edit Image 15 2-3-6 Insert Table 15 2-3-7 Add Section 15 2-3-8 Find Text 15 Content 2-4 New Project Wizard 15 2-4-1 Project Wizard: Project Title 15 2-4-2 Project Wizard: Source Files 15 I
Doc-O-Matic 2 Documentation Content 2-4-3 Project Wizard: Basic Options 16 2-4-4 Project Wizard: JavaDoc 16 2-4-5 Project Wizard: Default Selection 16 2-4-6 Project Wizard: Used Filters 16 2-4-7 Project Wizard: PDF Filter Options 17 2-4-8 Project Wizard: HTML Filter Options 17 2-4-9 Project Wizard: RTF Filter Options 17 2-4-10 Project Wizard: Dictionary 17 2-4-11 Project Wizard: Advanced Options 17 2-4-12 Project Wizard: Final Page 18 2-5 Project Configuration 18 2-5-1 General Options 20 More General Options 20 2-5-2 Documentation 20 Topic Sections 21 JavaDoc Compatibility 23 Automatic Linking 23 Link Database 25 Comment Processing 25 Comment Finding 27 Functions 28 Body Source Code 28 Topic Include Path 29 Topic Processing 29 HTML Files 32 Generic Source Files 32 2-5-3 Editor 37 Text Generation 37 Topic ID insertion 37 Comment Options 38 2-5-4 Source Code Parsing Related Options 38 C++ Parser 38 Pascal Parser 39 Conditional Defines 39 II
Doc-O-Matic 2 Documentation Content Excluded Source Files 39 Source Include Path 40 Miscellaneous Parser Options 40 2-5-5 Quality Assurance 40 2-5-6 Filters 40 Common Options 41 PDF Filter Configuration 44 HTML Filter Configuration 48 Windows Online Help/RTF Filter Configuration 52 2-5-7 Default Exports 54 Default Selection 54 Missing Topic Generation 55 2-5-8 Output Options 55 Output Code Options 55 Image Paths 56 Flags 56 Dictionary 56 Colors 57 Titles 57 2-5-9 Search Options 57 2-6 Legend 57 2-6-1 Legend 57 2-7 Environment Options 60 2-7-1 Basic 60 2-7-2 Editor Options 60 Editor Backups 60 2-7-3 Source Code Editor 60 2-7-4 Default Configuration 61 2-7-5 Project Parsing 61 2-7-6 Miscellaneous 61 2-7-7 Preview Fonts 61 2-8 Dialogs 62 2-8-1 First Time Startup 62 III
Doc-O-Matic 2 Documentation Content 2-8-2 Application Problem 62 2-8-3 Doc-O-Matic Feedback 62 2-8-4 Pick Topic 62 2-8-5 Progress Bar 62 2-8-6 Filter Information Dialog 62 2-8-7 About 63 2-8-8 Symbol Filter View 63 2-9 Doc-O-Matic Tools 63 2-9-1 Command Line Compiler 63 3 Writing Documentation 65 3-1 How to document source code 65 3-1-1 Comment location 66 3-1-2 Initializer Tokens 67 3-1-3 Specifying the symbol to which a comment belongs 68 3-1-4 Comment Distance 68 3-1-5 Advanced Comment location 69 3-1-6 Description locations 70 3-2 Topics and Topic IDs 70 3-3 Generic Topics 71 3-4 Topic Groups 71 3-5 Inside Comments 71 3-5-1 Topic Structure 72 3-5-2 ASCII Formatting 75 Headlines 75 Lists and Tables 75 3-5-3 Function Parameter Descriptions 79 3-5-4 Tags 80 Formatting and Inline Tags 80 Command Tags 83 Special Tags 85 3-5-5 Sample Source Code 85 3-5-6 Characters 86 IV
Doc-O-Matic 2 Documentation Content 3-5-7 White Space Removal 87 3-6 Topic Files 87 3-6-1 DTX Files 87 3-6-2 HTML Files 88 3-7 Special Topics 89 3-8 Generic Source Code 91 4 Doc-O-Matic Examples 92 4-1 Examples: Basic 92 4-2 Examples: Autolink 92 4-3 Examples: Off Source 92 4-4 Examples: Generic Topics 92 4-5 Examples: Groups 93 4-6 Examples: Combine 93 4-7 Examples: Links and Flags 93 4-8 Examples: Formatting 93 4-9 Examples: Generic Sources 93 5 More Information 94 5-1 New in Doc-O-Matic Version 2 94 5-2 Getting Technical Support 100 5-3 Architecture 101 5-3-1 Filters 101 PDF Filter 102 HTML Filter 102 Windows Online Help/RTF Filter 102 5-4 How Do I...? 103 5-4-1 How do I document my source code so that Doc-O-Matic understands it? 104 5-4-2 How do I tell Doc-O-Matic not to remove line feeds and spaces in a certain area of text? 104 5-4-3 How do I write "<" and ">" characters so that Doc-O-Matic prints them to the output? 105 V
Doc-O-Matic 2 Documentation Content 5-4-4 How do I tell Doc-O-Matic to omit the description for a symbol declaration? 105 5-4-5 How do I link from the generated Windows Help into VCL help? 105 5-4-6 How do I link from the generated HTML Help into the MFC online help? 106 5-4-7 How do I integrate the generated HTML Help into the MSDN help system? 107 5-4-8 How do I make the topic preview display chinese 109 5-4-9 How do I prevent a certain word in a text from being autolinked? 109 5-4-10 How do I apply basic character formatting? 109 5-4-11 How do I create generic topics? 110 5-4-12 How do I give a (generic) topic a nice readable title? 111 5-4-13 How do I make an event show up as event and not as property? 111 5-4-14 How do I use flags? 112 5-4-15 How do I create group topics and build topic hierarchies? 112 5-4-16 How do I define the order of topic groups? 113 5-4-17 How do I create a link to an external help file or web page? 114 5-4-18 How do I make implementation location documenting work in Pascal? 115 5-4-19 How do I add images to my documentation? 115 5-4-20 How do I document overloaded functions? 115 5-4-21 How do I use COMBINE and ALIAS 116 5-4-22 How do I use the autolink feature and how can I create manual links? 117 5-4-23 How do I create Online Help? 118 5-4-24 How do I configure Doc-O-Matic so that it uses my language? 118 5-4-25 How do I configure Doc-O-Matic so that no in-source comments are extracted? 118 5-4-26 How do I automatically combine all overloaded functions into one topic? 119 5-4-27 How do I document function arguments? 119 5-4-28 How do I use the See Also section? 119 5-4-29 How do I document project files such as *.dsp 120 5-4-30 How do I use the version info to check for obsolete topics? 120 VI
Doc-O-Matic 2 Documentation Content 6 Doc-O-Matic Licensing and Pricing 121 6-1 Doc-O-Matic License Agreement 121 6-2 Doc-O-Matic Pricing 123 7 Index 125 VII
1-1 Doc-O-Matic 2 Documentation Introduction 1 Introduction Doc-O-Matic is a source code documentation system that makes documentation of source code very easy. It provides a powerful documentation editor that allows you to edit comments in source files as well as off-source documentation. Doc-O- Matic has an intuitive user interface for managing documentation projects. It creates powerful, fully cross-linked documentation from one source in different output formats like printable PDF, HTML Help, HTML files, Windows Help and RTF. Supported Source Code Languages Doc-O-Matic currently supports C/C++ and Delphi as native languages. Doc-O- Matic parses the source files, understanding all aspects of symbols. Besides native languages Doc-O-Matic supports virtually any other languages that have comments through the Generic Source Code ( see Generic Source Files, page 32) feature. 1-1 Getting Started Doc-O-Matic is the revolutionary answer to your source code documentation problems. It's easy-to-use and extremely powerful. If you are new to Doc-O- Matic you should read the following topics. These topics describe how to document your source for use with Doc-O-Matic: 1. How to document source code ( see page 65) 2. Topics and Topic IDs ( see page 70) 3. Generic Topics ( see page 71) 4. Topic Groups ( see page 71) If you do already know the basic principles of documentation, you can get more in-depth information about the structure of comments, about ASCII formatting and additional features such as tags: 1. Topic Structure ( see page 72) 2. Headlines ( see page 75) 3. Lists and Tables ( see page 75) 4. Function Parameter Descriptions ( see page 79) 1
2-1 Doc-O-Matic 2 Documentation Using Doc-O-Matic 2 Using Doc-O-Matic This is the application documentation of Doc-O-Matic. The Doc-O-Matic IDE consists of several views which allow you to set up and maintain your documentation project: Info View ( see page 6) Symbols View ( see page 6) Topics View ( see Topic View, page 8) Source Files View ( see Project Files View, page 8) Topic Files View ( see page 9) Project Configuration View ( see Project Configuration, page 18) Message View ( see page 10) 2-1 Main Menu This is the main menu structure of the Doc-O-Matic main menu. Some items 2
2-1 Doc-O-Matic 2 Documentation Using Doc-O-Matic have an icon, which means that they are available as buttons on a toolbar as well. 2-1-1 File Menu New Project...: Creates a new blank project. New Project Wizard...: Opens the New Project Wizard ( see page 15) to create a new project. Open Project...: Opens a previously saved project. Reopen Project: Shows a list of previously opened projects to be opened. Save Project: Saves the current project. Save Project as...: Saves the current project and lets you select a file name. Save All: Saves the editor ( see Topic Editor, page 11) content if it has changed and the project file. Exit: Quits the application. 2-1-2 View Menu Info: Shows the info view ( see page 6). Symbols: Shows the symbols view ( see page 6). QA View: Shows the QA view ( see page 7). Topics: Shows the topic view ( see page 8). View Menu 3
2-1 Doc-O-Matic 2 Documentation Using Doc-O-Matic Source Files: Shows the source files view ( see Project Files View, page 8). Topic Files: Shows the topic files view ( see page 9). Config: Shows the project configuration ( see page 18). Messages: Shows the message view ( see page 10). Previous View: Selects the previous view. Next View: Selects the next view. Toggle Editor: Shows or hides the topic editor ( see page 11). Toggle Preview: Shows or hides the topic preview ( see page 10). Toggle Legend ( see page 57): Shows or hides the legend ( see page 57). Toggle View Header: Shows or hides the header caption of the views. This can save screen space on low display resolutions. 2-1-3 Project Menu Add Source Files...: Adds one or more source files ( see Project Files View, page 8) to the project. Add Topic Files...: Adds one or more topic files ( see Topic Files View, page 9) to the project. Import Source Files...: Adds all source files ( see Project Files View, page 8) contained in a directory hierarchy to the project. Import Topic Files...: Adds all topic files ( see Topic Files View, page 9) contained in a directory hierarchy to the project. Update All: Reparses all source and topic files. Build: Generates documentation using the currently selected filter. Build All: Generates documentation using all enabled ( see Filters, page 40) filters. Check: Does the same as a build but doesn't generate documentation. Project Menu 4
2-1 Doc-O-Matic 2 Documentation Using Doc-O-Matic Configure Filter...: Opens the filter configuration for the currently selected filter ( see Filters, page 101). Show Documentation: Reopens the most recently generated documentation that was generated using the current filter. Filter Information...: Opens the filter information ( see Filter Information Dialog, page 62) for the currently selected filter. Save as default configuration...: Saves the settings of the current project as the default settings for new projects. 2-1-4 Tools Menu Application Options...: Opens the Application Options ( see Environment Options, page 60). Export symbol ID list...: Saves the symbol IDs of all symbols in the current project into a ASCII text file. 2-1-5 Help Menu Contents: Shows the contents of the Doc-O-Matic documentation. Index: Shows the keyword of the Doc-O-Matic documentation. Getting started: Shows the Getting Started ( see page 1) section. How do I...? Shows the How Do I ( see How Do I...?, page 103) section. Important Topics A collection of help topics which are very important. Release Notes: Opens the online release notes at the Doc-O-Matic web site. Send Feedback...: Opens a dialog that allows you to send an email directly to the toolsfactory support team ( see Doc-O-Matic Feedback, page 62). Product News: Opens the online news page at the Doc-O-Matic web site. Help Menu 5
2-2 Doc-O-Matic 2 Documentation Using Doc-O-Matic Doc-O-Matic home page: Opens the Doc-O-Matic home page. toolsfactory home page: Opens the toolsfactory home page. About...: Opens the about box. 2-2 Doc-O-Matic Views All Doc-O-Matic views control a certain part of a Doc-O-Matic project. Info View ( see page 6) Symbols View ( see page 6) Topics View ( see Topic View, page 8) Source Files View ( see Project Files View, page 8) Topic Files View ( see page 9) Project Configuration View ( see Project Configuration, page 18) Message View ( see page 10) 2-2-1 Info View The info view helps new users to lean the process of generating documentation using Doc-O-Matic. 2-2-2 Symbols View The symbols view shows the content of the parsed source files (the classes, members, function, etc.). Also, it shows the export state of each item. The export state depends on the configuration of the project (see Default Exports ( see page 54)). The meaning of the different symbols is described in the Legend ( see page 57). Documentation States Each symbol can have one of the following documentation states. Image Meaning documented symbol uses documentation of a member in an ancestor class symbol is undocumented Export States Each symbol can have one of the following export states Image Meaning exported Symbols View 6
2-2 Doc-O-Matic 2 Documentation Using Doc-O-Matic not exported exported due to default setting ( see Default Exports, page 54) not exported due to default setting ( see Default Exports, page 54) not documented, export disabled due to configuration setting ( see Missing Topic Generation, page 55) Popup Menu If you right click a topic, the popup windows appears: Menu Item Open Source Change export state Copy topic ID to clipboard Function Opens the source of the selected symbol using the registered application or the application set in the Doc-O-Matic's application options ( see Miscellaneous, page 61). Cycles the export state to the next value. Copies the topic ID of the current topic to the clipboard which is useful when editing topics ( see Topic Editor, page 11). Create documentation for symbol Display Creates a new topic ( see page no documentation. Lets you change the display mode. 13) for the current symbol if it has Source Lets you select a source code mode. If it's set to "Show declaration source" the source code view shows the declaration source of the symbol (regenerated by Doc-O-Matic), if it's set to "Show body source" it shows the implementation code of functions extracted from your sources. 2-2-3 QA View The QA view gives you an impression about how well your source code is documented, which areas have documentation and which have not. It shows the project as a matrix of dots. Red dots indicate symbols which do not have documentation, the other dots indicate topics which have documentation. Yellow dots indicate symbols that inherit their documentation from an ancestor symbol. The dots are grouped by files and by classes. Each group is surrounded by a border line. Note that the grouping is only visible if there is enough place on your screen to display it. When moving the mouse over a dot a hint pops up automatically, showing you the group name and the topic id of the topic. If you click a dot the preview for the corresponding topic is shown in the preview pane. QA View 7
2-2 Doc-O-Matic 2 Documentation Using Doc-O-Matic Using the popup menu you can turn off the hints and change the used color scheme. 2-2-4 Topic View The topic view shows all generic topics in the project. Generic topics are topics which are not associated with a source code symbol (classes, members or functions for example). The topic view has two display modes, the hierarchy mode which shows the group hierarchy ( see Topic Groups, page 71) and the list mode which shows an alpha sorted list of topics and groups. These modes can be switched using the popup menu. Popup Menu If you right click a topic, the popup windows appears: Menu Item Open Source Change export state Copy topic ID to clipboard Function Opens the source of the selected topic using the registered application or the application set in the Doc-O-Matic's application options ( see Miscellaneous, page 61). Cycles the export state to the next value. Copies the topic ID of the current topic to the clipboard which is useful when editing topics ( see Topic Editor, page 11). New topic Creates a new topic ( see page 13). Display Lets you set the display mode to the group hierarchy mode or the list mode. 2-2-5 Project Files View You can use the project files view to manage the source files in your project. The view only shows files actually added to the project. It does not show files that are parsed as a result of project file expansion (if you have added a whole project to the Doc-O-Matic project) or include file expansion. You can add the following source files to your project: Files *.dsp *.dpr, *.dpk Meaning Developer Studio project file. Note that the files extracted out of developer studio files depend on the file extension settings ( see Miscellaneous Parser Options, page 40) in which is part of the project configuration. Delphi project file, Delphi package project file Project Files View 8
2-2 Doc-O-Matic 2 Documentation Using Doc-O-Matic *.bpr, *.bpk *.mak, makefile* *.lst *.cpp, *.c, *.cxx, *.cc *.h, *.hpp, *.hxx *.pas, *.inc, *.int C++Builder project file, C++Builder package project file Makefiles. Note that the files extracted out of makefiles depend on the file extension settings ( see Miscellaneous Parser Options, page 40) in which is part of the project configuration. File list file. This is a simple ASCII text file that contains a list of fully qualified filenames. It is helpful if you are working with an IDE that isn't directly supported. C/C++ source files C/C++ Header Files. Note that Doc-O-Matic automatically includes include files which can be found on the include path ( see Source Include Path, page 40), so you don't need to add the header files manually. Pascal Source Files Source files with different extensions are treated like C++ source files. 2-2-6 Topic Files View You can use the topic files view to manage the topic files in your project. There can be two types of topic files: DTX files, which are ASCII text files with a simple format (the native Doc-O-Matic format), and Doc-O-Matic enabled HTML files, which are HTML files that have a special comment that identifies the topic the file documents. Learn more about non-source topics here ( see Topic Files, page 87). You can add the following topic files to your project: Files Meaning *.dtx Doc-O-Matic topic files ( see DTX Files, page 87). other Generic sources ( see Generic Source Files, page 32) added to the project. *.html, *.htm Doc-O-Matic enabled HTML files. Note that the extensions of the files recognized as HTML files can be configured using the HTML file extension option ( see File Options, page 48) which is part of the project configuration. See Also Topic Files ( see page 87), DTX Files ( see page 87), HTML Files ( see page 88) Topic Files View 9
2-2 Doc-O-Matic 2 Documentation Using Doc-O-Matic 2-2-7 Message View The message view shows messages from the system, such as informational messages about the progress of a build, warning messages indicating problems in your documentation (e.g. missing parameter documentation), or error messages which indicate that there is something going wrong when building the project. These are the types of messages that can appear in the message view: Icon Meaning A purely informational message, such as a progress message A hint message, telling you about actions taken by Doc-O-Matic which affect the generated documentation. A warning message, telling you that there is a problem in your documentation that is non-critical. An error message, telling you that there is an error which possibly makes the documentation erroneous. An fatal error message. After such a message the current operation cannot continue. Notes You can filter the messages shown in the message view by using the filter combo box at the bottom of the view. Note also that you can save the content of the message view to a file or to the clipboard and you can clear the message view using the popup menu. 2-2-8 Topic Preview The topic preview shows the currently selected topic rendered as if it would have been exported. You can use this view to verify that your sources' comments and topic files have been parsed correctly and the output will be formatted properly. Note that the actually generated output might be completely different from how a topic looks like in the preview. This is because the output depends on the used export filter ( see Filters, page 101) and the options used when exporting it. The Doc-O-Matic environment options ( see Preview Fonts, page 61) offer an option to change the fonts used in the topic preview. If you are experiencing display problems with the topic preview try changing the fonts there. Choose fonts which are capable of displaying the characters in the character set your computer is using. Notes The preview of a topic is only available if the topic is exported. Note also that you Topic Preview 10
2-3 Doc-O-Matic 2 Documentation Using Doc-O-Matic can make the preview pane displaying the topic ID ( see Topics and Topic IDs, page 70) in the title bar by using the popup window. See Also Filters ( see page 101) 2-3 Topic Editor New in Version 2 Using the topic editor you can edit the documentation of all symbols and topics. You can edit and format the text, insert links ( see Edit Link, page 15), images ( see Edit Image, page 15), lists, tables ( see Insert Table, page 15) and new sections ( see Add Section, page 15) using the toolbar or the popup menu. Regardless of whether the text is located in your sources as a comment or in a topic DTX file, the edited documentation is saved to the same location where is was read from, using the editor configuration options ( see Editor, page 37) which control - for example - the source comment characters used. Paragraph Types Using the paragraph type button you can change the type of the paragraph the cursor is located in. For normal text the "Text" paragraph type should be used, for headlines you can use the "Headline" paragraph type. Like section headlines headline paragraphs are write protected to prevent the possibility of inconsistent text formatting. If the paragraph type is set to "Spaced" any line feeds and white spaces are not removed from the text when it's rendered. If it is set to "Code" the line feeds and white spaces are not remove like in "Spaced" mode. Additionally, in the generated documentation the text is rendered using a fixed-pitch font. You can use this paragraph type for code snippets contained in your text. Editor Commands The table below explains the tool bar buttons, commands and popup menu items that are available: Button / Popup Command Shortcut Description Save CTRL-S Saves any modifications. - Copy CTRL-C Copies the current selection to the clipboard. - Cut CTRL-X, Shift-DEL Cuts the current selection to the clipboard. 11
2-3 Doc-O-Matic 2 Documentation Using Doc-O-Matic - Paste CTRL-V, Shift-INS Pastes the content of the clipboard to the current cursor position. Undo CTRL-Z Undoes the last operation. Redo Shift- CTRL-Z Undoes the last undo. Spell Check F7 Starts spell checking the content of the editor starting at the current cursor position. Bold CTRL-B Bolds or un-bolds the selected text. Italic CTRL-I Italics or un-italics the selected text. Underline CTRL-U Underlines or un-underlines the selected text. Color CTRL-O Sets the color ( see Select Color, page 15) for the selected text. Insert Link Insert Image - Insert Topic ID Insert Bulletted List Insert Numbered List Insert Table Add Section Shift- CTRL-L Shift- CTRL-I Shift- CTRL-D Shift- CTRL-N Shift- CTRL-B Shift- CTRL-T Shift- CTRL-E Inserts a link ( see Edit Link, page 15) at the current cursor position. Inserts an image ( see Edit Image, page 15) at the current cursor position. Inserts a topic ID ( see Pick Topic, page 62) at the current cursor position. Inserts a numbered list at the current cursor position. Inserts a bulleted list at the current cursor position. Inserts a table ( see Insert Table, page 15) at the current cursor position. Adds a new section ( see Add Section, page 15) at the end of the topic. - Insert Row Shift- CTRL-R Inserts a new row into a list or table below the current row. - Insert Column Shift- CTRL-C Inserts a new cell into a table to the left of the current cell. - Delete Row CTRL- ALT-R Deletes the current row of a table. 12
2-3 Doc-O-Matic 2 Documentation Using Doc-O-Matic - Delete Column - Delete Table/List CTRL- ALT-C CTRL- ALT-D Deletes the current column of a table. Deletes the entire table or list. - Change Topic ID - Delete Topic - Select Section - Delete Section - Lets you change the topic ID of the current topic. - Deletes the topic (DTX location only). - Selects the current section the cursor is located in. - Deletes the current section the cursor is located in. - Select Topic - Selects the entire topic text. - Delete Topic Content - Empties the topic's content. - Readonly - Enables or disables editing of the topic text. - Editor Options - Lets you select the fonts used in the editor. - Toggle Topic Properties Shift- CTRL-P Shows or hides the topic properties. - Properties - Lets you edit a link ( see Edit Link, page 15) or image ( see Edit Image, page 15) if the cursor is on a link or an image. 2-3-1 New Topic New in Version 2 Using this dialog you can create new documentation for a symbol or a new topic. The topic must have an unique ID ( see Topics and Topic IDs, page 70), if the group topic check box is selected the topic is a group topic (this can be changed later). The location can be one of the following the declaration location if it's a symbol the implementation location if it's a function or method for which Doc-O-Matic knows the implementation location, or a DTX topic file ( see DTX Files, page 87). 2-3-2 Topic Properties New in Version 2 Using the topic properties you can set properties like the title or the group Topic Properties 13
2-3 Doc-O-Matic 2 Documentation Using Doc-O-Matic relationship of a topic. All values that are set here are stored along with the text of the topic using the corresponding command tags ( see page 83). You can add a new property by right clicking the properties area or clicking at the Add/Remove link. This brings up a popup menu from which you can select a specific property to add. If a property value is empty (or greyed for check box properties) it is removed from the topic the next time it is save. Property Corresponds to tag Meaning Title TITLE Sets the title of a topic. Title Image Topic Order TITLEIMG TOPICORDER The title image of a topic. The topic order (default 0) that is used to sort the topic hierarchy. Groups GROUP The topic groups the topic is member of. Auto Linking AUTOLINK Lets you override the project's autolinking configuration ( see Automatic Linking, page 23) for the current topic. Source IMPLEMENTATION Lets you override the project's body source code configuration ( see Body Source Code, page 28) for the current topic. Alias Topic ALIAS A topic that supplies the entire documentation for the current topic. Alias of ALIASOF A list of topics for which the current topic supplies the entire documentation. Combine Topic Combine With COMBINE COMBINEWITH A topic that supplies the documentation (excluding declaration source) for the current topic. A list of topics for which the current topic supplies the documentation (excluding declaration source). Flags FLAG A list of short purely informational strings attach certain information to a topic, like "new in version 2". Keywords KEYWORDS A list of keywords that are added to indices when generating the output. Version Specific VERSIONSPECIFIC A version information for the current topic that allows Doc-O-Matic to decide whether or not the topic is up-to-date. Topic Properties 14
2-4 Doc-O-Matic 2 Documentation Using Doc-O-Matic 2-3-3 Select Color New in Version 2 The color dialogs allows you to choose the text color of the selected text. The dialog offers only colors defined ( see Colors, page 57) in the project configuration. You can add a new color instantly by clicking the add color button ( see Add Color, page 57). 2-3-4 Edit Link New in Version 2 This dialog lets you insert or edit a link to a certain other topic. A link can be either native or extern, if it's a native link you can click the pick button ( see Pick Topic, page 62) next to the target field which brings up the topic ID picker. Optionally you can give the link a text, if this is left empty the link text will the same as the topic ID of the target. 2-3-5 Edit Image New in Version 2 Using this dialog you can insert a new image at the given location. The combo box offers all images that can be found on the image path ( see Image Paths, page 56) of the project (bitmaps only). You should omit the file extension for the image because this allows Doc-O-Matic to use the best matching image format that are suitable for the output documentation format ( see Filters, page 101). 2-3-6 Insert Table New in Version 2 This dialog allows you to insert a new table, you can select the number of rows and columns in the table and select whether the table shall have a header row which is formatted differently. 2-3-7 Add Section New in Version 2 The add section dialog lets you add a new section to a topic. 2-3-8 Find Text New in Version 2 This dialog allows you locate a string in the editor. 2-4 New Project Wizard The New Project Wizard helps you creating a new project very quickly and sets up the basic options of your new project. The Wizard consists of 13 easy steps. 2-4-1 Project Wizard: Project Title The project title appears at different locations of the generated documentations. It should be short (no longer than 128 characters) and meaningful. 2-4-2 Project Wizard: Source Files This step allows you to add source files to the project. You can add development projects such as Developer Studio (*.dsp), Delphi (*.dpk, *.dpr) and C++Builder (*.bpk, *.bpr) projects as well as individual files such as C++ source and header Project Wizard: Source Files 15
2-4 Doc-O-Matic 2 Documentation Using Doc-O-Matic files and Delphi source files. 2-4-3 Project Wizard: Basic Options In the basic options step you can set very basic and extremely important options. These options need to be set correctly so that Doc-O-Matic can successfully identify the source code documentation in your source files. If you are in doubt about how to set an option leave as it is set by default. Comment Location: The comment location option defines where the comments in your source code are located with respect to the source code symbols (eg. function-, class- or member declarations). Comments can be located either before or after a symbol. Comment Initializers: Some documentation systems (such as JavaDoc) use special tokens in front of each comment to distinguish documentation comments from ordinary comments. If you are using such tokens you can set it using this option. 2-4-4 Project Wizard: JavaDoc JavaDoc is a widely spread documentation standard which originally came from the Java language specification but is now used to document programming languages other than Java too. Doc-O-Matic understands how to handle JavaDoc style comments, if you are using JavaDoc, switch on this option. 2-4-5 Project Wizard: Default Selection The default selection defines which symbols are exported to a generated documentation by default. Usually, all classes, structs and records, functions, types, variables, constants, macros and files are exported. You can use the check boxes to define what you want to appear in the generated documentation. Also, this step allows you to define which class members appear in your documentation. Usually public and protected symbols are exported. If you are about to create a library documentation you would probably leave private switched off, because private members are usually only implementation specific and not of interest for users of the interface of classes. If you are doing in-house documentation private member would be interesting too, so you would switch on these options. Note that, you can define the export state of each symbol individually in the symbols view ( see page 6). These settings only define the default value for the different kinds of symbols. 2-4-6 Project Wizard: Used Filters Doc-O-Matic uses an export filter ( see Filters, page 101) system to generate the documentation. Each available filter is listed in this step and you can disable certain filters, depending on which output formats you want your documentation Project Wizard: Used Filters 16
2-4 Doc-O-Matic 2 Documentation Using Doc-O-Matic to be created in. 2-4-7 Project Wizard: PDF Filter Options Using this option you can define which paper format the generated PDF file will use. 2-4-8 Project Wizard: HTML Filter Options The HTML filter options are key-options of the HTML filter configuration ( see page 48). Make HTML Help: If you have installed the Microsoft HTML Help Workshop that includes the HTML Help compiler, you can turn this option on and Doc-O- Matic will automatically generate HTML Help. Encoding: Specifies the character encoding of all generated HTML pages. This must match the locale you're in. Member Location: Specifies whether to put both class and member descriptions on one page or separate them on individual pages. 2-4-9 Project Wizard: RTF Filter Options The RTF filter options are key-options of the RTF filter configuration ( see Windows Online Help/RTF Filter Configuration, page 52). Generate Borland Style A-footnotes: If you are planning to integrate the generated Window Online help system into the Borland Delphi or Borland C++Builder online help you need to turn on this option. 2-4-10 Project Wizard: Dictionary All Doc-O-Matic filters support the generation of native-language documentation. The filters generate some words and phrases which need to be translated into the target language. These words include "Class", "Function" or "Type". Whenever a filter needs to write such a word, it will use the chosen dictionary to translate it to your desired language. To create a new translation press the "New" button, create a new file for the dictionary and use the dictionary editor ( see page 56) to create the translation. After you have finished the translation the newly created file will contain your translation. We are happy to add your translation to the standard pack of dictionaries. If you want share your translation with other users, sent your new translations to support@toolsfactory.com and we will publish it at our web site and - with your permission - we will add it to the next version's dictionary pack. 2-4-11 Project Wizard: Advanced Options Here you can set two options that can have great impact on how Doc-O-Matic parses your sources and how the generated documentation looks like: Project Wizard: Advanced Options 17
2-5 Doc-O-Matic 2 Documentation Using Doc-O-Matic Use Standard Macro File: Doc-O-Matic supports C/C++ macro expansion and ships with a standard macro file that defines many of the commonly used macros in the ATL, MFC, OWL and VCL libraries. If you use one of these libraries we recommend to use the standard macro file because it makes Doc- O-Matic better understanding the structure of your sources. Use Standard Special Topics: Special topics are used to enhance the look and feel of the generated documentations. Doc-O-Matic ships with a DTX file that defines all special topics available in Doc-O-Matic. We recommend to use that file if you do not have a customized version. 2-4-12 Project Wizard: Final Page This is the final step. It shows you an overview over the settings you have made. If you click the "Finish" button, Doc-O-Matic will close your current project (it has already been saved if it was modified) and create a new project with the settings and source files you have chosen. After this the source files will be parsed. This can take between seconds and minutes, depending on how many files you have added to your project and how many include files are included by these files. 2-5 Project Configuration An extremely important part of each Doc-O-Matic project is the project configuration. The project configuration options are organized as a hierarchical tree of option pages. The configuration is divided into 8 main areas which cover certain steps in the documentation generation process: Option Area Covers General ( see General Options, page 20) Covers general settings like project title and version. Documentation ( see page 20) Editor ( see page 37) Source Parsing ( see Source Code Parsing Related Options, page 38) Covers all options that influence the way how documentation is extracted out of source and topic files and how this documentation is interpreted. Covers all options which influence the way the how Doc-O-Matic writes edited documentation into source and topic files. Covers all options that influence the way how Doc-O-Matic interprets C/C++ and Delphi/Pascal source code. 18
2-5 Doc-O-Matic 2 Documentation Using Doc-O-Matic QA Options ( see Quality Assurance, page 40) Filters ( see page 40) Default Exports ( see page 54) Output ( see Output Options, page 55) Options that control the quality assurance features of Doc-O-Matic. Lists all output filters used by Doc-O-Matic an gives access to the output filter specific options. Settings that define which symbols and topics are exported by default. Output specific option like where Doc-O-Matic finds images and which colors are used by the documentation. Options Tree The complete options tree consists of the following pages: General More Documentation Sections Advanced Automatic JavaDoc Support Automatic Linking Advanced Link Database Advanced Processing Parameters Ignored Lines Comment Finding Advanced Topic Files Functions Body Source Include Path Topic Processing Multi Topics Variables Advanced HTML Files Generic Source Editor Text Generation Topic IDs Comments C++ Pascal Source Parsing 19
2-5 Doc-O-Matic 2 Documentation Using Doc-O-Matic C++ Options Macros Namespaces Pascal Options Conditionals Excluded Files Include Path Miscellaneous QA Options Filters PDF Document Windows Help / RTF HTML and HTML Help Default Exports Default Selection Class Members Missing Topics Texts Output Code Options Image Paths Flags Dictionary Colors Titles 2-5-1 General Options These are very basic options which are very likely to change from project to project. Project Title: The project title appears as header in the generated documentation and in other locations of the generated documentation. The actual occurrence depends on the filter used to generate the documentation. Copyright: The copyright string is used by the filters in various different places, it should contain copyright information for the generated documentation. Version: The Version information is used both by Doc-O-Matic to determine whether or not a topic is outdated. For more information please see the VERSIONSPECIFIC command tag ( see Command Tags, page 83). More General Options New in Version 2 Project source language: Select the language of source files you are using in this project. It helps export filters to create the expected output. This setting doesn't affect the way the source files are parsed but the way it is presented. For example class variables are often called "Data Members" in C++ but called "Fields" in Pascal. This setting controls how things are named. 2-5-2 Documentation The documentation options control how Doc-O-Matic finds and associates the comments with the source code symbols in your source files. Also, these options Documentation 20
2-5 Doc-O-Matic 2 Documentation Using Doc-O-Matic control the way the content of the comment blocks (the documentation) is interpreted. Doc-O-Matic divides the documentation into logical blocks of text - the Sections. Click here ( see Topic Structure, page 72) for more information about sections. Topic Sections Sections are logical areas a comment block can be divided into. Please see Topic Structure ( see page 72) for details about using sections. Also see How do I configure Doc-O-Matic so that it uses my language? ( see page 118). You can add new and delete existing sections. Each section definition consists of a unique name, a set of strings that identify that section in the source text (starters) and a set of options that control how text contained in this section is handled. The most important configuration setting if a section are the starters. These are the strings Doc-O-Matic looks for in a topic to associate a certain block of text within a comment with a certain section. When there is text at the beginning of a comment block without a section starter which associates the text to a certain section (e.g. a "Description:" starter), the text is associated with the default section. You can select any section as default section that is a standard, summary or glossary section type. See Also Topic Structure ( see page 72), How do I configure Doc-O-Matic so that it uses my language? ( see page 118) Advanced Topic Section Using these options you can control how sections are detected. Section delimiter characters: Section starters are separated from the section text by delimiter characters. Using this option you can define which characters are starter delimiters. Automatic Sections Doc-O-Matic can extract the summary out of a comment automatically by extracting the very first sentence from the topic and using that sentence as the summary. Create summary section automatically: If the option below is checked Doc- O-Matic will convert the first sentence of a topic into a summary section. This is only done if (and only if) there is no summary section in the topic and if the default section is not the summary section. Edit Section New in Version 2 This dialog lets you define the properties of a section: Documentation 21
2-5 Doc-O-Matic 2 Documentation Using Doc-O-Matic Name The name of the section, it must be unique throughout the project. Type The section type defines which kind of information the section contains: Section Type Standard Parameter Description Return Description Examples Summary See Also List Meaning Text with no special meaning. Text contains descriptions of function parameters. Text contains the description of a function return value. Text contains an example for the topic. Text contains a brief description of the purpose of the item being described. Text contains a list of topic IDs used as see also list. Ignored Text Glossary Text Text that shall be ignored by Doc-O-Matic. Text that appears as the glossary description for the topic. Declaration Source Implementation Named Link List A piece of source code that is used to for the source code representation of the topic. If the topic describes a symbol, the source in this section replaces the original source of the symbol in the output documentation. Text in this section is used for the description of the body source code ( see page 28) of functions and files. Text contains a list of topic IDs like the see also list. The first item in the list will be used as the name of the list. Options The options define how the text in the section is being processed: Option Allow Multiple Meaning Tells Doc-O-Matic that more than one sections in a topic can exist. Documentation 22
2-5 Doc-O-Matic 2 Documentation Using Doc-O-Matic Autolink Remove link feeds Remove spaces In Separate Line Enables or disables the autolinking within the section. Makes Doc-O-Matic remove line feeds. If this option is enabled, single line feeds are converted to spaces. Makes Doc-O-Matic remove unnecessary white spaces. If this option is enabled, Doc-O-Matic turns a sequence of white spaces into one single white space. This option is used by the topic editor ( see page 11) when saving a topic. If it is enabled the section headline (starter) is located in a separate line. If it is disabled, the section's text follows the starter at the same line, separated by a section delimiter ( see Comment Processing, page 25). JavaDoc Contains a list of JavaDoc tags that are associated with that section. If you are using Doc-O-Matic's JavaDoc feature ( see JavaDoc Compatibility, page 23) you can make Doc-O-Matic learn new tags by adding them to a certain section. Description Contains a description of the section's purpose. JavaDoc Compatibility JavaDoc is a popular standard for documentation comment formatting. Doc-O- Matic supports JavaDoc to be compatible with existing documentations. In contrast to JavaDoc, Doc-O-Matic does not require tags to read the content of a topic correctly. This is a one of the major advantages of Doc-O-Matic because your in-source comments remain easy-to-read. Enable support for JavaDoc: When this option is enabled, Doc-O-Matic processes JavaDoc tags. When this option is disabled, JavaDoc tags are handled like ordinary text. Note that you can add JavaDoc tags by using the section definitions ( see Topic Sections, page 21). Automatic Linking The Automatic Linking feature is one of the most sophisticated Doc-O-Matic features. When this feature is enabled (this is the default), Doc-O-Matic scans any text for link able parts and automatically creates links from words for phrases to other topics in the documentation. Documentation 23
2-5 Doc-O-Matic 2 Documentation Using Doc-O-Matic Example Automatically link text blocks: When this option is enabled, Doc-O-Matic scans any text in a topic for link able parts such as class names, function names, member names and so on. If it finds such a text it creates a link. Automatically link source code blocks: This option is equivalent to the one above with the only difference that the text is source code included in the documentation or enclosed in <CODE> </CODE> blocks. Disable auto linking for topic preview: This speeds up the project loading and project updating since auto linking is a time-expensive task. It does not affect the generated documentation. Assume you have the following source which includes the documentation comment: // This function uses function DoBar to // create its result. int Foo::Bar() { [...] } // This is the description of function DoBar. It is used by // Foo::Bar and calculates a meaningless number. int Foo::DoBar() { [...] } The text of function Bar's description references function DoBar. Since Doc-O- Matic knows both functions it can substitute the function names by links to the referenced other function. The result is totally equivalent as if you had used the <LINK TargetID> ( see Formatting and Inline Tags, page 80) tag as follows: // This function uses function <LINK DoBar> to // create its result. int Foo::Bar() { [...] } // This is the description of function DoBar. It is used by // <LINK Foo::Bar> and calculates a meaningless number. int Foo::DoBar() { [...] } Advanced Autolinking These are more advanced automatic linking options. Documentation 24
2-5 Doc-O-Matic 2 Documentation Using Doc-O-Matic Minimum autolinking word length: Doc-O-Matic applies the autolinking feature only to words which are of a minimum length. Here you can set this minimum length, where zero length means that the length checking is disabled. Banned autolinking words: The words in this list are never auto linked. Note that these words are not case sensitive. Link Database New in Version 2 Link databases are used by Doc-O-Matic to resolve link targets that are located outside of the documentation system it is generating. A link database entry contains a topic ID and a list of targets for different output formats. Link Databases are used to resolve targets in <LINK> tags ( see Formatting and Inline Tags, page 80) and when autolinking your project. Create a link database for this project: Doc-O-Matic automatically creates a link database for each project, unless you disable this option. Using this link database you can create other Doc-O-Matic projects that link into the current project. Used Link Database Files: Using this option you can add link databases of other projects. This enables Doc-O-Matic to create links into foreign documentations. Doc-O-Matic comes with two prepared Link Databases, one MFC and one VCL link database. If you use these databases Doc-O-Matic can create links into help systems of the MFC and VCL automatically. See Also How do I link from the generated HTML Help into the MFC online help? ( see page 106), How do I integrate the generated HTML Help into the MSDN help system? ( see page 107), How do I link from the generated Windows Help into VCL help? ( see page 105) Advanced Link Database Options New in Version 2 Using this option you can control the order in which Doc-O-Matic looks up targets in your documentation. If it's set to "First Native", Doc-O-Matic looks in the project's topics first, and if it doesn't find a matching target, it looks up all link databases ( see Link Database, page 25) for a matching target. If it's set to "First databases", the lookup process is the other way round. Comment Processing The comment processing options control the way Doc-O-Matic interprets certain ASCII formatted text. Changing these options changes the way certain parts (such as numbered or bulletet lists) of the documentation are interpreted and therefore changes (indirectly) the generated documentation. Documentation 25
2-5 Doc-O-Matic 2 Documentation Using Doc-O-Matic Bulleted list: These characters start an item in a bulleted list. Parameter description delimiter characters: These characters are valid delimiters between a parameter name and its description. Headline delimiter characters: A line surrounded by a pair of one of these characters is considered a headline. Tail: Any combinations of these characters are removed from the end of comment blocks and the end of sections. Table headline characters: If you underline the first row's table cells using these characters, Doc-O-Matic will interpret the row as header row. Wall Characters ( see page 86): Walls as well as top and bottom lines which may surround a comment in your sources can consist of these characters. Tabulator expansion: Tabs are expanded to this number of spaces. Ensure that it is set to the same number as in your editor, wrong settings can result in incorrectly handled ASCII formatting. List minimum indent: Minimum number of spaces a list must be indented to be recognized as a list. See Lists and Tables ( see page 75) for details about ASCII formatting of lists and tables. Parameter Descriptions Here you can set how you are describing parameters in your comments. "Single" means that you use the parameter by name only, like in c - This is the description of c i - This is the description of i "First Word" and "Last Word" can be used if you are using an declaration-like syntax like or C/C++ style const char *c - This is the description of c Delphi/Pascal style i: Integer - This is the description of i If "First Word" is selected the first word is used as the parameter name, and if "Last Word" is selected, the last word is used as the parameter name. Important: If you are using "First Word" or last word, parameter name part must not contain the parameter delimiter character. If a description of a parameter exceeds one line and is continued on new lines these new lines must not contain the delimiter character either. If you are using "First Word" or "Last Word" you can still document parameters using their names only. Documentation 26