Author Topic: Preliminary documentation  (Read 16641 times)

Offline mandrav

  • Project Leader
  • Administrator
  • Lives here!
  • *****
  • Posts: 4291
    • Code::Blocks IDE
Preliminary documentation
« on: June 13, 2007, 12:16:35 pm »
Hi all,

thanks to Mario's (user: mariocup) efforts, there is a manual in the works explaining how to install/build/use Code::Blocks  8).
This manual is a work-in progress and is available in two languages: English and German.
We make available the PDF version for reviewal. The plan is to provide it in more formats (like CHM) later.

So, help us by reading what we have so far and share your views, criticism, suggestions. This will only help us create a better manual for new users ;).

Links:

Thank you Mario :).


EDIT: please ignore any copyright information inside the document. This will be removed by next week.
« Last Edit: June 13, 2007, 12:24:40 pm by mandrav »
Be patient!
This bug will be fixed soon...

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9508
Re: Preliminary documentation
« Reply #1 on: June 13, 2007, 01:37:44 pm »
So, help us by reading what we have so far and share your views, criticism, suggestions.
I had a look through he (not fully) translated German manual. It looks pretty good though! :P
I also realised some sections are already outdated (I guess they are taken from the WiKi?!). It seems it's written using LaTeX, so I'd like to propose the following:
Let's put this directly under version control, split up the paragraphs so that each dev can directly update the docu once a part has been changed. We could also accept patches than through BerliOS (from the users changing the WiKi for example). I think it's great work, but I don't believe a single user can maintain it completely.

Thank you Mario :).
++ ;-)

With regards, Morten.
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 Biplab

  • Developer
  • Lives here!
  • *****
  • Posts: 1874
    • Biplab's Blog
Re: Preliminary documentation
« Reply #2 on: June 13, 2007, 01:40:07 pm »
Let's put this directly under version control, split up the paragraphs so that each dev can directly update the docu once a part has been changed. We could also accept patches than through BerliOS (from the users changing the WiKi for example). I think it's great work, but I don't believe a single user can maintain it completely.

I do have same opinion. Let us put it in repo. :)
Be a part of the solution, not a part of the problem.

Offline David Perfors

  • Developer
  • Lives here!
  • *****
  • Posts: 560
Re: Preliminary documentation
« Reply #3 on: June 13, 2007, 01:55:22 pm »
Yes it would be great to put this under version control. It is a shame I couldn't find any time to work on the documentation I was working on.
Sorry for that.  :oops:
OS: winXP
Compiler: mingw
IDE: Code::Blocks SVN WX: 2.8.4 Wish list: faster code completion, easier debugging, refactoring

Offline Pecan

  • Plugin developer
  • Lives here!
  • ****
  • Posts: 2180
Re: Preliminary documentation
« Reply #4 on: June 13, 2007, 01:55:54 pm »
I too agree on putting it under  version control.

It needs some updating.

Thanks Mario.

Offline Deschamps

  • Multiple posting newcomer
  • *
  • Posts: 120
Re: Preliminary documentation
« Reply #5 on: June 13, 2007, 02:10:32 pm »
Quote from: mandrav
help us by reading what we have so far and share your views, criticism, suggestions

Well, I've just downloaded and had a quick look at this document, so here are my very first impressions:

Having in mind those new users for Code::Blocks, IMHO the documentation should begin with a chapter explaining how to obtain the latest version for C::B (stable or nightly, explaining those concepts), how to install it and how to configure a working enviroment with the usual compilers in the usual platforms. Perhaps, this could be introduced in a preface, as a beginner approach.

Currently, this manual directly begins setting up a TriCore project (??) and explaining the PXROS wizards (??), and afaik these components seems to be integrated in a "custom made" C::B. I don't know if it's intended to remove these chapters or adapt them to the standard C::B version, but in any case, i think that the logical sequence would be to begin having a general quick look for the main components and user interface (currently explaind on chapter 3).

Perhaps, the index could be organized in a manner that all the core plugins were covered inside the main document and all the contrib plugins explained into some appendices (beginning on how to obtain, build and configure them inside C::B), but not merged with the core plugins.

Could be defining the contents (i.e. to specify a reference index) the correct way to plan a well structured documentation?

Quote
We make available the PDF version for reviewal. The plan is to provide it in more formats (like CHM) later.

I know that this is only a preview, but I think that, for future draftings and compositions, it could be interesting to include the documentation into the svn repository accompaining the source code, in plain text format (or XML, or something editable and standarized), organized hierarchically on chapters/sections/paragraphs and languages, so it could be more easilly completed, corrected, updated or translated into other languages (the same way that does the svn-book itself). A generated PDF (preferably HTML, though) could come with the C::B releases.


In any case, it really nice to see that there is an active initiative for providing an "official" documentation acompaining C::B, so I can only celebrate it and congratulate those involved in his development (e.g. mariocup). It's really a hard work.

Regards.
Misquotations are the only quotations that are never misquoted

Offline mariocup

  • Developer
  • Lives here!
  • *****
  • Posts: 587
Re: Preliminary documentation
« Reply #6 on: June 13, 2007, 02:59:48 pm »
Hi Deschamps,

you are right the first chapter contains the documentation of our own wizards, because I forgot to set a comment in tex. In the german version it is excluded.  This documentation is only preliminary, so please excuse my mistake. I will send the version without the wizards to codeblocks community. I will reorganise the documentation in tex having conditional parts of the document, so it can be organised in different ways.
As the wizards are quite tricky we want to include a documentation how we wrote the wizards to give the user a quick reference to implement their own wizards, since the docuemtation of codeblocks is not complete and we made our own experiences.

From the tex-Format I can generate html, xhtml, docbook, odt, pdf so it is for me the easiest way to maintain. I would like to generate wiki code from tex  but it seems that there is not a 100% clean specification for wiki code. If you have one I will try to generate wiki code too.

We will have to see which kind of text format will be the right one for the community. It is no problem to have a xml based documentation, with chapter, section etc. commands and convert it to tex format.
But I spent a lot of time testing tools and documentation formats and I think that pdflatex generates  perfect pdf documents. Since tex separates content and layout and this document uses only user defined macros, it is easy to redefine the macros for a community version, if changes in the layout are required. I have tested also docbook, but it think the pdf output is not suitable. What kind of documentation type does the community prefer?

Thanks for your feedback.

Bye,

Mario


Offline mandrav

  • Project Leader
  • Administrator
  • Lives here!
  • *****
  • Posts: 4291
    • Code::Blocks IDE
Re: Preliminary documentation
« Reply #7 on: June 13, 2007, 03:04:05 pm »
Quote
What kind of documentation type does the community prefer?

I believe there are no objections for latex ;).
Be patient!
This bug will be fixed soon...

Offline David Perfors

  • Developer
  • Lives here!
  • *****
  • Posts: 560
Re: Preliminary documentation
« Reply #8 on: June 13, 2007, 03:21:15 pm »
I started with docbook, but if it is true what you say about the pdf generation lets go for Latex :)
OS: winXP
Compiler: mingw
IDE: Code::Blocks SVN WX: 2.8.4 Wish list: faster code completion, easier debugging, refactoring

Offline Biplab

  • Developer
  • Lives here!
  • *****
  • Posts: 1874
    • Biplab's Blog
Re: Preliminary documentation
« Reply #9 on: June 13, 2007, 04:50:58 pm »
Quote
What kind of documentation type does the community prefer?

I would vote for LaTEX. I love it. :)

Thanks for your hard work in bringing the first version out.
Be a part of the solution, not a part of the problem.

Offline thomas

  • Administrator
  • Lives here!
  • *****
  • Posts: 3979
Re: Preliminary documentation
« Reply #10 on: June 13, 2007, 05:19:36 pm »
Ugh... not used LaTeX since 1993, what a nightmare... but then, it's you who has to maintain it, not me... so in the end, just use what you are comfortable with :)

Anyway, what's wrong with writing documentation in OpenOffice?

Unless we plant to have a thousand mathematical formulas in our documentation, any modern word processor will do just as good, only more comfortably, faster and in WYSIWYG, will it not?
All modern word processors support PDF and HTML export, too.

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 :)
"We should forget about small efficiencies, say about 97% of the time: Premature quotation is the root of public humiliation."

Offline Biplab

  • Developer
  • Lives here!
  • *****
  • Posts: 1874
    • Biplab's Blog
Re: Preliminary documentation
« Reply #11 on: June 13, 2007, 06:20:50 pm »
LaTeX has a number of advantages.

  • Press-Quality output can't be obtained from from OpenOffice or even MS Office. The output will not look good.
  • Virtually every conceivable mathematical symbols can be used in LaTeX. OOo or MSOfc can't take that. (Though for C::B this is irrelevant)
  • LaTeX files can be exported into various other formats.

Word-processors are faster in the sense that they allow us to see the changes on-the-fly, make Cut-Copy-Paste from any other applications.

A thesis can be written in MSWord or OOo Writer. But there are some features (Bibliography management) which is not available in MSOfc or OOo. Most of the Colleges purchase third-party software for their students to help them manage Bibliography in an efficient way.

I have seen people struggling with their thesis (prepared in Word, without a Bibligraphy Management software) at the last moment because their supervisor has asked to remove or add couple of references or equations or figures. With LaTeX you get everything. Just compile it twice after such change and you are ready to submit. :)
Be a part of the solution, not a part of the problem.

Offline byo

  • Plugin developer
  • Lives here!
  • ****
  • Posts: 837
Re: Preliminary documentation
« Reply #12 on: June 13, 2007, 06:45:33 pm »
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 :)

I've written my thesis in Latex. It wasn't my choice, just many people advised me to do so (some professors in my high school even didn't accepted other formats). Even if I hadn't many formulas there I can say that it was very good choice.

I don't know how it is done in OOo but when my sister was writing her own thesis in MSOfc there was always something wrong with formatting, even changing printer could mix everything up, not mentioning replacement of some word at the beginning of chapter. I remember that she spent over a week for final polishing only because no matter what she did, it always looked wrong after printing (I hope your friend won't have such problems because it's really stressful). And she was shocked when I told that I don't have to care about it because formatting is done automatically.

And it has another advantage - many ppl can work on one document through svn or other versionning system and it won't break. Just like in normal code ;)

Regards
   BYO

Offline David Perfors

  • Developer
  • Lives here!
  • *****
  • Posts: 560
Re: Preliminary documentation
« Reply #13 on: June 13, 2007, 07:18:46 pm »
OOo has a bibliography manager. You should use the database for it... I never used it... But LaTeX should be very easy (well I told it was :P)
OS: winXP
Compiler: mingw
IDE: Code::Blocks SVN WX: 2.8.4 Wish list: faster code completion, easier debugging, refactoring

Offline polygon7

  • Multiple posting newcomer
  • *
  • Posts: 104
    • Home site
Re: Preliminary documentation
« Reply #14 on: June 13, 2007, 07:30:35 pm »
Quote
What kind of documentation type does the community prefer?
I would vote for LaTEX. I love it. :)
I would vote for LaTeX, too :D
best regards,
p7
 Free open source UML modeling tool: ArgoUML

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.

Offline Biplab

  • Developer
  • Lives here!
  • *****
  • Posts: 1874
    • Biplab's Blog
Re: Preliminary documentation
« Reply #30 on: June 27, 2007, 01:40:07 pm »
With LaTeX you develop documents, just the very same as you develop C::B. ;-)

This is the beauty of LaTeX. :)

So the question remains. Do I need to learn LaTeX to contribute something to a Document??

The answer is No (largely). It's a tagged language. So the major portion of LaTeX code will be of pure text only. Tags are necessary only in few places. For formatting you need to know couple of Tags (should you want to format them), but that shouldn't be a big headache. :)

So what's the purpose of the Wiki after this documentation hits the SVN?

You can use it as an Online Documentation. :)

Other difference is Wiki will remain User-Editable but the SVN doc will not.
Be a part of the solution, not a part of the problem.

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9508
Re: Preliminary documentation
« Reply #31 on: June 27, 2007, 01:45:11 pm »
I will try to send the sources of the documentation this week.
Nice! :-) Looking forward to it...

I just fear that soon you have two documentation systems both containing outdated information.
I think this is an issue. Hence the documentation needs some sync. I believe the WiKi can act as a good scratchpad for the docu. Once an article looks nice there it can be transferred into the docu. (This is mostly a copy&paste operation, really.) Out of the docu a webpage can be built automatically (maybe even using XSLT for nice style or something) but not a WiKi.
With regards, Morten.
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 #32 on: June 27, 2007, 01:49:30 pm »
Hi Artoj,

if there is an output specification of wiki, perhaps we can generate the wiki format from the docu sources. This would be the best solution.
We could write a XSLT script to convert to the wiki format.

Bye,

Mario


Offline artoj

  • Almost regular
  • **
  • Posts: 206
  • Location: Supporting my team
    • http://ajonsson.kapsi.fi/
Re: Preliminary documentation
« Reply #33 on: June 27, 2007, 09:00:16 pm »
I just hope that there will be someone who coordinates the documentation writing between the Wiki and the SVN. IMO, documentation duplication creates unneeded extra work for this project.

Offline dmoore

  • Developer
  • Lives here!
  • *****
  • Posts: 1576
Re: Preliminary documentation
« Reply #34 on: July 20, 2007, 03:38:35 am »
for those unfamiliar with latex, I've found this site useful (lots of examples, plus a pdf book):  http://en.wikibooks.org/wiki/LaTeX