% Document: ./SingleDocLatex/system_tests
% Source: ./Source/t/
% Generated with ROBODoc Version 4.99.36 (Apr 25 2008)
\documentclass{article}
\usepackage{makeidx}
\usepackage{graphicx}
\oddsidemargin 0 cm
\evensidemargin 0 cm
\topmargin 0 cm
\textwidth 16 cm
\textheight 22 cm
\setlength{\parindent}{0in}
\setlength{\parskip}{.08in}

\pagestyle{headings}
\title{ROBODoc System Tests}
\author{Generated with ROBODoc Version 4.99.36 (Apr 25 2008)
}
\makeindex
\begin{document}
\maketitle
\newpage
\tableofcontents

\newpage
\section{ROBODoc/ROBODoc System Tests}
\textsl{[ Modules ]}

\label{ch:robo10}
\label{ch:ROBODoc_ROBODoc_System_Tests}
\index{unsorted!ROBODoc System Tests}\index{Modules!ROBODoc System Tests}
\textbf{FUNCTION}

   A set of perl scripts that test ROBODoc functionallity.
   Each script contains one of more system tests.  Each test
   starts ROBODoc with a specific input and then asserts that
   ROBODoc produces the correct output.



   The tests use the Perl unittest framework, that is the 
   modules:

\begin{itemize}
  \item    Test::More, See http://perldoc.perl.org/Test/More.html 
  \item    Test::File
\end{itemize}


   There is also a custom module ROBOTestFrame (\ref{ch:robo11}) that contains a
   set of useful functions that are common to all tests.



   You can run the tests with

\begin{verbatim}
      prove -l
\end{verbatim}


   Tests go into files with the extension .t. You can
   run an individual set of tests with

\begin{verbatim}
     prove <testfile>
\end{verbatim}


   A 'prove' should always result in a 100\% score.  No test
   should fail.

\newpage
\subsection{ROBODoc System Tests/ASCII Generator}
\textsl{[ ROBODoc System Tests ]}
\textsl{[ Modules ]}

\label{ch:robo0}
\label{ch:ROBODoc_System_Tests_ASCII_Generator}
\index{unsorted!ASCII Generator}\index{Modules!ASCII Generator}
\textbf{FUNCTION}

   Test ROBODoc ASCII generator.

\newpage
\subsubsection{ASCII Generator/dummy\_header\_1}
\textsl{[ ASCII Generator ]}
\textsl{[ Variables ]}

\label{ch:robo12}
\label{ch:ASCII_Generator_dummy_header_1}
\index{unsorted!dummy\_header\_1}\index{Variables!dummy\_header\_1}
\textbf{FUNCTION}

   A dummy header to put into dummy source files.

\textbf{SOURCE}
\begin{verbatim}
    my $dummy_header_1 = <<'EOF';
C     ****f* Lib/Func
C     NAME
C       Func -- useless
C       Computes the value:
C        |latex \begin{equation}
C        |latex x = 0
C        |latex \end{equation}
C        app
C
C     SYNOPSIS
C       Func = Func (n)
C       Computes the value:
C        |latex \begin{equation}
C        |latex x = 0
C        |latex \end{equation}
C     BUGS
C       Generates screwy TeX
C     ***
      real function Func(n)
        Func = 0
      end function Func

EOF
\end{verbatim}
\newpage
\subsubsection{ASCII Generator/dummy\_header\_2}
\textsl{[ ASCII Generator ]}
\textsl{[ Variables ]}

\label{ch:robo13}
\label{ch:ASCII_Generator_dummy_header_2}
\index{unsorted!dummy\_header\_2}\index{Variables!dummy\_header\_2}
\textbf{FUNCTION}

   A dummy header to put into dummy source files.

\textbf{SOURCE}
\begin{verbatim}
    my $dummy_header_2 = <<'EOF';
C     ****f* Lib/Func
C     NAME
C       Func -- useless
C     SYNOPSIS
C       Example:
C         Foo foo foo
C         foo
C
C       Test paragraph.
C       Do da diddi do da dom dom.
C
C     BUGS
C       A list test:
C       * item 1
C       * item 2
C       * item 3
C
C     ***
      real function Func(n)
        Func = 0
      end function Func

EOF
\end{verbatim}
\newpage
\subsubsection{ASCII Generator/smoke test}
\textsl{[ ASCII Generator ]}
\textsl{[ System tests ]}

\label{ch:robo14}
\label{ch:ASCII_Generator_smoke_test}
\index{unsorted!smoke test}\index{System tests!smoke test}
\textbf{FUNCTION}

   Try different combination of options.
   This should not cause any asserts().

\textbf{SOURCE}
\begin{verbatim}
{
    my @sources = ( \$dummy_header_1, \$dummy_header_2 );

    foreach my $source_ref ( @sources ) {
        foreach my $mode_1 qw( --sections --toc --index --nopre ) {
            foreach my $mode_2 qw( --singledoc --multidoc ) {
                mkdocdir();
                add_source( "test.c", $$source_ref );
                my ( $out, $err ) = runrobo(
                    qw(--src Src
                    --doc Doc/test
                    --ascii
                    ), $mode_1, $mode_2 );
                # expected results:
                is( $out, '', 'No ouput' );
                is( $err, '', '... and no error' );
                my $file_name;
                # Docments names differ for the different
                # modes.
                if ( $mode_2 eq "--multidoc" ) {
                    $file_name = "Doc/test/test_c.txt";
                } else {
                    $file_name = "Doc/test.txt";
                }
                file_exists_ok( $file_name, 
                    'there should be documentation' );
                clean();
            }
        }
    }
}
\end{verbatim}
\newpage
\subsection{ROBODoc System Tests/Basics}
\textsl{[ ROBODoc System Tests ]}
\textsl{[ Modules ]}

\label{ch:robo1}
\label{ch:ROBODoc_System_Tests_Basics}
\index{unsorted!Basics}\index{Modules!Basics}
\textbf{FUNCTION}

   Tests basic ROBODoc funcionallity.  These are all
   'happy paths'.

\newpage
\subsubsection{Basics/Dummy Headers}
\textsl{[ Basics ]}
\textsl{[ Variables ]}

\label{ch:robo15}
\label{ch:Basics_Dummy_Headers}
\index{unsorted!Dummy Headers}\index{Variables!Dummy Headers}
\textbf{FUNCTION}

   A dummy header to put into dummy source files.

\textbf{SOURCE}
\begin{verbatim}
my $source = <<'EOF';
/****f* Test/test
 * NAME
 *   Test
 ******
 */
EOF
\end{verbatim}
\newpage
\subsubsection{Basics/One file per header}
\textsl{[ Basics ]}
\textsl{[ System tests ]}

\label{ch:robo16}
\label{ch:Basics_One_file_per_header}
\index{unsorted!One file per header}\index{System tests!One file per header}
\textbf{FUNCTION}

   Test --multidoc with --one\_file\_per\_header for html output.  We
   test this with one source file that contains three headers.  These
   should result in three documentation files.  To make it nasty we
   use some special header names.

\textbf{SOURCE}
\begin{verbatim}
#    A dummy header to put into dummy source files.
my $source = <<'EOF';
/****f* Test/Test
 * NAME
 *   Test foo bar
 ******
 */

/****f* Test/foo, bar
 * NAME
 *   Test foo bar
 ******
 */

/****f* Test/aa::awaw
 * NAME
 *   Test foo bar
 ******
 */

EOF

{
    add_source( "test.c", $source );
    my ( $out, $err ) = runrobo(qw(--src Src --doc Doc --one_file_per_header --multidoc --html));
    # expected results:
    is( $out, '', 'No ouput' );
    is( $err, '', '... and no error' );
    # There are three headers, so there should be three documentation files.
    file_exists_ok( 'Doc/test_cTest2FTest.html',       'Documentation for Test/Test' );
    file_exists_ok( 'Doc/test_cTest2Ffoo.html',        'Documentation for Test/foo' );
    file_exists_ok( 'Doc/test_cTest2Faa3A3Aawaw.html', 'Documentation for Test/aa::awaw' );
    # And a style sheet.
    file_exists_ok( "Doc/robodoc.css", 'and a stylesheet' );
    clean();
}
\end{verbatim}
\newpage
\subsubsection{Basics/Option first section level}
\textsl{[ Basics ]}
\textsl{[ System tests ]}

\label{ch:robo17}
\label{ch:Basics_Option_first_section_level}
\index{unsorted!Option first section level}\index{System tests!Option first section level}
\textbf{FUNCTION}

   Test --first\_section\_level.



   The level of the first section should be
   at level 3 instead of 1.

\textbf{SOURCE}
\begin{verbatim}
{
    add_source( "test.c", $test_source_2 );
    mkdocdir();
    my ( $out, $err ) = runrobo(
        qw(--src Src
           --doc Doc/test
           --singledoc
           --sections
           --test
           --toc
           --first_section_level 3));
    # expected results:
    is( $out, '', 'No ouput' );
    is( $err, '', '... and no error' );
    file_exists_ok( "Doc/test.xml", 'there should be documentation' );

    # Now test the level of the first header.
    my $documentation = XMLin( 'Doc/test.xml' );
    my $section = $documentation->{'section'};
    is ( $section->[0]->{'depth'}, '3', 'First section is at level 3' );
    my $subsection = $section->[0]->{'section'};
    is ( $subsection->{'depth'}, '4', 'First subsection is at level 4' );
    is ( $section->[1]->{'depth'}, '3', 'Second section is at level 3' );

    clean();
}
\end{verbatim}
\newpage
\subsubsection{Basics/Option help}
\textsl{[ Basics ]}
\textsl{[ System tests ]}

\label{ch:robo18}
\label{ch:Basics_Option_help}
\index{unsorted!Option help}\index{System tests!Option help}
\textbf{FUNCTION}

   Test the option --help.

\textbf{SOURCE}
\begin{verbatim}
{
    my ( $out, $err ) = runrobo('--help');
    like( $out, qr/ROBODoc Version/, '--help should print version number' );
    is( $err, '', '... and no error' );
}
\end{verbatim}
\newpage
\subsubsection{Basics/Option multidoc}
\textsl{[ Basics ]}
\textsl{[ System tests ]}

\label{ch:robo19}
\label{ch:Basics_Option_multidoc}
\index{unsorted!Option multidoc}\index{System tests!Option multidoc}
\textbf{FUNCTION}

   Test --multidoc for html output format.
   (Multidoc for other modes does not make much sense).
   We create one source file with a simple header and create multidoc

\textbf{SOURCE}
\begin{verbatim}
{
    add_source( "test.c", $source );
    my ( $out, $err ) = runrobo(qw(--src Src --doc Doc --multidoc --html));
    # expected results:
    is( $out, '', 'No ouput' );
    is( $err, '', '... and no error' );
    file_exists_ok( "Doc/test_c.html", 'there should be documentation' );
    file_exists_ok( "Doc/robodoc.css", 'and a stylesheet' );

    clean();
}
\end{verbatim}
\newpage
\subsubsection{Basics/Option version}
\textsl{[ Basics ]}
\textsl{[ System tests ]}

\label{ch:robo20}
\label{ch:Basics_Option_version}
\index{unsorted!Option version}\index{System tests!Option version}
\textbf{FUNCTION}

   Test robodoc --version, this should report the current version.

\textbf{SOURCE}
\begin{verbatim}
{
    my ( $out, $err ) = runrobo('--version');
    like( $out, qr/\d+\.\d+.\d+/, '--version should print version number' );
    is( $err, '', '... and no error' );
}
\end{verbatim}
\newpage
\subsubsection{Basics/Singledoc Outputmode with Different Formats}
\textsl{[ Basics ]}
\textsl{[ System tests ]}

\label{ch:robo21}
\label{ch:Basics_Singledoc_Outputmode_with_Different_Formats}
\index{unsorted!Singledoc Outputmode with Different Formats}\index{System tests!Singledoc Outputmode with Different Formats}
\textbf{FUNCTION}

   Test singledoc mode  for all supported output formats 
   and see if it creates output in this format.

\textbf{SOURCE}
\begin{verbatim}
{
    add_source( "test.c", $source );

    my %output_modes = (
        '--html'  => 'html',
        '--rtf'   => 'rtf',
        '--test'  => 'xml', 
        '--latex' => 'tex',
        '--dbxml' => 'xml',
    );

    foreach my $mode ( keys %output_modes ) {
        my $file_extension = $output_modes{$mode};

        my @arguments = qw(--src Src --doc testdoc --singledoc);
        push( @arguments, $mode );

        my ( $out, $err ) = runrobo(@arguments);
        is( $out, '', 'No ouput' );
        is( $err, '', '... and no error' );
        file_exists_ok( "testdoc.$file_extension",
            'there should be documentation' );
        if ( $mode eq "--html" ) {
            file_exists_ok( "testdoc.css", 'and a stylesheet' );
        }

        unlink("testdoc.$file_extension") if -e "testdoc.$file_extension";
        unlink('testdoc.css')             if -e 'testdoc.css';

    }

    clean();
}
\end{verbatim}
\newpage
\subsubsection{Basics/test\_source\_2}
\textsl{[ Basics ]}
\textsl{[ Variables ]}

\label{ch:robo22}
\label{ch:Basics_test_source_2}
\index{unsorted!test\_source\_2}\index{Variables!test\_source\_2}
\textbf{FUNCTION}

   A dummy header to put into dummy source files.
   This one has headers at several levels.

\textbf{SOURCE}
\begin{verbatim}
my $test_source_2 = <<'EOF';
/****f* Level_1/Level_2
 * NAME
 *   Test
 ******
 */

/****f* Level_2/_Level_3
 * NAME
 *   Test
 ******
 */

/****f* Level_3/_Level_4
 * NAME
 *   Test
 ******
 */

EOF
\end{verbatim}
\newpage
\subsection{ROBODoc System Tests/Encoding}
\textsl{[ ROBODoc System Tests ]}
\textsl{[ Modules ]}

\label{ch:robo2}
\label{ch:ROBODoc_System_Tests_Encoding}
\index{unsorted!Encoding}\index{Modules!Encoding}
\textbf{FUNCTION}

    Test decoding en encoding of non 7bit ASCII characters.

\newpage
\subsection{ROBODoc System Tests/Handling Errors}
\textsl{[ ROBODoc System Tests ]}
\textsl{[ Modules ]}

\label{ch:robo3}
\label{ch:ROBODoc_System_Tests_Handling_Errors}
\index{unsorted!Handling Errors}\index{Modules!Handling Errors}
\textbf{FUNCTION}

    Test wether calling ROBODoc with wrong options or input leads
    to the correct error messages.

\newpage
\subsubsection{Handling Errors/Error on Duplicate Options}
\textsl{[ Handling Errors ]}
\textsl{[ System tests ]}

\label{ch:robo23}
\label{ch:Handling_Errors_Error_on_Duplicate_Options}
\index{unsorted!Error on Duplicate Options}\index{System tests!Error on Duplicate Options}
\textbf{FUNCTION}

   ROBODoc should complain about options that are specifed more
   than once.

\textbf{SOURCE}
\begin{verbatim}
{
    add_source( "test.c", $source );
    my ($out, $err) = runrobo( qw( --src Src --doc Doc --multidoc --test --test --test) );
    print $out;
    like($out, qr/Usage/, 'Duplicate options should print usage' );
    print $err;
    like($err, qr/than\sonce/, 'and an error message'   );
    clean();
}
\end{verbatim}
\newpage
\subsubsection{Handling Errors/Error on Mutual Excluding Options}
\textsl{[ Handling Errors ]}
\textsl{[ System tests ]}

\label{ch:robo24}
\label{ch:Handling_Errors_Error_on_Mutual_Excluding_Options}
\index{unsorted!Error on Mutual Excluding Options}\index{System tests!Error on Mutual Excluding Options}
\textbf{FUNCTION}

   ROBODoc should complain about options that can not be used
   together.

\textbf{SOURCE}
\begin{verbatim}
{
    add_source( "test.c", $source );
    my ($out, $err) = runrobo( qw(--src Src --doc Doc --multidoc --singledoc --html) );
    like($out, qr/Usage/, 'Mutual excluding options should print usage' );
    print $err;
    like($err, qr/together/, 'and an error message'   );
    clean();
}
\end{verbatim}
\newpage
\subsubsection{Handling Errors/Error on Mutual Excluding Options II}
\textsl{[ Handling Errors ]}
\textsl{[ System tests ]}

\label{ch:robo25}
\label{ch:Handling_Errors_Error_on_Mutual_Excluding_Options_II}
\index{unsorted!Error on Mutual Excluding Options II}\index{System tests!Error on Mutual Excluding Options II}
\textbf{FUNCTION}

   ROBODoc should complain about options that can not be used
   together.

\textbf{SOURCE}
\begin{verbatim}
{
    add_source( "test.c", $source );
    my ($out, $err) = runrobo( qw(--src Src --doc Doc --multidoc --test --dbxml --html) );
    like($out, qr/Usage/, 'Mutual excluding options should print usage' );
    print $err;
    like($err, qr/together/, 'and an error message'   );
    clean();
}
\end{verbatim}
\newpage
\subsubsection{Handling Errors/Error on Non-existing Option}
\textsl{[ Handling Errors ]}
\textsl{[ System tests ]}

\label{ch:robo26}
\label{ch:Handling_Errors_Error_on_Non_existing_Option}
\index{unsorted!Error on Non-existing Option}\index{System tests!Error on Non-existing Option}
\textbf{FUNCTION}

   ROBODoc should complain about non-existing options.

\textbf{SOURCE}
\begin{verbatim}
{
    my ($out, $err) = runrobo( '--foobar' );
    like($out, qr/Usage/, 'Unknown option should print usage' );
    like($err, qr/Invalid/, 'and an error message'   );
}
\end{verbatim}
\newpage
\subsubsection{Handling Errors/Error on Non-existing rc file}
\textsl{[ Handling Errors ]}
\textsl{[ System tests ]}

\label{ch:robo27}
\label{ch:Handling_Errors_Error_on_Non_existing_rc_file}
\index{unsorted!Error on Non-existing rc file}\index{System tests!Error on Non-existing rc file}
\textbf{FUNCTION}

   When given a non-existing .rc file, ROBODc should
   at least report the name of the .rc file.

\textbf{SOURCE}
\begin{verbatim}
{
    my ($out, $err) = runrobo( '--rc foobar.rc' );
    like($err, qr/foobar/, 'should give an error message about foorbar.rc' );
}
\end{verbatim}
\newpage
\subsubsection{Handling Errors/Header without end marker}
\textsl{[ Handling Errors ]}
\textsl{[ System tests ]}

\label{ch:robo28}
\label{ch:Handling_Errors_Header_without_end_marker}
\index{unsorted!Header without end marker}\index{System tests!Header without end marker}
\textbf{FUNCTION}

   Test ROBODoc's response on a header without an
   end marker. ROBODoc should detect this.

\textbf{SOURCE}
\begin{verbatim}
{
    my $source = <<'EOF';
/****f* Test/test
 * NAME
 *   Test
 * FUNCTION
 *   Test2
 * SOURCE
 */

some source

and no end of the header  ....

EOF

    add_source( "test.c", $source );
    my ($out, $err) = runrobo( qw(--src Src --doc Doc --multidoc --test) );
    is( $out, '', 'no output' );
    like( $err, qr/end\smarker/, 'error about end marker' );
    clean();
}
\end{verbatim}
\newpage
\subsubsection{Handling Errors/Headers with duplicate names}
\textsl{[ Handling Errors ]}
\textsl{[ System tests ]}

\label{ch:robo29}
\label{ch:Handling_Errors_Headers_with_duplicate_names}
\index{unsorted!Headers with duplicate names}\index{System tests!Headers with duplicate names}
\textbf{FUNCTION}

   Test ROBODoc's response to a file with two headers that
   have the same name. This should be reported as an error.

\textbf{SOURCE}
\begin{verbatim}
{
    my $source = <<'EOF';
/****f* Test/test
 * NAME
 *   Test
 * FUNCTION
 *   Test2
 *****
 */

/****f* Test/test
 * NAME
 *   Test
 * FUNCTION
 *   Test2
 *****
 */

EOF

    add_source( "test.c", $source );
    my ($out, $err) = runrobo( qw(--src Src --doc Doc --multidoc --test) );
    is( $out, '', 'no output' );
    like( $err, qr/already\sexists/, 'error duplicate header' );
    clean();
}
\end{verbatim}
\newpage
\subsubsection{Handling Errors/Impossible output file}
\textsl{[ Handling Errors ]}
\textsl{[ System tests ]}

\label{ch:robo30}
\label{ch:Handling_Errors_Impossible_output_file}
\index{unsorted!Impossible output file}\index{System tests!Impossible output file}
\textbf{FUNCTION}

   When given a impossible output filename ROBODoc should
   at least report the filename.

\textbf{SOURCE}
\begin{verbatim}
{
    add_source( "test.c", $source );
    my ($out, $err) = runrobo( qw(--src Src --doc Foo/Bar/document --singledoc --html) );
    like($err, qr/document/, 'should give an error message about document' );
}
\end{verbatim}
\newpage
\subsubsection{Handling Errors/Non-existing css file}
\textsl{[ Handling Errors ]}
\textsl{[ System tests ]}

\label{ch:robo31}
\label{ch:Handling_Errors_Non_existing_css_file}
\index{unsorted!Non-existing css file}\index{System tests!Non-existing css file}
\textbf{FUNCTION}

   When given  a impossible css filename ROBODoc should
   at least report the filename.

\textbf{SOURCE}
\begin{verbatim}
{
    add_source( "test.c", $source );
    my ($out, $err) = runrobo( qw(--src Src --doc Doc --multidoc --html --css Foo/Bar/cascade.css) );
    like($err, qr/cascade/, 'should give an error message about css file' );
}
\end{verbatim}
\newpage
\subsection{ROBODoc System Tests/Header Test}
\textsl{[ ROBODoc System Tests ]}
\textsl{[ Modules ]}

\label{ch:robo4}
\label{ch:ROBODoc_System_Tests_Header_Test}
\index{unsorted!Header Test}\index{Modules!Header Test}
\textbf{FUNCTION}

   Tests the parsing of ROBODoc headers.

\newpage
\subsubsection{Header Test/Broken header}
\textsl{[ Header Test ]}
\textsl{[ System tests ]}

\label{ch:robo32}
\label{ch:Header_Test_Broken_header}
\index{unsorted!Broken header}\index{System tests!Broken header}
\textbf{FUNCTION}

  Try several header with names that contain spaces.
  These should be accepted.

\textbf{SOURCE}
\begin{verbatim}
{
    my $source = <<'EOF';
{****f* xxxxxx/x_xxx_xxxxxxxxxxxxxxxxxxxxxxxx
*
*OMSCHRIJVING
*xxxx xxxxxxx xxxxxxxxx xxxxxxxxxx xxxxxxx xxxxxxxxxxxx xx xx
xxxxxxxxxxxxxxx
*xxxxxxxxx x_xxx_xxxxxxxxxxxxxxxxxx xxxxxxx
*
*INVOER
*xxxxxxx : xxx xxxxxxx xxxx xxxxxx xxxxxxxxx xxxxxxxxxxxx xxxxx xx xxx
xx
* xxxxxxxxx xxxxxxxxx xxxxx xxxxxxxxxxxx.
*xxxxxxxxxxx : xxx xxxxxxxxx xxxxx xxxxx xxx xx xxxxx xxxxxx xx xxxxxxxxxx
* xxxxxxxxx xxxxxxxx xx
*RETURNWAARDE
*xxxx__xxxxxxx, x_xxx_xxxxxxxxx, xxxx__xxxxxxxx, x_xxx_xxxxxxxx,
*x_xxx_xxxxxxxxx, x_xxx_xxxxxxxxxxxxxx xx x_xxxx_xxxxxx_xxx
xxxxxx xxxxx.
*
*VOORBEELD
*x_xxx_xxxxxxxxxxxxxxxxxxxxxxxx (xxxxxxx := 5000,
* xxxxxxxxxxx := xx_xxxxxxxxxxx);
*DECLARATIE
*}

{*****}
EOF


    my $config = <<'EOF';
items:
    OMSCHRIJVING
    WIJZIGINGSOVERZICHT
    DECLARATIE
    INVOER
    UITVOER
    IN-UITVOER
    PARAMETERS
    BOUNDARIES
    RETURNWAARDE
    ATTRIBUTEN
    GEBRUIKTE GEGEVENS
    VOORBEELD
    ZIE VERDER
    OPMERKINGEN
    PRECONDITIE
    POSTCONDITIE 

item order:
    OMSCHRIJVING
    DECLARATIE

source items:
    DECLARATIE
    SOURCE
    
preformatted items:
    WIJZIGINGSOVERZICHT
    INVOER
    UITVOER   
    IN-UITVOER
    PARAMETERS
    RETURNWAARDE
    ATTRIBUTEN
    VOORBEELD

headertypes:
    h   "Modules"        vptlib_modules
    f   "Functies"       vptlib_functies
    v   "Variabelen"     vptlib_variabelen
    s   "Structuren"     vptlib_structuren
    e   "Enumeraties"    vptlib_enumeraties
    c   "Constanten"     vptlib_constanten
    u   "Unittesten"     vptlib_unittesten
    t   "Typedefinities" vptlib_typedefs
    m   "Macros"         vptlib_macros
    d   "Definities"     vptlib_definities

options:
    --documenttitle "Xxxxxxxxxxxxxxxxxxx"
    --tabsize 8
    --index 
    --sections
    --sectionnameonly  
    --nopre
    --multidoc
 
header markers:
    /****
\end{verbatim}
\newpage
\subsubsection{Header Test/Circular header}
\textsl{[ Header Test ]}
\textsl{[ System tests ]}

\label{ch:robo33}
\label{ch:Header_Test_Circular_header}
\index{unsorted!Circular header}\index{System tests!Circular header}
\textbf{FUNCTION}

   The 3rd header points to the first header, 
   completing a circle.  ROBODoc should complain
   about this.

\textbf{SOURCE}
\begin{verbatim}
TODO: {
    local $TODO = "checking circular headers is not implemented yet.";
    my $source = <<'EOF';

/****f* Foo/Bar
* NAME
*   Bar
****/

/****f* Bar/Fii
 * NAME
 *   Foo
 *****/

/****f* Fii/Bar
 * NAME
 *   Foo
 *****/
EOF

    add_source( "test.c", $source );
    my ($out, $err) = runrobo( qw(
        --src Src
        --doc Doc
        --multidoc
        --html
        --toc
        --sections
        ) );
    # ROBODoc should complain about circular 
    # headers.
    isnt( $err, '', 'there should be an error' );
#    clean();
}
\end{verbatim}
\newpage
\subsubsection{Header Test/Happy Path}
\textsl{[ Header Test ]}
\textsl{[ System tests ]}

\label{ch:robo34}
\label{ch:Header_Test_Happy_Path}
\index{unsorted!Happy Path}\index{System tests!Happy Path}
\textbf{FUNCTION}

   Happy Path Simple plain header. This definitely should work

\textbf{SOURCE}
\begin{verbatim}
{
    my $source = <<'EOF';
/****f* Test/test
 * NAME
 *   Test
 * FUNCTION
 *   Test2
 ******
 */
EOF

    add_source( "test.c", $source );
    my ($out, $err) = runrobo( qw(--src Src --doc Doc --multidoc --test) );
    is( $out, '', 'no output' );
    is( $err, '', 'and no error' );
    clean();
}
\end{verbatim}
\newpage
\subsubsection{Header Test/Multiple Names with Spaces}
\textsl{[ Header Test ]}
\textsl{[ System tests ]}

\label{ch:robo35}
\label{ch:Header_Test_Multiple_Names_with_Spaces}
\index{unsorted!Multiple Names with Spaces}\index{System tests!Multiple Names with Spaces}
\textbf{FUNCTION}

   Try several header with names that contain spaces.
   These should be accepted.

\textbf{SOURCE}
\begin{verbatim}
{
    my $source = <<'EOF';
/****f* Test Foo Bar/Name With Spaces, And Anotherone,
 *                   And One More, More
 * NAME
 *   Test
 * FUNCTION
 *   Test2
 ******
 */
EOF

    add_source( "test.c", $source );
    my ($out, $err) = runrobo( qw(--src Src --doc Doc --multidoc --test) );
    is( $out, '', 'no output' );
    is( $err, '', 'and no error' );
    my $documentation = XMLin( 'Doc/test_c.xml' );
    my $header = $documentation->{'header'};
    is ( $header->{'name'}, 'Test Foo Bar/Name With Spaces', 'Header name' );

    clean();
}
\end{verbatim}
\newpage
\subsubsection{Header Test/Names with Spaces}
\textsl{[ Header Test ]}
\textsl{[ System tests ]}

\label{ch:robo36}
\label{ch:Header_Test_Names_with_Spaces}
\index{unsorted!Names with Spaces}\index{System tests!Names with Spaces}
\textbf{FUNCTION}

   Try a header name with spaces and some '*' at
   the end.  The '*' should be ignored.

\textbf{SOURCE}
\begin{verbatim}
{
    my $source = <<'EOF';
/****f* Test Foo Bar/Name With Spaces ****
 * NAME
 *   Test
 * FUNCTION
 *   Test2
 ******
 */
EOF

    add_source( "test.c", $source );
    my ($out, $err) = runrobo( qw(--src Src --doc Doc --multidoc --test) );
    is( $out, '', 'no output' );
    is( $err, '', 'and no error' );
    my $documentation = XMLin( 'Doc/test_c.xml' );
    my $header = $documentation->{'header'};
    is ( $header->{'name'}, 'Test Foo Bar/Name With Spaces', 'Header name' );

    clean();
}
\end{verbatim}
\newpage
\subsection{ROBODoc System Tests/Item Test}
\textsl{[ ROBODoc System Tests ]}
\textsl{[ Modules ]}

\label{ch:robo5}
\label{ch:ROBODoc_System_Tests_Item_Test}
\index{unsorted!Item Test}\index{Modules!Item Test}
\textbf{FUNCTION}

   Tests the parsing generation of ROBODoc items.

\newpage
\subsubsection{Item Test/Sorting}
\textsl{[ Item Test ]}
\textsl{[ System tests ]}

\label{ch:robo37}
\label{ch:Item_Test_Sorting}
\index{unsorted!Sorting}\index{System tests!Sorting}
\textbf{FUNCTION}

   Lets see if we can get items sorted according
   to the order specified in a robodoc.rc file.

\textbf{SOURCE}
\begin{verbatim}
{
    my $source = <<'EOF';
/****f* Test/test
 * FIRST
 *   Test 1
 * Second
 *   Test 2
 * THIRD
 *   Test 3
 * SOURCE
 */

  Test 4

 /*******/
EOF

    my $config = <<'EOF';
items:
    FIRST
    Second
    THIRD
    FOURTH
item order:
    SOURCE
    THIRD
EOF

    my $config_no_sort = <<'EOF';
items:
    FIRST
    Second
    THIRD
    FOURTH
EOF

    add_source( "test.c", $source );
    add_configuration( "robodoc.rc", $config );
    my ($out, $err) = runrobo( qw(
        --src Src
        --doc Doc --multidoc --ascii
        --rc Config/robodoc.rc
    ) );
    is( $out, '', 'no output' );
    is( $err, '', 'and no error' );
    my $documentation = IO::File->new( "<Doc/test_c.txt" );
    ok( $documentation, 'There is a doc file' );
    my @items = ();
    while ( my $line = <$documentation> ) {
        if ( $line =~ m/(SOURCE|THIRD|Second|FIRST)/ ) {
            push( @items, $1 );
        }
    }
    is( $items[ 0 ], 'SOURCE', 'First item it the source item' );
    is( $items[ 1 ], 'THIRD',  'Second item it the third item' );
    is( $items[ 2 ], 'FIRST',  'Third item it the first item' );
    $documentation->close();

    # Now the same but without sorting
    add_configuration( "robodoc.rc", $config_no_sort );
    my ($out2, $err2) = runrobo( qw(
        --src Src
        --doc Doc --multidoc --ascii
        --rc Config/robodoc.rc
    ) );
    is( $out2, '', 'no output' );
    is( $err2, '', 'and no error' );

    $documentation = IO::File->new( "<Doc/test_c.txt" );
    ok( $documentation, 'There is a doc file' );
    @items = ();
    while ( my $line = <$documentation> ) {
        if ( $line =~ m/(SOURCE|THIRD|Second|FIRST)/ ) {
            push( @items, $1 );
        }
    }
    is( $items[ 0 ], 'FIRST',  'First item it the first item' );
    is( $items[ 1 ], 'Second', 'Second item it the second item' );
    is( $items[ 2 ], 'THIRD',  'Third item it the third item' );
    is( $items[ 3 ], 'SOURCE', 'Fourth item it the fourth' );
    $documentation->close();

    clean();
}
\end{verbatim}
\newpage
\subsection{ROBODoc System Tests/LaTeX Generator}
\textsl{[ ROBODoc System Tests ]}
\textsl{[ Modules ]}

\label{ch:robo6}
\label{ch:ROBODoc_System_Tests_LaTeX_Generator}
\index{unsorted!LaTeX Generator}\index{Modules!LaTeX Generator}
\textbf{FUNCTION}

   Test ROBODoc LaTeX generator.

\newpage
\subsubsection{LaTeX Generator/dummy\_header\_1}
\textsl{[ LaTeX Generator ]}
\textsl{[ Variables ]}

\label{ch:robo38}
\label{ch:LaTeX_Generator_dummy_header_1}
\index{unsorted!dummy\_header\_1}\index{Variables!dummy\_header\_1}
\textbf{FUNCTION}

   A dummy header to put into dummy source files.

\textbf{SOURCE}
\begin{verbatim}
    my $dummy_header_1 = <<'EOF';
C     ****f* Lib/Func
C     NAME
C       Func -- useless
C       Computes the value:
C        |latex \begin{equation}
C        |latex x = 0
C        |latex \end{equation}
C        app
C
C     SYNOPSIS
C       Func = Func (n)
C       Computes the value:
C        |latex \begin{equation}
C        |latex x = 0
C        |latex \end{equation}
C     BUGS
C       Generates screwy TeX
C     ***
      real function Func(n)
        Func = 0
      end function Func

EOF
\end{verbatim}
\newpage
\subsubsection{LaTeX Generator/dummy\_header\_2}
\textsl{[ LaTeX Generator ]}
\textsl{[ Variables ]}

\label{ch:robo39}
\label{ch:LaTeX_Generator_dummy_header_2}
\index{unsorted!dummy\_header\_2}\index{Variables!dummy\_header\_2}
\textbf{FUNCTION}

   A dummy header to put into dummy source files.

\textbf{SOURCE}
\begin{verbatim}
    my $dummy_header_2 = <<'EOF';
C     ****f* Lib/Func
C     NAME
C       Func -- useless
C     SYNOPSIS
C       Example:
C         Foo foo foo
C         foo
C
C       Test paragraph.
C       Do da diddi do da dom dom.
C
C     BUGS
C       A list test:
C       * item 1
C       * item 2
C       * item 3
C
C     ***
      real function Func(n)
        Func = 0
      end function Func

EOF
\end{verbatim}
\newpage
\subsubsection{LaTeX Generator/latex is balanced}
\textsl{[ LaTeX Generator ]}
\textsl{[ System tests ]}

\label{ch:robo40}
\label{ch:LaTeX_Generator_latex_is_balanced}
\index{unsorted!latex is balanced}\index{System tests!latex is balanced}
\textbf{FUNCTION}

   This function tests whether a generated latex file is balanced
   or not.  That is every 

\begin{verbatim}
     /begin{xxx} 
\end{verbatim}

   should end with a 

\begin{verbatim}
     /end{xxx}
\end{verbatim}

   at the same level.



   This is tested with several headers and in different modes.

\textbf{SOURCE}
\begin{verbatim}
{
    my @sources = ( \$dummy_header_1, \$dummy_header_2 );

    foreach my $source_ref ( @sources ) {
        foreach my $mode_1 qw( --sections --toc --index ) {
            foreach my $mode_2 qw( --nopre --altlatex ) {
                mkdocdir();
                add_source( "test.c", $$source_ref );
                my ( $out, $err ) = runrobo(
                    qw(--src Src
                    --doc Doc/test
                    --singledoc
                    --latex
                    ), $mode_1, $mode_2 );
                # expected results:
                is( $out, '', 'No ouput' );
                is( $err, '', '... and no error' );
                file_exists_ok( "Doc/test.tex", 'there should be documentation' );
                is( is_latex_balanced( "Doc/test.tex" ), 1, 'latex is balanced' );
                clean();
            }
        }
    }
}
\end{verbatim}
\newpage
\subsection{ROBODoc System Tests/Pipes}
\textsl{[ ROBODoc System Tests ]}
\textsl{[ Modules ]}

\label{ch:robo7}
\label{ch:ROBODoc_System_Tests_Pipes}
\index{unsorted!Pipes}\index{Modules!Pipes}
\textbf{FUNCTION}

   Test the usage of pipes.

\newpage
\subsubsection{Pipes/latex pipes}
\textsl{[ Pipes ]}
\textsl{[ System tests ]}

\label{ch:robo41}
\label{ch:Pipes_latex_pipes}
\index{unsorted!latex pipes}\index{System tests!latex pipes}
\textbf{FUNCTION}

   Test the use of latex pipes preformatted more.
$2n < 8$

\textbf{SOURCE}
\begin{verbatim}
{
    add_source( "test.c", $pipe_source );
    mkdocdir();
    my ( $out, $err ) = runrobo(
        qw(--src Src 
           --doc Doc/test
           --nopre
           --singledoc
           --sections
           --latex
           ));
    # expected results:
    is( $out, '', 'No ouput' );
    is( $err, '', '... and no error' );
    file_exists_ok( "Doc/test.tex", 'there should be documentation' );
    # TODO test content
    clean();
}
\end{verbatim}
\newpage
\subsection{ROBODoc System Tests/ROBODoc Configuration File}
\textsl{[ ROBODoc System Tests ]}
\textsl{[ Modules ]}

\label{ch:robo8}
\label{ch:ROBODoc_System_Tests_ROBODoc_Configuration_File}
\index{unsorted!ROBODoc Configuration File}\index{Modules!ROBODoc Configuration File}
\textbf{FUNCTION}

    Test stuff that can be specified in the robodoc.rc file.

\newpage
\subsubsection{ROBODoc Configuration File/Custom Header Markers}
\textsl{[ ROBODoc Configuration File ]}
\textsl{[ System tests ]}

\label{ch:robo42}
\label{ch:ROBODoc_Configuration_File_Custom_Header_Markers}
\index{unsorted!Custom Header Markers}\index{System tests!Custom Header Markers}
\textbf{FUNCTION}

   Test whether custum header markers can be specified.

\textbf{SOURCE}
\begin{verbatim}
{
    my $source = <<'EOF';
/ ****f* Test/test
/ NAME
/   Test
/ FUNCTION
/   Test1
/ SOURCE
/ ****

/ ****F* Foo/foo
/ NAME
/   Foo
/ FUNCTION
/   Test2
/ SOURCE
/ ****

EOF

    my $rc_file = <<'EOF';
header markers:
  / ****
remark markers:
  /
end markers:
  / ****
headertypes:
  f functions 1
  F Foos      2
EOF

    add_source( "test.c", $source );
    add_source( "robodoc.rc", $rc_file );
    my ($out, $err) = runrobo( qw(--src Src --doc Doc --multidoc 
        --test --rc Src/robodoc.rc ) );
    is( $out, '', 'no output' );
    is( $err, '', 'no error' );
    my $documentation = XMLin( 'Doc/test_c.xml' );
    my $header = $documentation->{'header'};
#    print Dumper( $documentation );
    isnt ( $header->{'Foo/foo'}, undef, 'There is a header named Foo/foo' );
    isnt ( $header->{'Test/test'}, undef, 'There is a header named Test/foo' );
    clean();
}
\end{verbatim}
\newpage
\subsubsection{ROBODoc Configuration File/line-endings.}
\textsl{[ ROBODoc Configuration File ]}
\textsl{[ System tests ]}

\label{ch:robo43}
\label{ch:ROBODoc_Configuration_File_line_endings_}
\index{unsorted!line-endings.}\index{System tests!line-endings.}
\textbf{FUNCTION}

   ROBODoc should not care about the kind of line-endings that
   are used.  Either cr/lf or cr, or even lf should work without
   any problem.   We test this with two .rc files that have
   different kind of line-endings.

\textbf{SOURCE}
\begin{verbatim}
{
    my $source = <<'EOF';
/****f* Test/test
 * FOO
 *   test
 ******/
EOF
    # A rc file with 'unix' line-endings.
    my $config = read_hexdump( 'TestData/robodoc_unix_rc.xxd' );
    add_configuration( "test.rc", $config, 'binary' );
    add_source( "test.rc", $source );
    mkdocdir();
    my ( $out, $err ) = runrobo(qw(
        --src Src
        --doc Doc/test
        --rc Config/test.rc
        --singledoc --test --nopre ));
    # expected results:
    is( $out, '', 'No ouput' );
    is( $err, '', '... and no error' );
    clean();

    # A rc file with 'windows' line-endings.
    $config = read_hexdump( 'TestData/robodoc_windows_rc.xxd' );
    add_configuration( "test.rc", $config, 'binary' );
    add_source( "test.rc", $source );
    mkdocdir();
    ( $out, $err ) = runrobo(qw(
        --src Src
        --doc Doc/test
        --rc Config/test.rc
        --singledoc --test --nopre ));
    # expected results:
    is( $out, '', 'No ouput' );
    is( $err, '', '... and no error' );
    clean();
}
\end{verbatim}
\newpage
\subsection{ROBODoc System Tests/Wiki Formatting}
\textsl{[ ROBODoc System Tests ]}
\textsl{[ Modules ]}

\label{ch:robo9}
\label{ch:ROBODoc_System_Tests_Wiki_Formatting}
\index{unsorted!Wiki Formatting}\index{Modules!Wiki Formatting}
\textbf{FUNCTION}

    Tests that test the Wiki like formatting that ROBODoc supports.

\newpage
\subsubsection{Wiki Formatting/Wiki Basics}
\textsl{[ Wiki Formatting ]}
\textsl{[ System tests ]}

\label{ch:robo56}
\label{ch:Wiki_Formatting_Wiki_Basics}
\index{unsorted!Wiki Basics}\index{System tests!Wiki Basics}
\textbf{FUNCTION}

   Test a simple header: contains three lists, some paragraphs,
   and some source.  All should be recognized.

\textbf{SOURCE}
\begin{verbatim}
{
    my $source = <<'EOF';
/****f* Test/Test
 * NAME
 *
 *   Implements serializers for the following
 *   files:
 *   - DZB_ACG - SAP accounting file record.
 *   - DZB_RRP - regularoty reporting file record.
 *   - DZB_MVT - Exchange Position File Record.
 *
 *   A test
 *     
 *   Implements the following
 *   functions:
 *   - S99304_SERIALIZE_DZB_ACG
 *   - S99304_SERIALIZE_DZB_ACG_TBL
 *   - S99304_SERIALIZE_DZB_MVT
 *   and the functions:
 *   - S99304_SERIALIZE_DZB_MVT_TBL
 *   - S99304_SERIALIZE_DZB_RRP
 *   - S99304_SERIALIZE_DZB_RRP_TBL
 * SOURCE
 */
    test()

 /******/

EOF

    add_source( "test.c", $source );
    my ( $out, $err ) = runrobo(qw(--src Src --doc Doc --nopre --multidoc --test));
    # expected results:
    is( $out, '', 'No ouput' );
    is( $err, '', '... and no error' );

    my $documentation = XMLin( 'Doc/test_c.xml' );
    my $header = $documentation->{'header'};
    is ( $header->{'name'}, 'Test/Test', 'Header is named Test/Test' );
    my $items = $header->{'item'};
    ok ( exists( $items->{'NAME'} ),   'header has an item NAME' );
    ok ( exists( $items->{'SOURCE'} ), 'header has an item SOURCE' );
    my $body = $items->{'NAME'}->{'item_body'};

    # There are paragraphs.
    ok ( exists( $body->{'para'} ),    'item has paragraphs' );

    # There are three lists.
    is ( scalar( @{ $body->{'list'} } ), 3, 'item has three lists' );
    clean();
}
\end{verbatim}
\newpage
\section{ROBODoc/ROBOTestFrame}
\textsl{[ Modules ]}

\label{ch:robo11}
\label{ch:ROBODoc_ROBOTestFrame}
\index{unsorted!ROBOTestFrame}\index{Modules!ROBOTestFrame}
\textbf{FUNCTION}

   A Perl module with a set of handy functions to create
   test scripts.



   These function are:

\begin{itemize}
  \item    runrobo (\ref{ch:robo54})
  \item    add\_source (\ref{ch:robo46})
  \item    add\_configuration (\ref{ch:robo44})
  \item    clean (\ref{ch:robo47})
  \item    mkdocdir (\ref{ch:robo51})
  \item    is\_latex\_balanced (\ref{ch:robo50})
  \item    read\_hexdump (\ref{ch:robo52})
\end{itemize}


\newpage
\subsection{ROBOTestFrame/add\_configuration}
\textsl{[ ROBOTestFrame ]}
\textsl{[ Functions ]}

\label{ch:robo44}
\label{ch:ROBOTestFrame_add_configuration}
\index{unsorted!add\_configuration}\index{Functions!add\_configuration}
\textbf{FUNCTION}

   Add a configuration file somewhere in Config/

\textbf{INPUTS}
\begin{itemize}
  \item    filepath -- path to a file.
  \item    configuration -- the content for this file
  \item    binary -- write the raw bytes.  [optional]
\end{itemize}


\textbf{SOURCE}
\begin{verbatim}
sub add_configuration
{
    my $filepath = shift;
    my $configuration   = shift;
    my $binary     = shift;
    add_file( $configuration_directory, $filepath, $configuration, $binary )
}
\end{verbatim}
\newpage
\subsection{ROBOTestFrame/add\_file}
\textsl{[ ROBOTestFrame ]}
\textsl{[ Functions ]}

\label{ch:robo45}
\label{ch:ROBOTestFrame_add_file}
\index{unsorted!add\_file}\index{Functions!add\_file}
\textbf{FUNCTION}

   Add a single file somewhere in base\_path.

\textbf{INPUTS}
\begin{itemize}
  \item    base\_path -- base path
  \item    filepath -- relative path to a file.
  \item    content  -- the content to go into this file
  \item    binary -- write the raw bytes. [optional]
\end{itemize}


\textbf{SOURCE}
\begin{verbatim}
sub add_file
{
    my $base_path = shift;
    my $filepath  = shift;
    my $content   = shift;
    my $binary    = shift;

    my $path = $base_path . dirname( $filepath );

    $path =~ s/\.$//;  # Fix for Perl 5.8.0 under Linux.

    if ( ! -e "$path" ) {
        mkpath $path or die "can't create $path";
    }

    my $full_filepath = "$base_path/$filepath";
    my $file = IO::File->new(">$full_filepath") or 
         die "Can't open $full_filepath";
    if ( $binary and ( $binary eq 'binary' ) ) {
        binmode( $file );
    }
    print $file $content;
    $file->close();
}
\end{verbatim}
\newpage
\subsection{ROBOTestFrame/add\_source}
\textsl{[ ROBOTestFrame ]}
\textsl{[ Functions ]}

\label{ch:robo46}
\label{ch:ROBOTestFrame_add_source}
\index{unsorted!add\_source}\index{Functions!add\_source}
\textbf{FUNCTION}

   Add a single source file somewhere in Src/

\textbf{INPUTS}
\begin{itemize}
  \item    filepath -- path to a file.
  \item    source\_code -- the source code to go into this file
  \item    binary -- write the raw bytes. [optional]
\end{itemize}


\textbf{SOURCE}
\begin{verbatim}
sub add_source
{
    my $filepath = shift;
    my $source_code   = shift;
    my $binary     = shift;

    add_file( $source_directory, $filepath, $source_code, $binary )
}
\end{verbatim}
\newpage
\subsection{ROBOTestFrame/clean}
\textsl{[ ROBOTestFrame ]}
\textsl{[ Functions ]}

\label{ch:robo47}
\label{ch:ROBOTestFrame_clean}
\index{unsorted!clean}\index{Functions!clean}
\textbf{FUNCTION}

    Clean source and documentation directories.

\textbf{SOURCE}
\begin{verbatim}
sub clean
{
    if ( -e $source_directory ) {
        rmtree( $source_directory ) or die;
    }
    if ( -e $documentation_directory ) {
        rmtree( $documentation_directory ) or die;
    }
    if ( -e $configuration_directory ) {
        rmtree( $configuration_directory ) or die;
    }
}
\end{verbatim}
\newpage
\subsection{ROBOTestFrame/configuration\_directory}
\textsl{[ ROBOTestFrame ]}
\textsl{[ Functions ]}

\label{ch:robo48}
\label{ch:ROBOTestFrame_configuration_directory}
\index{unsorted!configuration\_directory}\index{Functions!configuration\_directory}
\textbf{FUNCTION}

   Name of the documentation directory used to test ROBODoc.

\textbf{SOURCE}
\begin{verbatim}
my $configuration_directory = "Config";
\end{verbatim}
\newpage
\subsection{ROBOTestFrame/documentation\_directory}
\textsl{[ ROBOTestFrame ]}
\textsl{[ Functions ]}

\label{ch:robo49}
\label{ch:ROBOTestFrame_documentation_directory}
\index{unsorted!documentation\_directory}\index{Functions!documentation\_directory}
\textbf{FUNCTION}

   Name of the documentation directory used to test ROBODoc.

\textbf{SOURCE}
\begin{verbatim}
my $documentation_directory  = "Doc";
\end{verbatim}
\newpage
\subsection{ROBOTestFrame/is\_latex\_balanced}
\textsl{[ ROBOTestFrame ]}
\textsl{[ Functions ]}

\label{ch:robo50}
\label{ch:ROBOTestFrame_is_latex_balanced}
\index{unsorted!is\_latex\_balanced}\index{Functions!is\_latex\_balanced}
\textbf{FUNCTION}

   Test the balance of a latex file.
   A latex file is balanced if every

\begin{verbatim}
     /begin{xxxx}
\end{verbatim}

   is ended with a

\begin{verbatim}
     /end{xxx}
\end{verbatim}


\textbf{INPUTS}
\begin{itemize}
  \item    path - path to a latex file.
\end{itemize}

 RETURNS
   * 0 -- file is not balanced
   * 1 -- file is balanced

\textbf{SOURCE}
\begin{verbatim}
sub is_latex_balanced {
    my $path = shift;
    my @stack;
    local( $/ ) ;
    my $file = IO::File->new("<$path") or die "$path : $!";
    my $string = <$file>;
    $file->close();

    while ( $string =~ m/(begin|end)\{([^}]+)\}/g ) {
        my $b_e  = $1;  # begin or end
        my $kind = $2;  # document, or equation, or ...
        if ( $b_e eq "begin" ) {
            push( @stack, $kind );
        } else {
            if ( pop( @stack ) eq $kind ) {
                # OK.  begin and end matches.
            } else {
                # Not OK!  
                #   begin{ something }
                # followed by 
                #   end{ something else }
                return 0;  # Failure.
            }

        }
    }
    if ( scalar( @stack ) ) {
        # there are items left!
        return 0; # Not OK.
    }
    return 1;  # OK!
}
\end{verbatim}
\newpage
\subsection{ROBOTestFrame/mkdocdir}
\textsl{[ ROBOTestFrame ]}
\textsl{[ Functions ]}

\label{ch:robo51}
\label{ch:ROBOTestFrame_mkdocdir}
\index{unsorted!mkdocdir}\index{Functions!mkdocdir}
\textbf{FUNCTION}

   Create a empty documentation directory.
   This is handy for tests that use --singledoc.

\textbf{SOURCE}
\begin{verbatim}
sub mkdocdir
{
    if ( ! -e $documentation_directory ) {
        mkpath( $documentation_directory );
    }
}
\end{verbatim}
\newpage
\subsection{ROBOTestFrame/read\_hexdump}
\textsl{[ ROBOTestFrame ]}
\textsl{[ Functions ]}

\label{ch:robo52}
\label{ch:ROBOTestFrame_read_hexdump}
\index{unsorted!read\_hexdump}\index{Functions!read\_hexdump}
\textbf{FUNCTION}

   Reads a hexdump made with xxd (part of vim http://www.vim.org/) 
   This makes it possible to add files with all kinds of
   different formats and characters.



   Storing it in hexdump format makes sure that these files are
   not changed when they are checked into cvs or unzipped.



   This makes is possible to test cr/lf problems and internationalization
   issues.

\textbf{INPUTS}
\begin{itemize}
  \item    path - path to a hexdump file.
\end{itemize}

 RETURNS
   The decoded content of the file as a single string.

\textbf{SOURCE}
\begin{verbatim}
sub read_hexdump {
    my $path = shift;
    my $file = IO::File->new("<$path") or die "$path : $!";

    my $string = '';
    my @all_bytes = ();
    while ( my $line = <$file> ) {
        $line =~ s/^\S+:\s//; # remove address
        $line =~ s/\s\s+.*$//; # remove ascii
        $line =~ s/(\S\S)(\S\S)/$1 $2/g;
        # Now only the words are left.
        my @data = split( /\s/, $line );
        my @bytes = map { chr hex } @data;
        push( @all_bytes, @bytes );
    }
    # TODO try a join() here.
    foreach my $c ( @all_bytes ) {
        $string .= $c;
    }

    $file->close();
    return $string;
}
\end{verbatim}
\newpage
\subsection{ROBOTestFrame/robo\_win, robo\_unix}
\textsl{[ ROBOTestFrame ]}
\textsl{[ Functions ]}

\label{ch:robo53}
\label{ch:ROBOTestFrame_robo_win}
\index{unsorted!robo\_win}\index{Functions!robo\_win}
\textbf{FUNCTION}

   Location of the ROBODoc executable.

\textbf{SOURCE}
\begin{verbatim}
my $robo_win = "../robodoc.exe";
my $robo_unix = "../robodoc";
\end{verbatim}
\newpage
\subsection{ROBOTestFrame/runrobo}
\textsl{[ ROBOTestFrame ]}
\textsl{[ Functions ]}

\label{ch:robo54}
\label{ch:ROBOTestFrame_runrobo}
\index{unsorted!runrobo}\index{Functions!runrobo}
\textbf{FUNCTION}

   Run robodoc with the given set of
   arguments and capture all output to
   stdout en stderr.

\textbf{INPUTS}

   A list of options for robodoc.exr
 RETURNS
   stdout and stderr.

\textbf{SOURCE}
\begin{verbatim}
sub runrobo
{
    my $robo = '';
    if ( $^O eq 'linux' ) {
        $robo = $robo_unix;
    } else {
        $robo = $robo_win;
    }
    run( [ $robo, @_ ], \my( $in, $out, $err ) );
    return ($out, $err);
}
\end{verbatim}
\newpage
\subsection{ROBOTestFrame/source\_directory}
\textsl{[ ROBOTestFrame ]}
\textsl{[ Functions ]}

\label{ch:robo55}
\label{ch:ROBOTestFrame_source_directory}
\index{unsorted!source\_directory}\index{Functions!source\_directory}
\textbf{FUNCTION}

   Name of the source directory used to test ROBODoc.

\textbf{SOURCE}
\begin{verbatim}
my $source_directory  = "Src";
\end{verbatim}
\printindex
\end{document}