• Table of Contents
• Previous Chapter

Chapter 6: Technical information

6.1: Obtaining Yodl

The package is found in various yodl-X.Y.Z files, where X is the highest version number. This is a gzipped archive containing all sources, documentation and macro files. In the yodl directory archives having the .deb extension can also be found: these are Debian files, containing all information that is required to install binary versions using Debian's dpkg --install command.

6.1.1: Installing Yodl

• Yodl's binaries in /usr/bin;
• Yodl's macros in /usr/share/yodl
• Yodl's documentation in /usr/share/doc/yodl;
• Yodl's manpages in /usr/share/man/man{1,7};

If a local installation is preferred or required, unpack the file yodl-X.Y.Z.tar.gz. Next, chdir to the directory yodl-X.Y.Z, and optionally tweak the file config to your needs. Next, issue the command:

    build package
        

    build install /usr
        

    build install /usr/local
        

However, by far the easiest way to install a binary distribution is to use the Debian dpkg --install yodl*.deb command. Dpkg will install the various parts according to Debian's conventions under usr/.

Installation from source requires you to have the following programs installed on your system:

• A C compiler and run-time environment. A POSIX-compliant compiler, libraries and set of header files should work without problems. The GNU gcc compiler 3.3.4 and higher should work flawlessly.
• Icmake: Icmake is part of the standard Debian distribution, and can also be obtained from ftp://ftp.rug.nl/.
• Standard tools, like sed, grep, perl, etc..
• /bin/sh: a POSIX-compliant shell interpreter. The GNU shell interpreter bash can be used instead.

6.2: Organization of the software

Much of the documentation is provided in the individual source files themselves. This section, however, should offer the `broad picture', allowing you to understand the logic behind Yodl relatively fast.

6.2.1: Subdirectories and their meanings

• yodl: the root-directory of the Yodl tree. All sources and program maintenance scripts are found in or below this directory.
• debian: an auxiliary directory containing all files and directories required to cused to send txt commands to the output.

  E.g., the following code sends a TXT command <hr> to the output file when in TXT mode:

  COMMENT(-- alternative 1, using txtcommand --)
      txtcommand(<hr>)
      
      COMMENT(-- alternative 2, using NOTRANS --)
      IFDEF(txt)(
          NOTRANS(<hr>)
      )()
          
  

  5.6: The experimental XML converter

  The XML converter is experimental. It was added to Yodl to allow me to write documents for the horrible `webplatform' of the university of Groningen. The XML support files (located in the xml directory in the standard macro's directory) clearly reflect this target. Although experimental, they were kept because the XML macros support interesting constructions allowing Yodl to handle closing tags somewhat more strict than required for HTML.

  5.7: The Yodl Post-processor `yodlpost'

  Following the conversion of a Yodl text, most target-languages require an additional operation, called `post-processing'. Post-processing is required for various reasons: to split the output in separate files (HTML, XML); to fixup the locations of labels, that are referred to earlier than the labels are defined (virtually all target language except LaTeX); tables of contents are available only after the conversion, but will have to be inserted at the beginning of the document; etc. etc..

  Starting with Yodl V. 2.00 there is only one post-processor, handling all the conversions for all target languages. Program maintenance of just one program is certainly easier than maintenance of as many programs as there are target-languages, at the expense of only a slightly larger program: after all, the one post-processor contains the conversion procedures for all target languages. It turns out that this is a very minimal drawback. See section 6.7 for the technical details of post-processor program maintenance.

  The post-processor that is distributed since Yodl V. 2.00 does not use the .tt(Yodl)TAGSTART. and .tt(Yodl)TAGEND. tags anymore. Instead, the conversion process produces a index file in which comparable information is written. The advantage of using an index file is that the postprocessor doesn't have to parse the output file generated by Yodl twice (once to determine the tags, once to process the tags), which by itself accelerates the conversion process; and (albeit of a somewhat limited practical importance) that the tags are no longer reserved words: authors may put .tt(Yodl)TAGSTART. and .tt(Yodl)TAGEND. into their texts as often as they want.

  Authors should be aware of some caveats with respect to some target languages:

  man- and ms- conversions

  all dots are converted by the active character conversion table to \&.. Commands in these languages always start with a dot as the first character on a line. In order to insert these commands the roffcmd() (see section MACROLIST) should be used.

  plain text conversions

  As stated before, the ASCII converter basically only strips macronames from its input. This converter is so basic, that it should only be used as a last resort, when no other target language is available for the job.
  With the plain text converer, the layout of the input file is very important, as the output is basically the same as the input. The only exception to this rule are multiple empty lines, which normally are consumed by the post-processor, to be replaced by one single empty line.

  sgml conversions

  the SGML converter was implemented for historic reasons. It is by no means complete, and can at best be considered an `initial starting point'. Currently, the SGML converter only supports the article document type, having sect as its top-level sectioning command.

  xml conversions

  The XML converter was implemented to allow me (Frank) to produce XML text as defined by the so-called `webplatform' of the University of Groningen. A completely pathological implementation of XML, crippling its users to the level of the `double click brigade'. Well, so be it. The net result of this is that Yodl now offers some sort of XML conversion, which will surely require modifications in the near future. Much XML handling is based on frame-files which are literally inserted into the converted text. Hopefully that will be useful when constructing XML conversions for other environments than the `webplatform'.

  5.8: The support program `yodlverbinsert'

  The program yodlverbinsert is a simple C support program that can be used to generate verb()-sections in Yodl files from sections of existing files. The files from which sections are included are usually C or Cpp source files, accepting either // or /*-style comment.

  Yodlverbinsert offers the possibility to indent both the initial verb-statement and the inserted file contents. Furthermore, an additional empty line may be inserted before the first line that is actually inserted. The program is invoked according to the following synopsis:

  yodlverbinsert [OPTIONS] marker file

  The arguments have the following meanings;

  • marker
    The argument marker must start in file's first column en must either start as a standard C or C++ comment: // or /* must be used. Following that, the remainder of the argument is used as a label, e.g., //label, /*LABEL*/. The label may contain non-alpha characters as well. Except for the first two characters and their locations no special restrictions imposed upon the label texts. A labeled section ends at the next //= (when the label started with //) or at the next /**/ (when the label started with /*). Like the labels, the end-markers must also start in the file's first column.
  • file
    The argument file must be an existing file. Yodlverbinsert was designed with C or C++ sources in minde, from which labeled sections must be inserted into a Yodl document, but file could also refer to another type of (text) file.

  The default values of options are listed below, with each of the options between square brackets. The defaults were chosen so that yodlverbinsert performs the behavior of an earlier version of this program, which was not distributed with Yodl.

  • -N
    Do not write a newline immediately following verb-statement's open-parenthesis. By default it is written, causing an additional line to be inserted before the first line that's actually inserted from a file.
  • -s spaces [0]
    start each line that is written into the verb-section with spaces additional blanks.
  • -S spaces [8]
    prefix the verb of the verb-section by spaces additional blanks.
  • -t tabs [0]
    start each line that is written into the verb-section with tabs additional tab characters. If both -s and -t are specified, the tabs are inserted first.
  • -T tabs [0]
    prefix the verb of the verb-section by tabs additional tab characters. If both -S and -T are specified, the tabs are inserted first.

  Yodlverbinsert writes its selected section to its standard output stream.

  5.8.1: Example

  Assume the file demo contains the following text:

  
  preceding text
  
  //one
  one 1
  
  //=
  
  /*two*/
  
      two
  
  /**/
  
  trailing text
      
  

  Then the following commands write the shown output to the program's standard output:

  • verbinclude //one demo
    

            verb(
    one 1
    
    )
    
    

  • verbinclude -N //one demo
    

            verb(one 1
    
    )
    
    

  • verbinclude -s4 '/*two*/' demo
    

            verb(
        
            two
        
    )
    
    

  To call yodlverbinsert from a Yodl document, use PIPETHROUGH. E.g.,

  
      PIPETHROUGH(yodlverbinsert //one demo)
          
  

  Alternatively, define a simple macro like the macro verbinsert:

  
  DEFINEMACRO(verbinsert)(2)(PIPETHROUGH(yodlverbinsert //ARG1 ARG2)()\ 
  )
      
  

  which may be a useful macro if all or most of your labeled sections start with //, and if yodlverbinsert's arguments don't vary much. Variants to this macro can easily be conceived of.

  Note, however, that by default the PIPETHROUGH built-in will not be executed. Be sure to call yodl using the --live-data option, e.g., yodl -l3 ....

  ---

  • Table of Contents
  • Previous Chapter
  • Next Chapter

  ---

  ./usr/share/doc/yodl/yodl06.html0000644000000000000000000013360411066511733015355 0ustar rootroot

  ---

  • Table of Contents
  • Previous Chapter

  ---

  Chapter 6: Technical information

  This chapter consists of various sections. The first section describes Yodl from the point of view of the systems administrator. Issues such as the installation of the package are addressed here. The second section describes Yodl's technical implementation in some detail. Apart from the documentation about Yodl given here, much can be found in the individual source files. However, section 6.2 describes `the broad picture'. Having read section 6.2, it should be relatively easy to determine what happens where inside the Yodl program and the yodl-post post processor.

  6.1: Obtaining Yodl

  Yodl and the distributed macro package can be obtained at the ftp site ftp.rug.nl in the directory contrib/frank/software/linux/yodl.

  The package is found in various yodl-X.Y.Z files, where X is the highest version number. This is a gzipped archive containing all sources, documentation and macro files. In the yodl directory archives having the .deb extension can also be found: these are Debian files, containing all information that is required to install binary versions using Debian's dpkg --install command.

  6.1.1: Installing Yodl

  The binary package, distributed in yodl-X.Y.Z_a.b.c.deb can be installed using dpkg -install yodl-X.Y.Z. It will install:
  • Yodl's binaries in /usr/bin;
  • Yodl's macros in /usr/share/yodl
  • Yodl's documentation in /usr/share/doc/yodl;
  • Yodl's manpages in /usr/share/man/man{1,7};
  Local installations, not using the Debian installation process, can be obtained using the provided icmake build-script see below. An alternative is to use make.

  If a local installation is preferred or required, unpack the file yodl-X.Y.Z.tar.gz. Next, chdir to the directory yodl-X.Y.Z, and optionally tweak the file config to your needs. Next, issue the command:

  
      build package
          
  

  Followed by

  
      build install /usr
          
  

  or

  
      build install /usr/local
          
  

  The installation process will install the binaries, manual pages, other documentation and macro files under the indicated directory. For each part of the Yodl package a separate build script is available (repsectively in the src, macros, man and manual subdirectories under the common .../yodl-root where the main build script is found). Each of these build scripts can be called using build install xxx as well, allowing you to store Yodl's various parts in completely different directories.

  However, by far the easiest way to install a binary distribution is to use the Debian dpkg --install yodl*.deb command. Dpkg will install the various parts according to Debian's conventions under usr/.

  Installation from source requires you to have the following programs installed on your system:

  • A C compiler and run-time environment. A POSIX-compliant compiler, libraries and set of header files should work without problems. The GNU gcc compiler 3.3.4 and higher should work flawlessly.
  • Icmake: Icmake is part of the standard Debian distribution, and can also be obtained from ftp://ftp.rug.nl/.
  • Standard tools, like sed, grep, perl, etc..
  • /bin/sh: a POSIX-compliant shell interpreter. The GNU shell interpreter bash can be used instead.

  6.2: Organization of the software

  This section describes the organization of the source files. Its contents are not necessarily relevant for the binary distribution. The section is probably most useful to those readers who want to be able to extend or who want to do maintenance on Yodl's sources, or who want simply to understand what's happening inside the Yodl program.

  Much of the documentation is provided in the individual source files themselves. This section, however, should offer the `broad picture', allowing you to understand the logic behind Yodl relatively fast.

  6.2.1: Subdirectories and their meanings

  After unpacking Yodl's source archive, the following directories are available:
  • yodl: the root-directory of the Yodl tree. All sources and program maintenance scripts are found in or below this directory.
  • debian: an auxiliary directory containing all files and directories required to cused to send txt commands to the output.

    E.g., the following code sends a TXT command <hr> to the output file when in TXT mode:

    COMMENT(-- alternative 1, using txtcommand --)
        txtcommand(<hr>)
        
        COMMENT(-- alternative 2, using NOTRANS --)
        IFDEF(txt)(
            NOTRANS(<hr>)
        )()
            
    

    5.6: The experimental XML converter

    The XML converter is experimental. It was added to Yodl to allow me to write documents for the horrible `webplatform' of the university of Groningen. The XML support files (located in the xml directory in the standard macro's directory) clearly reflect this target. Although experimental, they were kept because the XML macros support interesting constructions allowing Yodl to handle closing tags somewhat more strict than required for HTML.

    5.7: The Yodl Post-processor `yodlpost'

    Following the conversion of a Yodl text, most target-languages require an additional operation, called `post-processing'. Post-processing is required for various reasons: to split the output in separate files (HTML, XML); to fixup the locations of labels, that are referred to earlier than the labels are defined (virtually all target language except LaTeX); tables of contents are available only after the conversion, but will have to be inserted at the beginning of the document; etc. etc..

    Starting with Yodl V. 2.00 there is only one post-processor, handling all the conversions for all target languages. Program maintenance of just one program is certainly easier than maintenance of as many programs as there are target-languages, at the expense of only a slightly larger program: after all, the one post-processor contains the conversion procedures for all target languages. It turns out that this is a very minimal drawback. See section 6.7 for the technical details of post-processor program maintenance.

    The post-processor that is distributed since Yodl V. 2.00 does not use the .tt(Yodl)TAGSTART. and .tt(Yodl)TAGEND. tags anymore. Instead, the conversion process produces a index file in which comparable information is written. The advantage of using an index file is that the postprocessor doesn't have to parse the output file generated by Yodl twice (once to determine the tags, once to process the tags), which by itself accelerates the conversion process; and (albeit of a somewhat limited practical importance) that the tags are no longer reserved words: authors may put .tt(Yodl)TAGSTART. and .tt(Yodl)TAGEND. into their texts as often as they want.

    Authors should be aware of some caveats with respect to some target languages:

    man- and ms- conversions

    all dots are converted by the active character conversion table to \&.. Commands in these languages always start with a dot as the first character on a line. In order to insert these commands the roffcmd() (see section MACROLIST) should be used.

    plain text conversions

    As stated before, the ASCII converter basically only strips macronames from its input. This converter is so basic, that it should only be used as a last resort, when no other target language is available for the job.
    With the plain text converer, the layout of the input file is very important, as the output is basically the same as the input. The only exception to this rule are multiple empty lines, which normally are consumed by the post-processor, to be replaced by one single empty line.

    sgml conversions

    the SGML converter was implemented for historic reasons. It is by no means complete, and can at best be considered an `initial starting point'. Currently, the SGML converter only supports the article document type, having sect as its top-level sectioning command.

    xml conversions

    The XML converter was implemented to allow me (Frank) to produce XML text as defined by the so-called `webplatform' of the University of Groningen. A completely pathological implementation of XML, crippling its users to the level of the `double click brigade'. Well, so be it. The net result of this is that Yodl now offers some sort of XML conversion, which will surely require modifications in the near future. Much XML handling is based on frame-files which are literally inserted into the converted text. Hopefully that will be useful when constructing XML conversions for other environments than the `webplatform'.

    5.8: The support program `yodlverbinsert'

    The program yodlverbinsert is a simple C support program that can be used to generate verb()-sections in Yodl files from sections of existing files. The files from which sections are included are usually C or Cpp source files, accepting either // or /*-style comment.

    Yodlverbinsert offers the possibility to indent both the initial verb-statement and the inserted file contents. Furthermore, an additional empty line may be inserted before the first line that is actually inserted. The program is invoked according to the following synopsis:

    yodlverbinsert [OPTIONS] marker file

    The arguments have the following meanings;

    • marker
      The argument marker must start in file's first column en must either start as a standard C or C++ comment: // or /* must be used. Following that, the remainder of the argument is used as a label, e.g., //label, /*LABEL*/. The label may contain non-alpha characters as well. Except for the first two characters and their locations no special restrictions imposed upon the label texts. A labeled section ends at the next //= (when the label started with //) or at the next /**/ (when the label started with /*). Like the labels, the end-markers must also start in the file's first column.
    • file
      The argument file must be an existing file. Yodlverbinsert was designed with C or C++ sources in minde, from which labeled sections must be inserted into a Yodl document, but file could also refer to another type of (text) file.

    The default values of options are listed below, with each of the options between square brackets. The defaults were chosen so that yodlverbinsert performs the behavior of an earlier version of this program, which was not distributed with Yodl.

    • -N
      Do not write a newline immediately following verb-statement's open-parenthesis. By default it is written, causing an additional line to be inserted before the first line that's actually inserted from a file.
    • -s spaces [0]
      start each line that is written into the verb-section with spaces additional blanks.
    • -S spaces [8]
      prefix the verb of the verb-section by spaces additional blanks.
    • -t tabs [0]
      start each line that is written into the verb-section with tabs additional tab characters. If both -s and -t are specified, the tabs are inserted first.
    • -T tabs [0]
      prefix the verb of the verb-section by tabs additional tab characters. If both -S and -T are specified, the tabs are inserted first.

    Yodlverbinsert writes its selected section to its standard output stream.

    5.8.1: Example

    Assume the file demo contains the following text:

    
    preceding text
    
    //one
    one 1
    
    //=
    
    /*two*/
    
        two
    
    /**/
    
    trailing text
        
    

    Then the following commands write the shown output to the program's standard output:

    • verbinclude //one demo
      

              verb(
      one 1
      
      )
      
      

    • verbinclude -N //one demo
      

              verb(one 1
      
      )
      
      

    • verbinclude -s4 '/*two*/' demo
      

              verb(
          
              two
          
      )
      
      

    To call yodlverbinsert from a Yodl document, use PIPETHROUGH. E.g.,

    
        PIPETHROUGH(yodlverbinsert //one demo)
            
    

    Alternatively, define a simple macro like the macro verbinsert:

    
    DEFINEMACRO(verbinsert)(2)(PIPETHROUGH(yodlverbinsert //ARG1 ARG2)()\ 
    )
        
    

    which may be a useful macro if all or most of your labeled sections start with //, and if yodlverbinsert's arguments don't vary much. Variants to this macro can easily be conceived of.

    Note, however, that by default the PIPETHROUGH built-in will not be executed. Be sure to call yodl using the --live-data option, e.g., yodl -l3 ....

    ---

    • Table of Contents
    • Previous Chapter
    • Next Chapter

    ---

    ./usr/share/doc/yodl/yodl06.html0000644000000000000000000013360411066511733015355 0ustar rootroot

    ---

    • Table of Contents
    • Previous Chapter

    ---

    Chapter 6: Technical information

    This chapter consists of various sections. The first section describes Yodl from the point of view of the systems administrator. Issues such as the installation of the package are addressed here. The second section describes Yodl's technical implementation in some detail. Apart from the documentation about Yodl given here, much can be found in the individual source files. However, section 6.2 describes `the broad picture'. Having read section 6.2, it should be relatively easy to determine what happens where inside the Yodl program and the yodl-post post processor.

    6.1: Obtaining Yodl

    Yodl and the distributed macro package can be obtained at the ftp site ftp.rug.nl in the directory contrib/frank/software/linux/yodl.

    The package is found in various yodl-X.Y.Z files, where X is the highest version number. This is a gzipped archive containing all sources, documentation and macro files. In the yodl directory archives having the .deb extension can also be found: these are Debian files, containing all information that is required to install binary versions using Debian's dpkg --install command.

    6.1.1: Installing Yodl

    The binary package, distributed in yodl-X.Y.Z_a.b.c.deb can be installed using dpkg -install yodl-X.Y.Z. It will install:
    • Yodl's binaries in /usr/bin;
    • Yodl's macros in /usr/share/yodl
    • Yodl's documentation in /usr/share/doc/yodl;
    • Yodl's manpages in /usr/share/man/man{1,7};
    Local installations, not using the Debian installation process, can be obtained using the provided icmake build-script see below. An alternative is to use make.

    If a local installation is preferred or required, unpack the file yodl-X.Y.Z.tar.gz. Next, chdir to the directory yodl-X.Y.Z, and optionally tweak the file config to your needs. Next, issue the command:

    
        build package
            
    

    Followed by

    
        build install /usr
            
    

    or

    
        build install /usr/local
            
    

    The installation process will install the binaries, manual pages, other documentation and macro files under the indicated directory. For each part of the Yodl package a separate build script is available (repsectively in the src, macros, man and manual subdirectories under the common .../yodl-root where the main build script is found). Each of these build scripts can be called using build install xxx as well, allowing you to store Yodl's various parts in completely different directories.

    However, by far the easiest way to install a binary distribution is to use the Debian dpkg --install yodl*.deb command. Dpkg will install the various parts according to Debian's conventions under usr/.

    Installation from source requires you to have the following programs installed on your system:

    • A C compiler and run-time environment. A POSIX-compliant compiler, libraries and set of header files should work without problems. The GNU gcc compiler 3.3.4 and higher should work flawlessly.
    • Icmake: Icmake is part of the standard Debian distribution, and can also be obtained from ftp://ftp.rug.nl/.
    • Standard tools, like sed, grep, perl, etc..
    • /bin/sh: a POSIX-compliant shell interpreter. The GNU shell interpreter bash can be used instead.

    6.2: Organization of the software

    This section describes the organization of the source files. Its contents are not necessarily relevant for the binary distribution. The section is probably most useful to those readers who want to be able to extend or who want to do maintenance on Yodl's sources, or who want simply to understand what's happening inside the Yodl program.

    Much of the documentation is provided in the individual source files themselves. This section, however, should offer the `broad picture', allowing you to understand the logic behind Yodl relatively fast.

    6.2.1: Subdirectories and their meanings

    After unpacking Yodl's source archive, the following directories are available:
    • yodl: the root-directory of the Yodl tree. All sources and program maintenance scripts are found in or below this directory.
    • debian: an auxiliary directory containing all files and directories required to cused to send txt commands to the output.

      E.g., the following code sends a TXT command <hr> to the output file when in TXT mode:

      COMMENT(-- alternative 1, using txtcommand --)
          txtcommand(<hr>)
          
          COMMENT(-- alternative 2, using NOTRANS --)
          IFDEF(txt)(
              NOTRANS(<hr>)
          )()
              
      

      5.6: The experimental XML converter

      The XML converter is experimental. It was added to Yodl to allow me to write documents for the horrible `webplatform' of the university of Groningen. The XML support files (located in the xml directory in the standard macro's directory) clearly reflect this target. Although experimental, they were kept because the XML macros support interesting constructions allowing Yodl to handle closing tags somewhat more strict than required for HTML.

      5.7: The Yodl Post-processor `yodlpost'

      Following the conversion of a Yodl text, most target-languages require an additional operation, called `post-processing'. Post-processing is required for various reasons: to split the output in separate files (HTML, XML); to fixup the locations of labels, that are referred to earlier than the labels are defined (virtually all target language except LaTeX); tables of contents are available only after the conversion, but will have to be inserted at the beginning of the document; etc. etc..

      Starting with Yodl V. 2.00 there is only one post-processor, handling all the conversions for all target languages. Program maintenance of just one program is certainly easier than maintenance of as many programs as there are target-languages, at the expense of only a slightly larger program: after all, the one post-processor contains the conversion procedures for all target languages. It turns out that this is a very minimal drawback. See section 6.7 for the technical details of post-processor program maintenance.

      The post-processor that is distributed since Yodl V. 2.00 does not use the .tt(Yodl)TAGSTART. and .tt(Yodl)TAGEND. tags anymore. Instead, the conversion process produces a index file in which comparable information is written. The advantage of using an index file is that the postprocessor doesn't have to parse the output file generated by Yodl twice (once to determine the tags, once to process the tags), which by itself accelerates the conversion process; and (albeit of a somewhat limited practical importance) that the tags are no longer reserved words: authors may put .tt(Yodl)TAGSTART. and .tt(Yodl)TAGEND. into their texts as often as they want.

      Authors should be aware of some caveats with respect to some target languages:

      man- and ms- conversions

      all dots are converted by the active character conversion table to \&.. Commands in these languages always start with a dot as the first character on a line. In order to insert these commands the roffcmd() (see section MACROLIST) should be used.

      plain text conversions

      As stated before, the ASCII converter basically only strips macronames from its input. This converter is so basic, that it should only be used as a last resort, when no other target language is available for the job.
      With the plain text converer, the layout of the input file is very important, as the output is basically the same as the input. The only exception to this rule are multiple empty lines, which normally are consumed by the post-processor, to be replaced by one single empty line.

      sgml conversions

      the SGML converter was implemented for historic reasons. It is by no means complete, and can at best be considered an `initial starting point'. Currently, the SGML converter only supports the article document type, having sect as its top-level sectioning command.

      xml conversions

      The XML converter was implemented to allow me (Frank) to produce XML text as defined by the so-called `webplatform' of the University of Groningen. A completely pathological implementation of XML, crippling its users to the level of the `double click brigade'. Well, so be it. The net result of this is that Yodl now offers some sort of XML conversion, which will surely require modifications in the near future. Much XML handling is based on frame-files which are literally inserted into the converted text. Hopefully that will be useful when constructing XML conversions for other environments than the `webplatform'.

      5.8: The support program `yodlverbinsert'

      The program yodlverbinsert is a simple C support program that can be used to generate verb()-sections in Yodl files from sections of existing files. The files from which sections are included are usually C or Cpp source files, accepting either // or /*-style comment.

      Yodlverbinsert offers the possibility to indent both the initial verb-statement and the inserted file contents. Furthermore, an additional empty line may be inserted before the first line that is actually inserted. The program is invoked according to the following synopsis:

      yodlverbinsert [OPTIONS] marker file

      The arguments have the following meanings;

      • marker
        The argument marker must start in file's first column en must either start as a standard C or C++ comment: // or /* must be used. Following that, the remainder of the argument is used as a label, e.g., //label, /*LABEL*/. The label may contain non-alpha characters as well. Except for the first two characters and their locations no special restrictions imposed upon the label texts. A labeled section ends at the next //= (when the label started with //) or at the next /**/ (when the label started with /*). Like the labels, the end-markers must also start in the file's first column.
      • file
        The argument file must be an existing file. Yodlverbinsert was designed with C or C++ sources in minde, from which labeled sections must be inserted into a Yodl document, but file could also refer to another type of (text) file.

      The default values of options are listed below, with each of the options between square brackets. The defaults were chosen so that yodlverbinsert performs the behavior of an earlier version of this program, which was not distributed with Yodl.

      • -N
        Do not write a newline immediately following verb-statement's open-parenthesis. By default it is written, causing an additional line to be inserted before the first line that's actually inserted from a file.
      • -s spaces [0]
        start each line that is written into the verb-section with spaces additional blanks.
      • -S spaces [8]
        prefix the verb of the verb-section by spaces additional blanks.
      • -t tabs [0]
        start each line that is written into the verb-section with tabs additional tab characters. If both -s and -t are specified, the tabs are inserted first.
      • -T tabs [0]
        prefix the verb of the verb-section by tabs additional tab characters. If both -S and -T are specified, the tabs are inserted first.

      Yodlverbinsert writes its selected section to its standard output stream.

      5.8.1: Exampl