user/developer document

[ollydbg]

I only see an old discussion here about the document.
Preliminary documentation
And also check out the repo: svn.berlios.de/svnroot/repos/codeblocks/docs
The question is:
Are there any official way(instructions) to build those files? (I mean I would like to build it under Windows, Miktex), I see some tex files, also some xml files.

The only issue is I don't want to do extra(duplicate) work between this Latex docs and wiki pages.
Personally I would like to use Latex tools like LYX to edit the latex files. (LYX is quite powerful)

Also, I would like to think we should synchronize the feature in the trunk and the documents. Like in GDB's repo, when some one add a new feature, they should also add the new document pieces, and new test cases.

[MortenMacFly]

The LaTeX documentation is under:
http://svn.berlios.de/svnroot/repos/codeblocks/docs/userguide

There is a Makefile for Linux, but you can use free tools like TeXMaker (http://www.xm1math.net/texmaker) or TeXnicCenter (http://www.texniccenter.org) to edit. There are two main files:

• main_codeblocks_de.tex
• main_codeblocks_en.tex

If you just open these an let the tool gather the document structure you should be fine. Both tools work with MiKTeX - for TeXnicCenter download the latest ALPHA version (http://sourceforge.net/projects/texniccenter/files/TeXnicCenter Alpha/2Alpha4/TXCSetup_2Alpha4_Win32.exe).

I personally prefer WinEdt (http://winedt.com/) which I am very used too and like it a lot. However, its commercial so you need to buy a license (which I did because its my #1 favourite LaTeX IDE).

Please don't use Lyx as this spoils the raw TeX documents so they become unreadable and hard to maintain. IMHO Lyx is for people that use Word all the time and are forced to use LaTeX. But if you want to do some extra-ordinary or tweaking you are horrible lost with Lyx.

...maybe Mario or I find the time to provide a TeXnicCenter project file.

BTW: Keep in mind that besides MiKTeX/LaTeX you also need GhostScript (maybe GhostView), a PDF viewer (I use "PDF-XChange Viewer Free", see http://www.tracker-software.com/pdf-xchange-products-comparison-chart) and probably the MS HTML compiler under Windows.

If you never used LaTeX there is a need for some learning curve, but in the end, LaTeX is the most beautiful type setting on earth...

[MortenMacFly]

...I've added a WinEdt project file to the documentation (for the English version) and made the project actually compile under Windows with default MiKTeX environment.

I think the docu needs some cleanup concerning the macros and styles used. I would prefer to use a default style w/o dependency on a lot of user-defined styles.

[ollydbg]

Thanks morten. I just update to the latest revision.

I have Miktex installed already. It have a Texworks installed by default. I just open the file "main_codeblocks_en.tex" and select "pdflatex", and hit the build button, and then "main_codeblocks_en.pdf" was successfully build and shown in another Texworks window. Cheers!!!

BTW: I used latex when I'm in school. But I'm not a latex export .

EDIT: In Texworks, we should select "pdfLatex+makeIndex+bibtex", so the hyperlinks will be shown correctly in the pdf. (Otherwise, it will show many "??")

[MortenMacFly]

I have Miktex installed already. It have a Texworks installed by default.

Yes, I completely forgot about that option... sure - this will work. TeXWorks has improved a lot lately. Even easier for people that want to contribute.

[Alpha]

I just took a look at this, and noticed there were some issues with the section I worked on.  The following patch should deal with image sizes, however, I do not know enough about latex to be able to fix the (lack of) line wrapping on the last four longer example commands in the Tools+ section (they run off the page).

Code: [Select]

Index: userguide/tools_plus_en.tex
===================================================================
--- userguide/tools_plus_en.tex (revision 7934)
+++ userguide/tools_plus_en.tex (working copy)
@@ -2,7 +2,7 @@
 
 Creating a new tool is fairly simple, and can be completed in a few simple steps. First open \menu{Tools(+),Configure Tools...} to access the User-defined Tools dialog.
 
-\figures{tools_setup}{User-defined Tools dialog}
+\screenshot{tools_setup}{User-defined Tools dialog}
 
 \genterm{Tool Name}
 
@@ -47,7 +47,7 @@
 
 Will create this structure.
 
-\figures{tools_menu_path}{Tools menu structure}
+\figures[hbt!][width=.6\columnwidth]{tools_menu_path}{Tools menu structure}
 
 The command name will be used if this entry is blank. If the first character is a period, the command will be hidden.
 
@@ -55,7 +55,7 @@
 
 This controls the command's placement in the right-click menu of the Projects and Files tabs of the Management pane. The same rules of structure with the Tools Menu Path apply here.
 
-\figures{tools_context_path}{Context menu structure}
+\screenshot{tools_context_path}{Context menu structure}
 
 Please note that the command will not show up in the context menu unless the Command Line contains one or more of the following: \codeline{\$relfile}, \codeline{\$file}, \codeline{\$reldir}, \codeline{\$dir}, \codeline{\$relpath}, \codeline{\$path}, \codeline{\$fname}, and \codeline{\$fext}.
 
@@ -65,7 +65,7 @@
 \genterm{Tools Output Window}
 Tools that only output results command (and require no input) line generally use this setting. The program will be run invisibly and any output will be redirected to the appropriate tab of the Tools Output Window. The text [DONE] will be added upon the tool's completion.
 
-\figures{tool_output}{Tool Output window}
+\figures[hbt!][width=.5\columnwidth]{tool_output}{Tool Output window}
 
 \hint{If the Tools Output window is open when Code::Blocks is closed, it may trigger Code::Blocks to crash.}
 


[ollydbg]

I'm OK with your patch.
Will commit if no objections for few days.

About this:

Code: [Select]

\begin{itemize}
\item Windows
\begin{itemize}
\item 7z or zip - Tools Menu
\begin{cmd}
"path_to_7z\7z" a -t$if(zip == $inputstr{7z or zip?}){zip -mm=Deflate -mmt=on -mx9 -mfb=128 -mpass=10}{7z -m0=LZMA -mx9 -md=64m -mfb=64 -ms=on} -sccUTF-8 "-w$(PROJECTDIR).." "$(PROJECTDIR)..\$(PROJECT_NAME)" "$(PROJECTDIR)*"
\end{cmd}
\item tar.gz or tar.bz2 - Tools Menu
\begin{cmd}
cmd /c ""path_to_7z\7z" a -ttar -mx0 -sccUTF-8 "-w$(PROJECTDIR).." "$(PROJECTDIR)..\$(PROJECT_NAME)" "$(PROJECTDIR)*" && "path_to_7z\7z" a -t$if(gz == $inputstr{gz or bz2?}){gzip -mx9 -mfb=128 -mpass=10 -sccUTF-8 "-w$(PROJECTDIR).." "$(PROJECTDIR)..\$(PROJECT_NAME).tar.gz}{bzip2 -mmt=on -mx9 -md=900k -mpass=7 -sccUTF-8 "-w$(PROJECTDIR).." "$(PROJECTDIR)..\$(PROJECT_NAME).tar.bz2}" "$(PROJECTDIR)..\$(PROJECT_NAME).tar" && cmd /c del "$(PROJECTDIR)..\$(PROJECT_NAME).tar""
\end{cmd}
The command is too long, I'm not sure how to wrap it. Maybe, we should use some special environment. I'm waiting for some Latex exports' comments.

[MortenMacFly]

The command is too long, I'm not sure how to wrap it. Maybe, we should use some special environment. I'm waiting for some Latex exports' comments.

Sid you try to simply add a hard line break (\linebreak, \newline, \\  ->  one of it but tried in that order) or maybe wrap it in a minipage?

[Alpha]

I avoided using an actual line break, because that would make it more difficult to copy-paste a command that a reader might want to try.

It would be possible to simply escape everything and use normal word wrap, for example:

Code: [Select]

"path\_to\_7z\textbackslash{}7z" a -t\textdollar{}if(zip == \textdollar{}inputstr\{7z or zip?\})\{zip -mm=Deflate -mmt=on -mx9 -mfb=128 -mpass=10\}\{7z -m0=LZMA -mx9 -md=64m -mfb=64 -ms=on\} -sccUTF-8 "-w\textdollar{}(PROJECTDIR).." "\textdollar{}(PROJECTDIR)..\textbackslash{}\textdollar{}(PROJECT\_NAME)" "\textdollar{}(PROJECTDIR)*"
... except that I cannot figure out how to get the font to match (using \cmdline{... my command ...} makes it close, but not the same).

[ollydbg]

I'm OK with your patch.
Will commit if no objections for few days.

I do not have the SVN access to modify the document part. Sorry.

BTW: I think TOC should be added, OK?

Code: [Select]

Index: F:/cb_doc/userguide/main_codeblocks_en.tex
===================================================================
--- F:/cb_doc/userguide/main_codeblocks_en.tex (revision 7935)
+++ F:/cb_doc/userguide/main_codeblocks_en.tex (working copy)
@@ -30,6 +30,7 @@
 
 \begin{document}
 \include{mystyles/cb_titlepage}
+\tableofcontents{}
 \include{basics_en}
 \include{plugins_en}
 \include{more_plugins_en}



[ollydbg]

I avoided using an actual line break, because that would make it more difficult to copy-paste a command that a reader might want to try.

It would be possible to simply escape everything and use normal word wrap, for example:

Code: [Select]

"path\_to\_7z\textbackslash{}7z" a -t\textdollar{}if(zip == \textdollar{}inputstr\{7z or zip?\})\{zip -mm=Deflate -mmt=on -mx9 -mfb=128 -mpass=10\}\{7z -m0=LZMA -mx9 -md=64m -mfb=64 -ms=on\} -sccUTF-8 "-w\textdollar{}(PROJECTDIR).." "\textdollar{}(PROJECTDIR)..\textbackslash{}\textdollar{}(PROJECT\_NAME)" "\textdollar{}(PROJECTDIR)*"
... except that I cannot figure out how to get the font to match (using \cmdline{... my command ...} makes it close, but not the same).

Can you give us another patch, I'm not fully understand your idea, but with patches, I can just test and see what changes in PDF.
PS: It looks like the "\cmd" is a user defined environment I'm not familiar with.
PS2: I see some thing like:

Code: [Select]

\usepackage{listings}
 \lstset{language=, breaklines=true, basicstyle=\small,}

\begin{lstlisting}
void check_neighbours (unsigned char **image_twod, int **objects, int current, int width, int height, int *corrections, int x, int y)
\end{lstlisting}
See: http://en.wikibooks.org/wiki/LaTeX/Packages/Listings
Or maybe fancyvrb package (an advanced verbatim package)

[Alpha]

Can you give us another patch, I'm not fully understand your idea, but with patches, I can just test and see what changes in PDF.

This patch shows several options to fix the problem, but none of them are quite correct.

Code: [Select]

Index: userguide/tools_plus_en.tex
===================================================================
--- userguide/tools_plus_en.tex (revision 7934)
+++ userguide/tools_plus_en.tex (working copy)
@@ -179,13 +179,14 @@
 \begin{itemize}
 \item 7z or zip - Tools Menu
 \begin{cmd}
-"path_to_7z\7z" a -t$if(zip == $inputstr{7z or zip?}){zip -mm=Deflate -mmt=on -mx9 -mfb=128 -mpass=10}{7z -m0=LZMA -mx9 -md=64m -mfb=64 -ms=on} -sccUTF-8 "-w$(PROJECTDIR).." "$(PROJECTDIR)..\$(PROJECT_NAME)" "$(PROJECTDIR)*"
+"path_to_7z\7z" a -t$if(zip == $inputstr{7z or zip?}){zip -mm=Deflate -mmt=on
+-mx9 -mfb=128 -mpass=10}{7z -m0=LZMA -mx9 -md=64m -mfb=64 -ms=on} -sccUTF-8
+"-w$(PROJECTDIR).." "$(PROJECTDIR)..\$(PROJECT_NAME)" "$(PROJECTDIR)*"
 \end{cmd}
 \item tar.gz or tar.bz2 - Tools Menu
-\begin{cmd}
-cmd /c ""path_to_7z\7z" a -ttar -mx0 -sccUTF-8 "-w$(PROJECTDIR).." "$(PROJECTDIR)..\$(PROJECT_NAME)" "$(PROJECTDIR)*" && "path_to_7z\7z" a -t$if(gz == $inputstr{gz or bz2?}){gzip -mx9 -mfb=128 -mpass=10 -sccUTF-8 "-w$(PROJECTDIR).." "$(PROJECTDIR)..\$(PROJECT_NAME).tar.gz}{bzip2 -mmt=on -mx9 -md=900k -mpass=7 -sccUTF-8 "-w$(PROJECTDIR).." "$(PROJECTDIR)..\$(PROJECT_NAME).tar.bz2}" "$(PROJECTDIR)..\$(PROJECT_NAME).tar" && cmd /c del "$(PROJECTDIR)..\$(PROJECT_NAME).tar""
-\end{cmd}
 
+cmd /c ""path\_to\_7z\textbackslash{}7z" a -ttar -mx0 -sccUTF-8 "-w\textdollar{}(PROJECTDIR).." "\textdollar{}(PROJECTDIR)..\textbackslash{}\textdollar{}(PROJECT\_NAME)" "\textdollar{}(PROJECTDIR)*" \&\& "path\_to\_7z\textbackslash{}7z" a -t\textdollar{}if(gz == \textdollar{}inputstr\{gz or bz2?\})\{gzip -mx9 -mfb=128 -mpass=10 -sccUTF-8 "-w\textdollar{}(PROJECTDIR).." "\textdollar{}(PROJECTDIR)..\textbackslash{}\textdollar{}(PROJECT\_NAME).tar.gz\}\{bzip2 -mmt=on -mx9 -md=900k -mpass=7 -sccUTF-8 "-w\textdollar{}(PROJECTDIR).." "\textdollar{}(PROJECTDIR)..\textbackslash{}\textdollar{}(PROJECT\_NAME).tar.bz2\}" "\textdollar{}(PROJECTDIR)..\textbackslash{}\textdollar{}(PROJECT\_NAME).tar" \&\& cmd /c del "\textdollar{}(PROJECTDIR)..\textbackslash{}\textdollar{}(PROJECT\_NAME).tar""
+
 \hint{The Windows command line interpreter has been invoked directly here (\cmdline{cmd /c}), allowing for multiple commands to be chained in a single line. However, this causes the command to fail to execute in the Code::Blocks Console.}
 
 \end{itemize}
@@ -193,9 +194,8 @@
 \item Linux
 \begin{itemize}
 \item 7z or zip - Tools Menu
-\begin{cmd}
-7z a -t$if(zip == $inputstr{7z or zip?}){zip -mm=Deflate -mmt=on -mx9 -mfb=128 -mpass=10}{7z -m0=LZMA -mx9 -md=64m -mfb=64 -ms=on} -sccUTF-8 "-w$(PROJECTDIR).." "$(PROJECTDIR)../$(PROJECT_NAME)" "$(PROJECTDIR)*"
-\end{cmd}
+
+\cmdline{7z a -t\textdollar{}if(zip == \textdollar{}inputstr\{7z or zip?\})\{zip -mm=Deflate -mmt=on -mx9 -mfb=128 -mpass=10\}\{7z -m0=LZMA -mx9 -md=64m -mfb=64 -ms=on\} -sccUTF-8 "-w\textdollar{}(PROJECTDIR).." "\textdollar{}(PROJECTDIR)../\textdollar{}(PROJECT\_NAME)" "\textdollar{}(PROJECTDIR)*"}
 \item tar.gz or tar.bz2 - Tools Menu
 \begin{cmd}
 tar -cf "$(PROJECTDIR)../$(PROJECT_NAME).tar.$if(gz == $inputstr{gz or bz2?}){gz" -I 'gzip}{bz2" -I 'bzip2} -9' "$(PROJECTDIR)*"



See: http://en.wikibooks.org/wiki/LaTeX/Packages/Listings
Or maybe fancyvrb package (an advanced verbatim package)

I will look into those, but I am still quite new to LaTeX, so no promises.

[ollydbg]

I'm OK with your patch.
Will commit if no objections for few days.

I do not have the SVN access to modify the document part. Sorry.

BTW: I think TOC should be added, OK?

Code: [Select]

Index: F:/cb_doc/userguide/main_codeblocks_en.tex
===================================================================
--- F:/cb_doc/userguide/main_codeblocks_en.tex (revision 7935)
+++ F:/cb_doc/userguide/main_codeblocks_en.tex (working copy)
@@ -30,6 +30,7 @@
 
 \begin{document}
 \include{mystyles/cb_titlepage}
+\tableofcontents{}
 \include{basics_en}
 \include{plugins_en}
 \include{more_plugins_en}



FYI: I have committed this patch.

[ollydbg]

I see a feature(forward and backward search) of Texworks, when I build the PDF document, I can click on the PDF(opened in Texworks), and select "Jump to source", then it will take me to the latex source associated with the current PDF view. Also when I click on some tex source, and click the context menu "Jump to PDF", it will take me to PDF, quick nice.

BTW: I'm using Miktex 2.9 portable edition.