Technical Drawings with Dia

Dia is an excellent multi-platform diagram drawing tool originally written by Alexander Larsson. Unlike Visio, it works well on Windows and Linux, and best part -- it is free.

I have been using it for a good part of the last 10 years and always enjoy its functionality.

The most unintuitive aspect of embedding Dia drawings into your Microsoft Word document or PowerPoint presentation is how to export the drawing to appropriate picture format.

Before you start working on your drawing with Dia, change drawing setting to these:

• File|Page Setup to:
  
  1. Paper Size: Letter
  2. Scaling: 45
• Under View menu item:
  
  1. Select AntiAliased
  2. Unselect Snap To Objects

Now, proceed with your drawing diagram. You can disregard the fact that it might span over multiple pages. When you are finished, go back to File|Page Setup and change Scaling of it to Fit to: 1 by 1. This will rescale your drawing to fit in a page. The reason for that is the physical constraint of Microsoft Word document which is page-oriented.

Now you are ready to export your drawing from Dia internal XML format to one of the compressed graphics formats such as JPEG, GIF, or PNG.
Open 'Export Diagram' dialog via File|Export. We are going to use PNG as graphics file format as it works well in the documents and on the web across all imaginable platforms.

The trick is to select the right PNG format out of all available which are:

• Cairo PNG (*.png)
• Cairo PNG (with alpha) (*.png)
• Pixbuf[png] (*.png)
• PNG (anti-aliased) (*.png)

The right format would be the last available, PNG (anti-aliased).

When selected, press 'Save' button and then a little dialog 'diaw.exe' pops up to let you specify PNG Export Options. This is very important as you can set Image width of your final picture.

For Microsoft Word document I set Image widht to 800 and let the dialog adjust the height.

For PowerPoint presentation, set it to 1200 and also remember to have your document orientation set to Landscape in the File|Page Setup we did at the beginning.

When you import the picture in your Word document, you can resize it to better fit the flow of your text.

How to change text font size in Microsoft MSDN 2008 Document Explorer

MSDN Library that comes with Visual Studio 2008 shows its content in Microsoft Document Explorer. The Explorer is a index/search engine with embedded Internet Explorer that shows the text.

One annoying thing that I found is the size of the text fonts. They appear really tiny on my Dell 2009W Wide Screen monitor that sports 1680x1050 resolution.

The Font Resize button on Document Explorer's own toolbar has no effect on the text font size. It took me some digging to learn how to control the font size:

1. Start MSDN Library. Wait for Microsoft Document Explorer to start up.
2. Click on Tools->Options. The Options dialog comes up. Note that its Environment/'Fonts and Colors' setting has no effect on the size of the text fonts.
   
3. Instead, select Help/'Web Browser', and click on 'Internet Explorer Options..." button.
   
   
4. Choose 'General' tab and click on 'Accessibility' button in 'Appearance' section. 
5. In 'Accessibility' dialog that pops up under 'Formatting' section enable:
   
   • Ignore font styles specified on webpage
   • Ignore font sizes specified on webpage 
   
6. Confirm to all the changes

This should effectively change the size of the text fonts in the Document Explorer.

Doxygen tips-n-tricks

Doxygen documentation parser written by Dimitri van Heesch (big thanks!) has been a part of my professional tool chest for a good part of the last ten years. Along with Graphvis (layered drawings of directed graphs), a graph visualization toolkit from AT&T and Lucent Bell Labs, it provides a quick and intuitive way of documenting your source code. Doxygen output also helped me tremendously to navigate through a maze and learn quickly the inner workings of every new project I came across in the past.

First, you need to create a configuration file, Doxyfile, either by running doxywizard GUI or from command-line with 'doxygen -g' command.

Adjust Configuration File

First thing you would want to adjust is project name/number, document encoding and output directory.

PROJECT_NAME = Granule

PROJECT_NUMBER = 1.4.0

OUTPUT_DIRECTORY = dox

DOXYFILE_ENCODING = UTF-8

TAB_SIZE = 4
FULL_PATH_NAMES = NO
HIDE_UNDOC_CLASSES = NO
HIDE_IN_BODY_DOCS = YES 
EXTRACT_ALL = YES
RECURSIVE = YES

If it is a "C" project, optimize for "C":

OPTIMIZE_OUTPUT_FOR_C = YES

For C++ project,

BUILTIN_STL_SUPPORT = YES
TEMPLATE_RELATIONS = YES

CLASS_GRAPH = YES

UML_LOOK = YES
GRAPHICAL_HIERARCHY = YES

You need to tell doxygen the file types to parse:

FILE_PATTERNS = *.h *.cpp

One thing I like about doxygen is its ability to shed some light on the function call chain in a program. For every function, it can optionally list all callers as well as call chain.

CALL_GRAPH = YES

CALLER_GRAPH = YES
REFERENCED_BY_RELATION = YES

COLLABORATION_GRAPH = YES

SOURCE_BROWSER = YES
INLINE_SOURCES = YES

ALPHABETICAL_INDEX = YES
GENERATE_TREEVIEW = YES   (side pane) 
SEARCHENGINE = YES

GENERATE_HTML = YES
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html
HTML_HEADER =
HTML_FOOTER = 
HTML_STYLESHEET = 
HTML_ALIGN_MEMBERS = YES
DISABLE_INDEX = NO

HAS_DOT = YES

DOT_IMAGE_FORMAT = png

DOT_FONTNAME = FreeSans

Cross-Referencing with Tag Files

If your project is an collection of disjointed libraries each within the boundary of its own package, you might want to enable cross-referencing with tagging feature of doxygen.

To better illustrate the concept, I will use my own software as an example. My flashcards program, Granule, internally relies on libassa (a collection of reusable shared code). In my Linux development environment, I have the following code arrangement:

Library

/path/to/libs/libassa/assa/
|
|-/dox/
|    \--html/
|         \--index.html
|--{*}.h
|--{*}.cpp
|--Makefile
\--Doxygen-lib

Application

/path/to/apps/granule/src
|
|--/dox/
|    \--html/
|         \--index.html
|--{*}.h
|--{*}.cpp
|--Makefile
\--Doxygen-app

The two paths are distinctly different. In order for the HTML documentation generated by Doxygen-app include references to the documentation generated by Doxygen-lib, we need

• configure Doxygen-lib to generate its tag file
• configure Doxygen-app to include external tag file(s) to resolve external references
  

With this in mind, let's look at the syntax of both configuration files:

--- Doxygen-lib ---

GENERATE_TAGFILE = dox/html/libassa.tag

--- Doxygen-app --

TAGFILES = /path/to/libs/libassa/assa/dox/html/libassa.tag=/path/to/libs/libassa/assa/dox/html

BTW, the path can be either absolute (as show in the example above) or relative. As you can see for yourself, the syntax of the TAGFILES parameter is a bit awkward by any standards. I would prefer instead an option of an environment variable to resolve the location of tag files which is more suited for a team of collaborative developers.

However, it gets the job done and that is what's important at the end of the day.

Happy coding!