ITauthor

I came across this really useful tool for trying out regular expressions for Visual Studio: This allows you to write your regular expression, input the text you're going to run it against and then do a match or a replace and see what the results are. Once you're happy that your regular expression matches/replaces what it's supposed to you can generate the code (in either VB or C#) and just copy it into Visual Studio. You can download this .NET app from www.gotdotnet.com

I've now finished writing up a description of how to use Phil Wright's Magic Library GUI classes for .NET to add icons to items in a menu. You can find my article at: www.itauthor.com/VisualStudio/VisualStudio-Csharp/menucontrols.html

The internet really is a wonderful thing. How else could I have found out about NDoc? What's NDoc? Well, it's this fabulous tool for turning the XML file produced by Visual Studio from ///-type comments in C# code into professional-looking documentation. I'm in the middle of documenting how to add menu control containing icons to a C# application, using Phil Wright's Magic Libary 1.7 user interface class library for .NET. As part of the page I'm writing (www.itauthor.com/VisualStudio/VisualStudio-Csharp/menucontrols.html), I wanted to include a listing of the simple example program I wrote. There must be something out there that converts C# code to HTML and does it as nicely as perltidy – see my previous entries on this (21 November and 22 November). In fact it took a lot more searching than I thought it would, but my searches eventually led to Jean-Claude Manoli's web site and the C# formatter he wrote "to learn how to use the .NET Framework's regular expressions" (www.manoli.net/csharpformat/). Seems like a lot of work to go to just to learn regexps, but, hey, I'm not complaining because the end result is a cracking good C# code to HTML convertor. Here's an example of what it outputs. My only disappointment about it is that Jean-Claude didn't provide a downloadable application version of the convertor. He did, however, provide his C# source code. The only trouble with that is that you have to know what to do with it and (guess what – I'll try not to get on my high horse here, promise!) he didn't supply any documentation to go with it to tell you what to do with the source. Well, actually, that last sentence isn't true. Jean-Claude has commented his code, so there is documentation. And that brings me to NDoc. Jean-Claude mentions on his site some of the projects he's been working on. One of them is NDoc: an open-source application that makes it easy to "create great looking C# code documentation". That caught my eye, so I followed the link to more information about NDoc and these links to other articles:

• www.squiffler.com/squiffler/article.aspx?id=1
  An article by Ollie Cornes that introduces the topic of using /// comments to produce XML source for documentation. It describes using Visual Studio's inbuilt tool for outputting web page help from the XML and then touches on NDoc. This article is a good starting point. However, it's not been designed to print out in IE (though it prints okay in Mozilla). I've produced a printable version of Ollie's article.
• www.codeproject.com/csharp/CSharpCommentingandDocs.asp
  A short article by Patrick Long, which appears on the very excellent Code Project web site. This covers some of the same ground as the previous article, but more briefly. It gives a bit more detail about NDoc.
• www.ondotnet.com/pub/a/dotnet/2002/12/09/ndoc.html
  This O'Reilly Network article ought to enthuse you to take a look at NDoc. The author, Shawn Van Ness, is a big fan of NDoc and uses it on all his .NET projects. He concludes: "With each new project I work on, I grow continuously more impressed with the flexibility and versatility of NDoc. It's saved me hundreds of hours of tedious labor engineering my own MSDN-style documentation solution, and it looks good doing it!"

Having looked at what it does, I totally agree that NDoc is a must-have application for any .NET developer who's interested in making his/her code accessible to others. There are two very smart things going on here. One of them, of course, is NDoc, which is a very clever bit of work. The best things about it are that a) it's free, and b) it works like a dream. The other smart thing is Microsoft's comments-to-XML-file functionality that makes it all possible. The important thing about so-called self-documenting software is that the end result is only as good as the quality of the comments in the code. Generally (and this is a generalisation) developers are very resistant to the idea of writing in sentences, never mind standard English. To me it seems strange how developers can get the spelling of weirdly named programming commands and functions correct, and they can use the correct syntax, and yet, despite their mastery of a programming language, they often have only a rudimentary grasp of the English language – and I'm talking about English-speaking programmers here. Anyway, NDoc is a great piece of work and I heartily recommend it to you. If you want to try it out, download the source code for Jean-Claude Manoli's C# formatter from www.manoli.net/csharpformat/, then download NDoc from SourceForge (http://ndoc.sourceforge.net/download.html – I chose the web-based .exe downloader for NDoc 1.2). Run the installer. It's a quick install and you don't have to restart the computer. You will probably also want to download the Visual Studio .NET Help Integration Kit from the MSDN web site (if this link doesn't work, go to msdn.microsoft.com/library and search for "VSHIK"). It's is a 6.5MB download, but you need it to produce Miscrosoft Help 2 help from NDoc. (NDoc's default output is MSDN-style help.) Then open Jean-Claude Manoli's C# formatter solution in Visual Studio .NET. Right click on the project in the Solution Explorer and in the left pane of the Property Pages dialog box, click Configuration Properties. Notice that in the Outputs section, there's a property called XML Documentation File. This is set to CSharpFormat.xml. This is the XML documentation file that Visual Studio will produce from the code (including the comment lines beginning ///). Build the project and browse to the project directory in Windows Explorer. Open up CSharpFormat.xml in a web browser. You'll see that Visual Studio has done some clever stuff. It's not just a dump of all the /// lines. Next, start up NDoc (e.g. \NDoc\bin\.net-1.1\NDocGui.exe). Click Add. In the dialog box, use the browse buttons and Open dialog boxes to add \obj\debug\CSharpFormat.dll as the Assembly Filename, and \CSharpFormat.xml as the XML Doc Filename. Click OK. In the NDoc window, click the Namespace Summaries button. Add a description of the Manoli.Utils.CSharpFormat namespace. Click OK. Click the Build Documentation button: On my machine it takes less than 10 seconds to build the documentation for this class library. Click the View button. The finished product looks like this. You can choose to output in other formats (e.g. HTML Help or as web pages) if you prefer. I'd say that was bloody marvellous. Hats off to everybody on the NDoc team!

I may be missing something, but I find it hard to credit that Visual Studio doesn't include an easy way to add icons to menu items. I'm playing around with C#, creating Windows apps and all I want to do is have the standard icons beside the File > New and File > Open menu items. Creating the menu bar and its contents is very easy, but there seems to be no easy way to add icons, and MSDN is unhelpful on the solution. I found a potentially helpful article at: http://www.csharphelp.com/archives2/archive416.html but it's only helpful if you're an experience C# programmer – it's way over my head! I'd have thought that so many Windows app use these standard menu items, Visual Studio would add the icons, standard shortcuts and Alt key combinations by default. It's such a huge, complex program, I'm amazed they didn't think about adding an easy method of adding menu item icons. However, having said all that, I've just noticed that IE doesn't use icons for File > New and File > Open, it only uses them for pages and directories in the Favorites menu. Weird!

I installed Visual Studio .NET 2003 last night. It took forever to install and by the time it finished I was too knackered to do anything other than check it was working. But I'm now ready to try my hand at a bit of C# programming. Why am I even thinking about meddling with C#? It may seem a little dumb because I'm a technical author. I don't need to be able to code C#. But the reasons are historical. In 1989 I was studying publishing and I needed a word processor. I bought myself an Amstrad PCW and fairly soon discovered that what I'd thought was just a glorified typewriter was actually a computer. It ran on the CP/M operating system and had a pretty good version of BASIC called Mallard BASIC. I used this to write simple games. The best of these was a program I called Chomp, which was inspired by PacMan. The trouble was that the more features I added to Chomp (different levels and configurable settings) the slower it ran. I found out about C and it immediately seemed that a compiled program would obviously run must faster than an interpreted program. So I bought a copy of C for the PCW and started learning how to code in C. Straight away I was impressed by the way C helped you to write logically structured programs. I discovered the beauty of functions, and realised what a mess you can get yourself into with BASIC. However, I then graduated and got a job and started a family and got married - all at about the same time - and stopped playing around with programming for several years. Then I quit the job I was doing, bought myself a computer and started freelancing. Now that I had a computer again I got back into coding. First I wanted to create an Access database for my business, so that involved learning how to use Visual Basic and learning more about database systems. Then I wanted to have my own website, so inevitably I came to know Perl. Perl has been my programming language of choice for the last few years. It was originally specifically designed for working with text, so it's my kind of language. It makes sense to me and I find it easy to use. I like the fact that you don't have to worry about what type of data you assign to a variable, Perl figures it all out for you, and things are labelled with $, %, @, # so that you can see what they are at a glance. But C was always there in the background as my first serious programming language. Over the summer I bought a C book for the first time since I bought the Kernighan and Ritchie book all those years ago, and I took it on holiday with me, with my laptop. I didn't plan to do any coding, but one night I thought I'd recreate a program I first wrote back in 1990, I think. It was the classic sentence builder program. You supply it with arrays of nouns, verbs, adverbs, adjectives, prepositions and conjunctions, and it churns out random, silly, but syntactically correct, sentences. The kids had great fun running it and plugging in new words. And I felt that it was in some way educational for them - learning a little bit about grammar. Plus I was chuffed that I could still write C code. So that's pretty much why I'm interested in C#. I pricked up my ears when I first heard about it a couple or so years ago, and I'd like to have some level of proficiency in a language other than Perl. Perl is always going to be more useful to me than C# - just because of what I do for a living and what Perl is very good at doing - but it would be nice to have a second string to my programming bow. Needless to say, I've been reading up on the subject. I came across this useful website: http://www.csharpfriends.com