In my previous posts I discussed how you could create printable documentation from SQL Doc. In this post, I want to discuss how you can customize the front cover of the documentation. By default, the output of the Word cover will look like this.

Within the SQL Doc installation directory (C:\Program Files\Red Gate\SQL Doc 2\), there is a style directory.  This style directory contains different artefacts used when generating the documentation, within the Word folder there is a file called DefaultCoverPage.doc. This is just a standard Word document, with placeholder fields used to insert the appropriate information for the document during generation. You can now customize the cover as you see fit such as including your own information, logo etc. For example, below I’ve moved the Red Gate logo, added an additional title, changed the size and colour of the title while moving the created date time to the footer of the page.

The next time a Word document is generated on that machine the new cover page will be used.

A ‘word’ of warning for users on Vista, you will need to run Word as Administrator, or save the customized cover page to a different path and copy the file back as Program Files is a restricted location which requires elevated permissions to write too.

I would also recommend taking a copy of the original cover in case you want to revert back. If you do accidentally change the cover page without taking a backup, delete the file DefaultCoverPage.doc and repair the installation via the control panel. This will restore the application to the original install files.

Labels: Red Gate

In my previous post I explained how you can use SQL Doc 2.0 to document ASPNetDB and produce a Microsoft Word document. One huge advantage of having it in Microsoft Word is that it can be exported to a number of different formats very easily – for example PDF or XPS.

To do this from Word 2007, the first step is to download the Word 2007 Save as PDF \ XPS addin from here - http://www.microsoft.com/downloads/details.aspx?FamilyID=4d951911-3e7e-4ae6-b059-a2e79ed87041&displaylang=en.  After installing this you will have a new option within your Save As menu.

After producing your database documentation as a Document, simple select this option to save the document.  It will ask you where you wish to save the document and the format it should be saved as. You can select between PDF, or Microsoft’s XPS Document – both work exactly perfectly, it’s just personal choice.

Once you have selected your location, the document will open. This is how the PDF document looks, which you can download from here

This is how the XPS document looks within IE8, which you can download here.

The document looks exactly the same as the original word output, however it can now be shared in different formats.

However, if you don’t have Office 2007, all is not lost. There is a free download available called CutePDF Writer where you can print any document or file as a PDF – very useful to have installed.

By selecting this as your printer, it will create you a PDF document which you can then use as you wish. For those of you with .Net 3.0 framework installed, there is an XPS Document Writer installed, which is very similar to CutePDF.  This will create you XPS documents in exactly the same way.

A 14 day free trail of SQL Doc can be downloaded from http://www.red-gate.com/Products/SQL_Doc

Labels: Red Gate

Last week I successfully released my first project! The project was a major release of SQL Doc from Red Gate which allows you to easily document your database schema. While maybe not as popular as SQL Compare, it solves a problem many people experience very effectively.

With SQL Doc 2.0, we had very clear aims and goals for what we wanted to achieve. We used a variety of different sources, such as support calls and forum posts, to identity the core features people where asking for. This provided us with three main features:

• Printable documentation
• Improve the description editor
• Be able to use the links within the preview panel

With 2.0, we implemented the above features along with a series of small, yet important, changes to improve the overall experience for the user.

Documenting ASPNetDB

With ASP.net, there is a database called ASPnetDB, by default this is where various settings and data is stored for the built-in ASP.net providers, such as Membership and Personalization. While most of the time you don’t need to interact with the database directly, the times you do are extremely difficult due to the lack of documentation and the fact that SQL Server Management Studio isn’t designed for gaining a high level picture of the database schema. This is one example of where SQL Doc can help.

Upon connecting to your server, you can select the database(s) you wish to document. Here I've just selected aspnetdb.

Once you have selected all your databases, click Generate Documentation… SQL Doc can output the documentation to three different formats, CHM, HTML and now Microsoft Word (.doc). Depending on your use-case depends on the type of documentation you might require – we feel SQL Doc provides you with excellent support, however if you feel we are missing something let us know.

To understand ASPNetDb, I want to print off the database schema as I always find reading this easier in paper format than online. As such, I select Document to be my output. After a few moments, Word will open and I will have my documentation produced.

We can now navigate and read the document using word, or print it off. The documentation itself contains all the same information it would have within CHM or HTML, it’s just now in a printable format.

You can download this sample document here.

We also include the functionality to filter down the different objects, for example I might only want to include tables and stored procedures within the documentation. Using the treeview down the size, we can unselect the objects and categories we do not wish to be included.

By default, we include the SQL creation script for each database object, while this is very interesting certain users requested the ability to exclude this – which we have done. Within the Edit Project dialog there is a check box to include the SQL creation script, untick this and it will no longer be included.

The documentation now only includes the relevant sections while shorter due to the lack of SQL Scripts.  Feel free to take a look here.

You can download a 14 day free trail from our website:

http://www.red-gate.com/products/sql_doc

Labels: Red Gate

The excellent Pragmatic Programmer book suggests that you should learn a new language every year – this is something which I strongly agree with. By learning a new language it does not mean C# 4.0 (when you already know 2.0 and 3.0), or how to create Silverlight applications. Instead, make the effort to learn a language with a different mindset and approach to what your used to and actively engage in that community. Coming from a Java\C# background, Ruby was an eye-opener for me and approach to software development. The priorities and principals are different, for example Ruby has much more emphasise on elegance, solving problems and testability where software is treated as an art form while still being pragmatic in their approach – it’s never prefect and can be improved at some point. This importance is also being effectively communicated throughout the community from the Ruby guru’s such as Dave Thomas and Chad Fowler to the developers writing applications on a day-to-day basis. As a result of learning more about the Ruby language,

I feel I can approach a solution with a more opened minded approach.

How should you learn a new language?

This is something which I have been thinking about for a while, what is the most effective way to learn a new programming language? There are a couple of approaches you could take, but this is my approach (if you have your own suggestion, please leave it as a comment).

1) Buy a book, but not just any book – the best book. Personally, online materials are great but I still find the most effective way to learn something is to have a physical book by my side.  However, be sure to pick your book wisely, I recommend you research the influences within the community and either buy their book, or the book they recommend.  The wrong book could take you down completely the wrong path.

2) Start writing tests

Once you have picked your language and book of choice, you need to start grokking the concepts. After trying a couple of different techniques, I've found the best way to learn a new language is to actually write tests. This isn’t as crazy as it might sound, the test will define your expected outcome from your sample and give you something to aim for. This will help focus your mind on the task in hand, while giving you a clear signal as to when you are complete – the test will pass.

For example, with C#, if I wanted to know how to write a line of text to a file I might write the following test with the implementation.  

public class IO_Examples
{
    [Fact]
    public void Write_Hello_World_To_The_File_HelloWorldTxt()
    {
        MyFileAccess.Write("Hello World", "HelloWorld.txt");

        Assert.True(File.ReadAllText("HelloWorld.txt").Contains("Hello World"));
    }
}

public class MyFileAccess
{
    public static void Write(string s, string file)
    {
        StreamWriter streamWriter = new StreamWriter(file);
        streamWriter.WriteLine(s);
        streamWriter.Close();
    }
}

I have also found tests to be a much more natural starting point for interacting with a language, with C# my starting point was a command line application, however this wasn’t the most effective way of learning as I was constantly commenting out calls to various methods to execute the correct block of code. By using a test framework and a test runner as your starting point, I would have been able to run the samples more quickly and effectively while still keeping everything readable.

However, if your anything like me, while learning you will end up going off on a tangent or being distracted mid-task, I can recall too many occasions where I have been deep in the middle of learning the inners the underlying code only to read a blog post which takes me in a different direction and then completely forgetting where I was. By having a test, or a series of tests, guiding me I am able to quickly get back on track by seeing which tests are currently failing.  Because the tests will describe my aim, I will have a much better chance of remembering what I was actually doing.

Finally, once you start moving onto real applications and solving real problems using the language, you will be able to look back and refer to the tests as a reference regarding everything you learned.  If you keep your tests in a source control repository, you will even be able to see how you adapted over time. This could be extremely useful a year down the line where you want a very quick refresher.

3) Solve a problem!

Once you have an understanding of the language with a series of tests describing how to do various different tasks, the next thing to do is solve a problem you, or someone else, is experiencing having. While this isn’t always possible, it’s a great motivator to finish the job.  I enjoy automation and improving productivity (it allows me to spend more time on twitter), I find it really interesting to see how problems can be solved in a more effective fashion using tools and technologies – if a new language can help me with that then all the better. Not only will I learn the language in a more ‘real world’ context, but it will be helping me in the future.

Labels: Best Practices, C#, IronRuby

This week the IronRuby team moved their source repository over to GitHub, with the layout now reflecting the structure they maintain internally. I just wanted to cover how I downloaded and built IronRuby on a Windows Vista machine – Linux\Mac users will need to build via Mono. The first task is to download the code, as such you will need a git client, at the moment the best client I have found is msysgit.

msysgit installs both a GUI and command line, to download the source code I simply used the command line. Executing the following command within the directory where you want the code to be stored, for me this was E:\IronRubyGit\.

git clone git://github.com/ironruby/ironruby.git

The next task is to build the project, if you have MRI (Matz’s ruby) you can use the rake compile command, this will compile everything for you. If you don’t have MRI installed, you can build the Ruby.sln file using Visual Studio 2008 or the C# compiler (csc).

E:\IronRubyGit\ironruby\merlin\main\Languages\Ruby>rake compile
(in E:/IronRubyGit/ironruby/merlin/main/Languages/Ruby)
-------------------------------------------------------------------------------
dlr_core
-------------------------------------------------------------------------------
rake aborted!
No such file or directory - e:\ironrubygit\ironruby\merlin\main\languages\ruby\src\microsoft.scripting.core

(See full trace by running task with --trace)

However, I was greeted with a error message saying it was unable to find a file or directory. Luckily, the IronRuby mailing list is a great resource, and it turns out I needed to set the MERLIN_ROOT environment variable.

E:\IronRubyGit\ironruby\merlin\main\Languages\Ruby>set MERLIN_ROOT=e:\ironrubygit\ironruby\merlin\main

As a side note, merlin was the original codename for the IronPython team, which now includes IronRuby and the DLR (see John Lam’s post)

After solving this, I hit another error regarding tf.exe, the Team Foundation Source Control command line, being missing.

Cannot find tf.exe on system path.

The build script (rake) does a check to see if everything is configured correctly for IronRuby development, however tf isn’t required for building and actually only required internally within the team. The check for tf.exe is made within E:\IronRubyGit\ironruby\merlin\main\Languages\Ruby\rake\misc.rake, search for the string and simply remove it from the array.

commands += ['tf.exe', 'svn.exe'] if IronRuby.is_merlin?

Run rake compile again and IronRuby should happily build with the assemblies being built to ‘E:\IronRubyGit\ironruby\merlin\main\bin\debug’

However, after launching ir.exe (the IronRuby REPL), I was unable to reference rubygems. After a bit of investigating, turns out the $LOAD_PATHS where incorrect. These paths are set within ir.exe.config, all you need to do is replace the following part of the path External\Languages\Ruby\Ruby-1.8.6\lib\ruby with => external\languages\ruby\redist-libs\ruby . It’s used three times, after replacing the values I could happily use IronRuby.

Hope this helps!

Labels: DLR, IronRuby