Hi community,
using latex for the first time is not easy, but if you have a template and some macros it is very easy. Here a small snippet of the main document that includes the different parts:
% Version of Document Management
% $Name: $
%%%%%%%% parameter for titlepage %%%%%%%%%%
\def\Subject{Code::Blocks}
\def\Title{Manual}
% style for documentation
\input{format_docu}
\begin{document}
\include{titlepage}
\include{wizards_en}
\include{plugins_en}
\include{params}
\include{generate}
\end{document}
and now the plugins_en tex-source
\chapter{\codeblocks Project Management}
The instructions for \pxref{sec:variables_types} and \pxref{sec:build_codeblocks} are official documentations of the \codeblocks Wiki site and available in english only.
The below illustration shows the design of the \codeblocks user interface.
\screenshot{codeblocks}{IDE \codeblocks}
\begin{description}
\item[Management] This window contains the interface \samp{Projects} which will in the following text be referred to as the project view. This view show all the projects opened in \codeblocks at a certain time. The \samp{Symbols} tab of the Management window shows symbols, variables etc.
\item[Editor] In the above illustration, a source named \file{hello.c} is opened with syntax highlighting in the editor.
\item[Open files list] shows a list of all files opened in the editor, in this example: \file{hello.c}.
\item[CodeSnippets] can be displayed via the menu \samp{View} $\rightarrow$ \samp{CodeSnippets}. Here you can manage text modules and links to files.
\item[Messages]. This window is used for outputting search results, log messages of a compiler etc..
\end{description}
\codeblocks offers a very flexible and comprehensive project management. The following text will address only some of the features of the project management.
\section{Notes for Projects}
In \codeblocks, so-called notes can be stored for a project. These notes should contain short descriptions or hints for the corresponding project. By displaying this information during the opening of a project, other users are provided with a quick survey of the project. The display of notes can be switched on or off in the Notes drop-down field of the Properties of a project.
\section{Project Templates}
\codeblocks is supplied with a variety of project templates which are displayed when creating a new project. However, it is also possible to store custom templates for collecting your own specifications for compiler switches, the optimisation to be used, machine-specific switches etc. in templates. These templates will be stored in the \file{Documents and Settings\osp \var{user}\osp Application Data\osp codeblocks\osp UserTemplates} directory. If the templates are to be open to all users, they have to be copied to a corresponding directory of the \codeblocks installation. These templates will then be displayed at the next startup of \codeblocks under New Project User templates.
\hint{The available templates in the Project Wizard can be edited by selection via right-click.}
\section{Create Projects from Build Targets}
In projects it is necessary to have different variants of the project available. Variants are called Build Targets. They differ with respect to their compiler options, debug information and/or choice of files. A Build Target can also be outsourced to a separate project. To do so, click \samp{Project} $\rightarrow$ \samp{Properties}, select the variant from the drop-down field \samp{Build Targets} and click the \samp{Create project from target} button (see \pxref{fig:build_targets}).
\screenshot{build_targets}{Build Targets}
\section{Virtual Targets}
Projects can be further structured in \codeblocks by so-called Virtual Targets. A frequently used project structure consists of two Build Targets, one \samp{Debug} Target which contains debug information and one \samp{Release} Target without this information. By adding Virtual Targets via \samp{Project} $\rightarrow$ \samp{Properties} $\rightarrow$ \samp{Build Targets} individual Build Targets can be combined. For example, a Virtual Target \samp{All} can create the Targets Debug and Release simultaneously. Virtual Targets are shown in the symbol bar of the compiler under Build Targets.
\section{Pre- and Postbuild steps}\label{sec:pre_postbuild}
\codeblocks makes it possible to perform additional operations before or after compiling a project. These operations are called Prebuilt or Postbuilt Steps. Typical Postbuilt Steps are:
\begin{itemize}
\item Creating an Intel Hexformat from a finished object
\item Manipulating objects by \cmdline{objcopy}
\item Generating dump files by \cmdline{objdump}
\end{itemize}
\genterm{Example}
Creating a Disassembly from an object under Windows. Piping to a file requires calling \cmdline{cmd} with the \opt{/c} option.
\begin{cmd}
cmd /c objdump -D name.elf > name.dis
\end{cmd}
Archiving a project can be another example for a Postbuilt Step. For this purpose, create a Build Target \samp{Archive} and include the following instruction in the Postbuilt Step:
\begin{cmd}
zip -j9 $(PROJECT_NAME)_$(TODAY).zip src h obj $(PROJECT_NAME).cbp
\end{cmd}
With this command, the active project and its sources, header and objects will be packed as a zip file. In doing so, the Built-in variables \codeline{$(PROJECT_NAME)} and \codeline{$(TODAY)}, the project name and the current date will be extracted (see \pxref{sec:builtin_variables}). After the execution of the Target \samp{Archive}, the packed file will be stored in the project directory.
\section{Adding Scripts in Build Targets}
\codeblocks offers the possibility of using menu actions in scripts. The script represents another degree of freedom vor controlling the generation of your project.
\hint{A script can also be included at a Build Target.}
\section{Workspace and Project Dependencies}
In \codeblocks, multiple projects can be open. By saving open projects in a so-called Workspace via \samp{File} $\rightarrow$ \samp{Save workspace} you can collect the projects in a single workspace under \file{\var{name}.workspace}. If you open \file{\var{name}.workspace} during the next startup of von \codeblocks, all projects will show up again. Complex software systems consist of components which are managed in different \codeblocks projects. Furthermore, with the generation of such software systems, there are often dependencies between these projects.
\genterm{Example}
A project A contains central functions which are made available to other projects in the form of a library. Now, if the sources of the central function are changed, then the library has to be recreated. To maintain consistency between a project B which uses the functions and project A which implements the functions, project B has to depend on project A. The necessary information on the dependencies of projects is stored in the relevant workspace, so that each project can be created separately. The usage of dependencies makes it also possible to control the order in which the projects will be generated. The dependencies for projects can be set via the selecting the menu \samp{Project} $\rightarrow$ \samp{Properties} and then clicking the \samp{Project's dependencies} button.
\section{Including Assembler files}
In the Management window of the Project View, Assembler files are shown in the \file{Others} directory. Right-clicking one of the listed Assembler files will open a context menu. Select \samp{Properties} to open a new window. Now select the \samp{Build} tab and activate the two fields \samp{Compile file} and \samp{Link file}. Then select the \samp{Advanced} tab and execute the following steps:
\begin{enumerate}
\item Set \samp{Compiler variable} to CC
\item Select the compiler under \samp{For this compiler}
\item Select \samp{Use custom command to build this file}
\item In the window, enter:
\begin{code}
$compiler $options $includes <asopts> -c $file -o $object
\end{code}
\end{enumerate}
The \codeblocks variables are marked by \codeline{$} (see \pxref{sec:command_macros}). They are set automatically so that you only have to replace the Assembler option \var{asopt} by your own settings.
\section{Editor and Tools}
\subsection{Default Code}
The company's Coding Rules require source files to have a standard design. \codeblocks makes it possible to include a predefined content at the beginning of a file automatically when creating new C/C++ sources and headers. This predefined content is called default code. This setting can be selected under \samp{Stettings} $\rightarrow$ \samp{Editor} Default Code. A new file can be created via the menu \samp{File} $\rightarrow$ \samp{New} $\rightarrow$ \samp{File}.
\genterm{Example}
\begin{code}
/*************************************************************************
* Project:
* Function:
*************************************************************************
* $Author: mario $
* $Name: $
*************************************************************************
*
* Copyright 2007 by company name
*
************************************************************************/
\end{code}
This document contains all necessary macros. I think it is easy to maintain because if somebody add a \screenshot{name}{caption} it will be formated 70% of the textwidth. Another advantage is that "everyone" can add documentation and it will always look the same.
Not all but a lot of Word user do not know much about text formating so the start to use emphasis, bold text or even tabs to format their document. This is not a good idea and hard to maintain. I think developers do not like to write documentation and have no time for formating documents so a plain text format is better.
Maintainance of the document.
I think the document should be splitted in different small part, e.g. every plugin a own tex file, that are include in a master document. So different person can work on the documents at the same time.
Further the documents are plain text and can be diffed easily and merged if necessary.
I will modify our company template at the week end to fit for a community version. The documentation for using the macros is only available in german, but I will translate the relevant parts.
We will have to discuss the structure of the document and perhaps provide different sorting of chapters.
Perhaps some user are not interested in build code blocks from source, so that part of the document should not be the first chapter.
Other users who want to write plugins etc. are most interested in building from sources and have a different focus.
As latex allows also conditional text and inputs this process can be automated to generate different variants of the same document source.
I hope that we will provide soon a documentation for codeblocks, so that all new users will discover all the nice but hidden features in codeblocks.
Bye,
Mario
