Tutorials

First Steps
Creating a new C/C++ project
Using LEP in an existing eclipse project
Using LEP to create a webpage
Plugin Preferences
File based settings
Settings for the C++-Compiler
Reference Codeblocks
Use LaTeX formatting in blocknames
Writing an API documentation

Creating a new C/C++ project

This section covers the creation and usage of an C++ project, explains the structure of a lep file and the usage of codeblocks.

For C++ projects, lep has its own project wizard in the group "Literate Eclipse Programming" which can be reached under "File->New->Project...". Like other eclipse projects, it creates a folder for you. The most important file in this folder is the lep file, which is opened in a new editor after project creation.

If you know LaTeX, the content of the lep file will look familiar to you. If you don‘t know LaTeX, this sides may give you an overview:

Codeblocks are the only difference to a normal LaTeX file. Basically, codeblocks contain text, which should be written to external files or which should be used in other codeblocks. The sample lep file contains two such blocks, they can be placed anywhere in the file. Lets have a look at the first block:

    <<code/HelloWorld.cpp>>=
    #include <iostream>
    
    int main(int argc, char** argv) {
        int i=0;
        <<Print>>
        return 0;
    }
    @

The first line of the block determines its name. Because of the dot in the name, this name is detected as a file path. The path is relative to the path of the lep file and to the eclipse project. When the file is saved, a new subfolder code is created in the project folder and the content of this block is written to the file HelloWorld.cpp.

The content, that is everything between the first line and a final line with just an @ at its beginning. But wait, as it was said, codeblocks can be used inside other codeblocks. In our block here, the line <<Print>> is replaced with all the content of the block named Print:

    <<Print>>=
        std::cout<<"Hello World"<<std::endl;
    @

It is not important, if Print is located before or after the block, in which it is used. On last thing that you can do with codeblocks is, that they can be continued. Every time you name a block like another one, the content of those blocks is concatenated. When you do this, the location is important: the order of concatenation follows the order of appearance in the file.

What do we have now? We have a lep file, which is basically a LaTeX file. People use LaTeX files to get good looking pdf files. The LEP plugin builds the pdf automatically when you save the file. After the pdf is created, it is opened in a new eclipse editor. To find the current cursor position quickly in the pdf, you can use the "Goto PDF"-command from the "LEP"-menu. To go the other way round, just do a right click inside the pdf.

Because this file contains also one codeblock with a filename, we have also a C++ code file. Code files are compiled and linked to produce an executable. The lep file lives inside of an C++ project and eclipse together with the CDT plugin do all the work for us to turn our code file into an executable. To build the executable just use "Build Project" from the "Project"-menu. Errors and warnings which the compiler may find will show up in the according line in the lep editor. If everything is fine, use "Run" or "Debug" from the "Run"-menu. If you use "Debug" the debugger will stop in the first line of the main function. If you want it to stop on another location, set a breakpoint by using "Toggle Breakpoint" from the "LEP"-menu. To help you in writing your own C++ code, LEP uses the CDT-plugin to shows code completions. It is important that the C++ build environment was setup prior to the eclipse project creation, else the build and run commands may not work properly.

Using LEP in an existing eclipse project

At the moment, LEP brings just one project wizard for C++, but it‘s no problem to use it in other project types like java projects. Just create a new lep file in the top folder of the project and output the codeblocks to the source folder, e.g. like 

    <<src/net/sf/lep/editors/LEPConfiguration.java>>=

To keep the file path a little shorter, see the "path"-setting in the File based settings. Because the project is still a normal java project, you can use it as per usual. At the moment there is no code completion inside of the lep editor. But errors and warnings show up in the according lep line and they offer java-quickfixes if "Ctrl+1" is used (cursor needs to be in the line with an error/warning).

The usage of quickfixes inside of the lep editor is a bit tricky. After the fix is called it is executed in the according java file. Just save the changed java file and the content of the lep file updates itself. The update can be checked in the eclipse console.

Using LEP to create a webpage

This sample demonstrates the usability of codeblocks for writing web pages. It puts reoccurring text sections like page headers and footers in codeblocks. Every page reuses this blocks and it is easy to maintain a consistent layout. For example this web page uses for each side the following header and footer:

    <<website head>>=
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    
    <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
    
      <head>
        <title>LEP - Literate Programming for Eclipse</title>
        <link type="text/css" rel="stylesheet" href="style.css" >
      </head>
    
      <body>
        <ul class="inlineList piped">
          <<menu entries>>
        </ul>
        
        <hr/>
    @
    <<website foot>>=
        <p class="flowstop"><center>
            <a href="http://sourceforge.net/projects/lep">
            <img src="http://sflogo.sourceforge.net/sflogo.php?
                    group_id=512594&type=2" 
                alt="SourceForge.net" />
        </a></center></p>
        
      </body>
    </html>
    @

The code for a single page is therewith reduced to its content. Note the inclusion of the header and footer at the beginning and end of the block.

    <<website/index.htm>>=
     <<website head>>
        
        <h1>LEP<br/>Literate Programming for Eclipse</h2>
        
        <center><img src="img/EditorOverview.png"/></center>
        
        <p class="centerblock centertext">
        Literate Eclipse Programming assists developers in 
        writing structured, well documented source code. LEP 
        integrates automated extraction of source code and 
        documentation into a familiar eclipse environment. 
        Compiling and debugging are fully supported.<br/><br/>
     <<website foot>>
    @

With codeblocks it is easy to get a site menu on each page without writting duplicated code or using frames or scripts. Just add each page to a codeblock, which is included once in the header codeblock.

    <<menu entries>>=
          <li><a href="index.htm">Home</a></li>
    @

Plugin Preferences

Windows/Linux: Menu Bar->Window->Preferences->LiterateEclipseProgramming
Mac: Menu Bar->Eclipse->Preferences->LiterateEclipseProgramming

LiterateEclipseProgramming->Templates:
The build in text completions can be edited and new ones can be created. The list on the left shows the names of the templates, the text area on the right shows the editable content of the selected template. Enter a new name into the textfield below and press "Add new Template" to create a new empty template.

To use them in the editor, go to a new line or add a blank and then press "Ctrl+Space". A menu with all completions will open.

File based settings

Additionally to the global plugin preferences, there are local settings which influence the extraction of files and the creation of pdfs. These settings are written into the lep file inside of a special codeblock named "LEP Settings". To create it, place the cursor at the beginning of a new line and use the key combination "Ctrl+Space" to open the completion menu; select "LEP Settings". The following settings are available, you can delete those you don‘t need to use it‘s default values:

Here is an example for a LEP Settings codeblock:

    <<LEP Settings>>=
    language = de
    path = code
    buildCommand = /path/to/my/script
    useFullPath = true
    coderef = <<#name# #index#>> on page \pageref{#label#}
    @

Settings for the C++-Compiler

If you are working in a CDT C/C++ Project, you can set compiler settings right from the lep file inside of special codeblocks. The blocks "Release Settings" and "Debug Settings" are available from the completion menu which you can call at the beginning of a new line with "Ctrl+Space". Here is an example:

    <<Debug Settings>>=
    Defines= 
    Undefines=
    Include paths= /path/to/include/boost, /path/to/include/xerces
    Cpp flags= -c -fmessage-length=0 -O2 -g3 -Wall -m32
    Libraries= xerces_d
    Library paths= /path/to/lib
    Linker flags= -m32 -Wl,-rpath,/path/to/lib
    @

Reference Codeblocks

LaTeX uses \ref- or \pageref-commands to reference other parts of a document. LEP introduces its own \coderef-command to reference codeblocks like the following:

    <<First Codeblock>>=
        ...
    @

Later one in the document, there is the need to remind the reader of this codeblock. This can simply be done by using the coderef-command with the name of the codeblock.

    \coderef{First Codeblock}

By default this will add the following text to the pdf:
<<First Codeblock Nr>> on page X

Of course this is customizable. Just add a new line to the file based settings.

    <<LEP Settings>>=
    ...
    coderef = <<#name# #index#>> on page \pageref{#label#}
    ...
    @

After the equal sign has to follow valid LaTeX code. There are three special keywords, that will be replaced with the values of the codeblock:

To make the entire text a link use the hyperref-command like
\hyperref[#label#]{<<#name# #index#>> on page} \pageref{#label#}

Sometimes there is the need to reference a special line in one codeblock, e.g., like in the following block where \coderef{Second Codeblock} uses \coderef{FirstCodeblock} on its second line.

    <<Second Codeblock>>=
        ...
        <<First Codeblock>>
        ...
    @

Instead of hard coding the line number, it is possible to add a label to this line:

    <<Second Codeblock[escapechar=\%]>>=
        ...
        <<First Codeblock>> %\label{code:block1inblock2}%
        ...
    @

Between the two escape characters is a normal LaTeX-label contained. The escape character itself is defined behind the blockname. It is important that the chosen character doesn't occurre in the normal code of this single block. Now this line can be referenced via \ref{code:block1inblock2}.

It is also possible to define the escape character for the entire document by adding it to the lstset-options at the beginning of the document:

    \lstset{numbers=left,
    numberstyle=\tiny,language=C++,basicstyle=\small,
    tabsize=2,breaklines,showstringspaces=false,frame=tB,
    escapechar={\`}}

{\`} seems to be promising as a global escape character which causes no collisions with normal code. If a local and global definition is set, the local one is chosen for that specific codeblock.

Use LaTeX formatting in blocknames

Since version 0.5.10 it is possible to use codeblock names like
<<Set list to $\{1,\ldots,\Delta\}$>>
If such a block is included in another block, the formatting isn't used by default. Instead the command names show up. To avoid this, an escape sequence has to be given, either a local or global one. On how to define escape characters, see Reference Codeblocks.

Note: First, it is not possible to use << or >> within block names. Second, there is no need to escape an underscore for LaTeX, this is done by LEP.

As a bonus for using escape sequences, LEP places a pageref directly after the name of an included codeblock instead of listing it in "included blocks" below. If a coderef setting is present, this is used as a guideline, e.g., to make the whole line a link, see Reference Codeblocks.

Writing an API documentation

Similar to the extraction of codeblocks, LEP is able to extract portions of normal text. This can be used to generate different views onto the code like an api documentation. Such text sections have to be enclosed and named like this:

    \begin{lepsection api-docu}
        ...
    \end{lepsection api-docu}

The name of this section is "api-docu". It has to be the same at the beginning and end. The following characters can't be used in names: '}', ';' and '->'. Apart from that the name is arbitrary. Like with codeblocks, if the same name is used for other sections, those sections are joined.

After you have marked some text portions as sections, you will notice no difference in the final pdf. The text in those sections will show up like any other text. To create a new view onto your document, you have to add a new line to the file based settings.

    <<LEP Settings>>=
    ...
    theme = api-docu -> apiDocuFile; user-docu -> userDocuFile
    ...
    @

The theme setting takes section-file pairs. The file is separated by a '->' from the section name. Pairs are separated by ';'. The meaning of one pair is to filter the section from the document, collect its content and than to write this content to the file given after the '->'. The tex-ending is added automatically to the file. With this line, all the sections named "api-docu" will be collected and written to the file "apiDocuFile.tex" and all the "user-docu"-sections will be collected and written to "userDocuFile.tex". Note, if just a section name is given, this section will be filtered out but no file is written. E.g., theme = api-docu; user-docu will hide both sections from the final document.

Now you can use the created tex files in other documents or include them in the appendix like:

    \section{Appendix: API Documentation}
    \include{apiDocuFile}
    
    \section{Appendix: User Documentation}
    \input{userDocuFile}

The difference between the two variants is, that include adds the content of the file on a new page and input doesn't create a new page.

Sometimes a section should be used in an external file and in the normal document. For that a section can be marked with a star, to prevent it from getting filtered out. It is sufficient to mark either the beginning or the end with a star.

    \begin{lepsection* api-docu}
        ...
    \end{lepsection* api-docu}

No matter were a lepsection ends up in the final document, codeblocks are build in the order they appear in the lep document. Even codeblocks from hidden sections are used. To disable a particular codeblock, just add a star to the end of the first line, e.g., <<Name of block>>=*. This single block will neither be written to code files nor to the pdf. If this block consists of other parts with the same name, those aren't influenced, neither are references to this block. Disabled blocks are collapsed to a single line automatically

SourceForge.net