Hello World!

The following outlines my initial my motivation for writing doctool.

For the sake of simplicity, assume you have written the famous Hello world example in C++. Now you want to explain some students what's it doing, how it's doing what's it doing, how to compile it and how to execute it.

Write the C++ Program

You first write the program. At this point of time you are just concerned that the program works at all. Just imagine that it's not about printing 'Hello word'. Instead, suppose it's about some numerical method you want to teach tomorrow morning and this program should be an example implementation.

So anyway, you end up with a C++ program that is doing what it is supposed to do. So you have this.

Present the Code

Using the :import: directive you can include the program listing into you document. If you add the downloadable option you can click the title. What you get is this:

tutorial/hello.cc

#include <iostream>

int

main()

{

    std::cout << "Hello world!" << std::endl;

}

Compiling the Code

Next you want to explain how to compile the code. Don't talk about, do it. The shell box gets executed when the doc file gets converted to HTML:

$shell> cd tutorial                        
$shell> clang++ -Wall -o hello hello.cc

Explain the compile options with a parameter list (requires at least four spaces between parameter key and parameter explanation):

-Wall	Show all warnings.
-o hello	The resulting executable will be named `hello`.
hello.cc	The C++ source file.

Executing the Program

Once compiled we can execute the program. This time we use a more 'lightweight' variant for the shell (see document source).

$shell> cd tutorial
$shell> ./hello
Hello world!

Adding Comments

For small example programs I like to insert some brief comments into the example source code. For example, I want to explain what the #include or the std::cout is doing. If such comments are done with ///, //- or //* these brief comments can be extracted by doctool.

Let us call this new version hello2.cc.

Some Notes

We can import the explanations from the source file with the :import: directive together with the brief option. The comment will be followed with consecutive source code (terminated by the next empty line).

We include the C++ header files for I/O operations

#include <iostream>

We next explain the output streaming.

std::cout << "Hello world!" << std::endl;

Complete Code (Stripped)

If you want to show the whole code listing these in-source comments are annoying. Using the stripped option they get removed from the listing if you are using the :import: directive:

tutorial/hello2.cc

#include <iostream>

int

main()

{

    std::cout << "Hello world!" << std::endl;

}

Complete Code (Unstripped)

And that's how the code would look like unstripped:

tutorial/hello2.cc

///

/// We include the C++ header files for I/O operations

///

#include <iostream>

int

main()

{

    ///

    /// We next explain the output streaming.

    ///

    std::cout << "Hello world!" << std::endl;

}