Author Topic: Preliminary documentation  (Read 16619 times)

Carsomyr

  • Guest
Re: Preliminary documentation
« Reply #15 on: June 13, 2007, 07:53:28 pm »
As an idea one could also look at LyX (www.lyx.org). It gives you a GUI and rough preview similar to a word processor, but still uses LaTeX to render the final document.

The LaTeX it generates also looks reasonably clean(and human editable) on the documents I've used it for.

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9508
Re: Preliminary documentation
« Reply #16 on: June 13, 2007, 09:01:45 pm »
I truly believe LaTeX is the best choice we can make, it has just so much advantages:
  • C::B supports LaTeX
  • LaTeX integrates smoothly into SVN (patches etc. are possible)
  • diff is possible
  • we can use parts of the docu into the dev's SDK docu
  • we can use parts of the SDK docu inside this docu
  • it can easily be converted into other formats (e.g. a fully linked webpage / PDF file)
  • we can easily split the files up into e.g. one per section to avoid conflicts while editing
  • LaTeX simply rocks and is plain solid (I'm using it regularly, round about one document of different complextity pr month)
  • it is *not* binary or similar to binary as I would call e.g. a OOo document, too

Anyway, what's wrong with writing documentation in OpenOffice?
See above - although it's XML the format (without linefeeds, zipped) makes it impossible to diff easily between documents.

A friend of mine is writing his thesis in Microsoft Word at the present time (85 pages of text so far), and even this works without any hassle, including automatic indexing of chapters and stuff. I think if I told him to use LaTeX instead, he'd believe I was joking :)
He is a liar and he will sooner or later start to hate WYSIWYG. Trust me - I have tried so often and/or was forced to use Word. It isn't bad for letters but for documents it just not worth it. Everybody writing more than one "big document" will surely agree... ;-)

With regards, Morten.
« Last Edit: June 13, 2007, 11:20:54 pm by MortenMacFly »
Compiler logging: Settings->Compiler & Debugger->tab "Other"->Compiler logging="Full command line"
C::B Manual: http://www.codeblocks.org/docs/main_codeblocks_en.html
C::B FAQ: http://wiki.codeblocks.org/index.php?title=FAQ

Offline David Perfors

  • Developer
  • Lives here!
  • *****
  • Posts: 560
Re: Preliminary documentation
« Reply #17 on: June 13, 2007, 11:01:34 pm »
It isn't bad for letters but for documents it just not worth it. Everybody writing more than one "big document" will surely agree... ;-)
I agree :)
Time to learn LaTeX ;)
OS: winXP
Compiler: mingw
IDE: Code::Blocks SVN WX: 2.8.4 Wish list: faster code completion, easier debugging, refactoring

Offline mariocup

  • Developer
  • Lives here!
  • *****
  • Posts: 587
Re: Preliminary documentation
« Reply #18 on: June 13, 2007, 11:33:05 pm »
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:

Code: [Select]
% 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

Code: [Select]
\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

Offline thomas

  • Administrator
  • Lives here!
  • *****
  • Posts: 3979
Re: Preliminary documentation
« Reply #19 on: June 14, 2007, 11:38:06 am »
Quote from: MortenMacFly
He is a liar and he will sooner or later start to hate WYSIWYG.
No, he is an Urologist who has very little knowledge of computers. You set up the document for him and all, and then you tell him: "if you want to have a new chapter, click here". This works with less than two phone calls per week. He is perfectly happy that titles look like titles and paragraphs look like paragraphs. I see nothing wrong with that :)

Bibliography might be a point, I admit... But we settled that he copy/pasted the citations from the medline webpage, and later inserted the citations by hand, and this works surprisingly well (having around 90 entries). To be honest, I'm not sure that it could be much faster than typing [Foobar1998] anyway.

Explaining to him thinks like "if you want , then you have to type "u, and if you want , then you have to type \3 or \ss, but not in the middle of a word, there it has to be \ss{} instead" would be a daunting task. He is just happy that pressing and actually produces and in the text.

I'm personally not satisfied with a "X is better than Y because of (irrelevant reason) and (irrelevant reason) and (FUD) and (not applicable feature)" answer, but that doesn't matter.

All that counts in the end is that the ones who maintain the documentation are comfortable with the tool they use, and that the tool accomplishes the task. If that's LaTeX, then that shall be it :)

Just don't ask me to edit on a 10'' amber screen with vi, please  :D

(No thank you, I'm not interested in the many advantages of vi over other editors.)
"We should forget about small efficiencies, say about 97% of the time: Premature quotation is the root of public humiliation."

Offline Pecan

  • Plugin developer
  • Lives here!
  • ****
  • Posts: 2180
Re: Preliminary documentation
« Reply #20 on: June 14, 2007, 01:12:41 pm »
How is svn going to allow all of us to update this document?

When someone else makes a change to (say) keybinder, svn nolonger lets me update. I have to revert my changes, update from svn, remake the changes, then update again.

Is that how it's supposed to be? If many people are hitting the same document frequently, how will this ever work?

Offline byo

  • Plugin developer
  • Lives here!
  • ****
  • Posts: 837
Re: Preliminary documentation
« Reply #21 on: June 14, 2007, 01:31:55 pm »
When someone else makes a change to (say) keybinder, svn nolonger lets me update. I have to revert my changes, update from svn, remake the changes, then update again.

Svn should always let you update. It will bock commit if files were changed by someone else. And usually when update is performed, svn tries to merge your local changes with the ones made on repository. This works very well in most cases. The only problem is when changes are made to the same part of code. In such situation, conflicts must be resloved manually.

So as long as files are in text form, there shouldn't be problems with commiting. Document may be also splitted into smaller files to prevent most of conflicts.

Regards
  BYO

Offline Pecan

  • Plugin developer
  • Lives here!
  • ****
  • Posts: 2180
Re: Preliminary documentation
« Reply #22 on: June 14, 2007, 02:09:38 pm »

Svn should always let you update. It will bock commit if files were changed by someone else.
...

Yes, that's what I mean. How will all of us update the document at the same time?

What is the proper sequence? Make changes; update; then commit?
Or update; make changes; commit? Or what...

What is the proper response when it refuses to let you commit?

« Last Edit: June 14, 2007, 02:26:32 pm by Pecan »

Offline mariocup

  • Developer
  • Lives here!
  • *****
  • Posts: 587
Re: Preliminary documentation
« Reply #23 on: June 14, 2007, 02:32:06 pm »
Hi Pecan,

I think we should split the parts of the documents in reasonable small parts (e.g. every plugin a seperate file). So if you make an update of all small files you will see the svn status. It is the same process like managing source code and that is the daily work. Perhaps we should have some developers that are "responsible/maintainer" of parts of the document, also for different languages.

As the files are splitted in small parts it will be easy to add (and to diff) documentation for a new plugin and we will only have to add an input command of this file.

Regards,

Mario

Offline TDragon

  • Lives here!
  • ****
  • Posts: 936
    • Twilight Dragon Media
Re: Preliminary documentation
« Reply #24 on: June 14, 2007, 03:43:56 pm »
What is the proper sequence? Make changes; update; then commit?
Or update; make changes; commit? Or what...

What is the proper response when it refuses to let you commit?
The proper sequence is "make changes; update; commit" -- or, better yet, "update; make changes; update; commit". This page in the SVN book has proven helpful to me (albeit command-line svn only is exampled). Basically svn forces you to resolve any conflicts between the code you've just created and the code in the repository before it lets you commit to the repository -- obviously a good thing. Like byo said, usually the resolution happens automatically with an update; sometimes, when svn doesn't know how to resolve things automatically, the update ends with a file or two marked as "conflicted", and you have to use TortoiseMerge or whatever to fix it up. So the proper response when it refuses to let you commit is to update, and if some files come up as conflicted, resolve them to files that are merely changed.

Hope that helps,
John E. / TDM
« Last Edit: June 14, 2007, 04:20:49 pm by TDragon »
http://tdm-gcc.tdragon.net/ - TDM-GCC compiler suite for Windows (GCC 5.1.0 2015-06-28, 32/64-bit, no extra DLLs)

Offline thomas

  • Administrator
  • Lives here!
  • *****
  • Posts: 3979
Re: Preliminary documentation
« Reply #25 on: June 14, 2007, 04:50:25 pm »
What is the proper sequence? Make changes; update; then commit?
Or update; make changes; commit? Or what...
You can just commit, and that's it. Subversion is really foolproof and will not let you do it wrong. If you must update, then it will tell you "cannot commit, must update first".
"We should forget about small efficiencies, say about 97% of the time: Premature quotation is the root of public humiliation."

Offline rickg22

  • Lives here!
  • ****
  • Posts: 2283
Re: Preliminary documentation
« Reply #26 on: June 26, 2007, 11:46:23 pm »
Maybe it's a little too late (just found this topic)... can i vote for ODF? ^^;

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9508
Re: Preliminary documentation
« Reply #27 on: June 27, 2007, 01:16:40 pm »
Maybe it's a little too late (just found this topic)... can i vote for ODF? ^^;
One thing I dislike: To save file space ODF documents are usually without any linefeed. This makes comparision of such files nearly impossible - unless you reformat the XML file before. Also: Writing this as "plain text files" without any editor (like OO) is impossible. Using LaTeX you don't have such issues. With LaTeX you develop documents, just the very same as you develop C::B. ;-)
Compiler logging: Settings->Compiler & Debugger->tab "Other"->Compiler logging="Full command line"
C::B Manual: http://www.codeblocks.org/docs/main_codeblocks_en.html
C::B FAQ: http://wiki.codeblocks.org/index.php?title=FAQ

Offline mariocup

  • Developer
  • Lives here!
  • *****
  • Posts: 587
Re: Preliminary documentation
« Reply #28 on: June 27, 2007, 01:27:40 pm »
Hi MortenMacFly,

I will try to send the sources of the documentation this week. All plugins are separated in files, so there will be no conflicts if different devolopers work on these files.

I want to redesign the titlepage with the CB Logo and remove the copyright info.

Latex can generate also html and odt format http://tug.org/applications/tex4ht/.

Bye,

Mario

Offline artoj

  • Almost regular
  • **
  • Posts: 206
  • Location: Supporting my team
    • http://ajonsson.kapsi.fi/
Re: Preliminary documentation
« Reply #29 on: June 27, 2007, 01:34:43 pm »
So what's the purpose of the Wiki after this documentation hits the SVN?

I just fear that soon you have two documentation systems both containing outdated information.