Author Topic: CodeBlocks User Manual  (Read 1092 times)

Offline gd_on

  • Lives here!
  • ****
  • Posts: 520
CodeBlocks User Manual
« on: December 19, 2019, 07:58:45 pm »
Some years ago (oups ! 9 years  :-[), I worked on the translation in French of the Codeblocks user Manual, written in English and German by Mario Cupelli.
As a new Codeblocks version is in preparation, I think it's a good time to update it.
The work is in progress and I'm able to produce an English and a French version (of course), but not a German one (I don't speak German!)
As previously, the work is largely based on the Wiki content, but adapted to Latex files (as it was). I have added and updated many things.
I can produce pdf files and with some additional work (but not too much) html and chm versions (as it was also in the past).
It could be nice if I could directly update the files and add the new ones with svn, but I certainly have not the good rights. Nevertheless, I can preprare a zipped files with all that is needed with the same structure which exists in the docs sub-folder in www.codeblocks.org/docs/.
You can dowload a preversion of the manual in English  here or the french one  here. ;D
There is still some work in the last part (building C::B from sources), because if it's amost correct for Windows, it's certainly not exact for Linux and not really adapted to Mac.
It needs also some adjustments for the future 20.xx version but probably not too much. ;)

Gd_on
« Last Edit: December 19, 2019, 08:00:54 pm by gd_on »
Windows 10, svn C::B (last version or almost!), WxWidgets 3.1.3, Compilers 8.1.0, 64 bits (seh, posix : gcc, g++ and gfortran in C:\MinGW64) or 32 bits (sjlj, posix in C:\MinGW32).

Offline oBFusCATed

  • Developer
  • Lives here!
  • *****
  • Posts: 12219
    • Travis build status
Re: CodeBlocks User Manual
« Reply #1 on: December 19, 2019, 08:31:07 pm »
Where are this files stored in svn? If you provide patches I could probably push them.
(most of the time I ignore long posts)
[strangers don't send me private messages, I'll ignore them; post a topic in the forum, but first read the rules!]

Offline gd_on

  • Lives here!
  • ****
  • Posts: 520
Re: CodeBlocks User Manual
« Reply #2 on: December 19, 2019, 11:37:36 pm »
The svn access is : svn://svn.code.sf.net/p/codeblocks/code/docs for the doc in tex format.
The access for the doc in pdf, chm and html is in www.codeblocks.org/docs/ (not the same structure as in svn).

gd_on
Windows 10, svn C::B (last version or almost!), WxWidgets 3.1.3, Compilers 8.1.0, 64 bits (seh, posix : gcc, g++ and gfortran in C:\MinGW64) or 32 bits (sjlj, posix in C:\MinGW32).

Offline oBFusCATed

  • Developer
  • Lives here!
  • *****
  • Posts: 12219
    • Travis build status
Re: CodeBlocks User Manual
« Reply #3 on: December 20, 2019, 09:40:22 am »
I have access to the former. Probably not to the latter. :)
(most of the time I ignore long posts)
[strangers don't send me private messages, I'll ignore them; post a topic in the forum, but first read the rules!]

Offline gd_on

  • Lives here!
  • ****
  • Posts: 520
Re: CodeBlocks User Manual
« Reply #4 on: December 30, 2019, 07:20:52 pm »
As I cannot update the doc files with svn, here is a 7zip file containing the updated documentation in English and French. As told previously, I cannot do the job for german, sorry.
I have not made it as a patch : it's too big.
The content of the directory userguide is supposed to replace/update the content of the folder svn://svn.code.sf.net/p/codeblocks/code/docs/userguide. The content of the subdirectory htmlweb which is supposed to replace/update the content of www.codeblocks.org/docs/. Normally, after replacement ot the files, links in http://www.codeblocks.org/user-manual should still work: filenames are the same. I have also put the source of a small utility that I use to restore the original link to png files inside the html files.
This work still needs update, corrections,..., but as it is, it may be already useful.
It's possible to use them directly in the htmlweb subfolder (for pdf, or chm files) also by clicking on main_codeblocks_fr.html or main_codeblocks_en.html for the html version, but if someone who has the correct rights (an admin I suppose) is able to update on C::B web site, it will be nice.

gd_on

PS : Happy New Year
« Last Edit: December 31, 2019, 12:57:10 pm by gd_on »
Windows 10, svn C::B (last version or almost!), WxWidgets 3.1.3, Compilers 8.1.0, 64 bits (seh, posix : gcc, g++ and gfortran in C:\MinGW64) or 32 bits (sjlj, posix in C:\MinGW32).

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9528
Re: CodeBlocks User Manual
« Reply #5 on: January 02, 2020, 11:08:17 am »
As I cannot update the doc files with svn, here is a 7zip file containing the updated documentation in English and French. As told previously, I cannot do the job for german, sorry.
OK - I've committed them to SVN. Than you. I've also removed the German translation as there will be nobody to harmonise 3 languages. I would also strongly suggest to drop the French translation as well, as the effort to keep the remaining two (en/fr) in sync is certainly high and I believe all coders nowadays should do well in English.

I've also added WinEdt project files for the two manuals and created the PDF's from scratch. That is looking good.

It's possible to use them directly in the htmlweb subfolder (for pdf, or chm files) also by clicking on main_codeblocks_fr.html or main_codeblocks_en.html for the html version, but if someone who has the correct rights (an admin I suppose) is able to update on C::B web site, it will be nice.
I'll think about that. For me, providing a link to a PDF and CHM file on the homepage and packaging these into the installers is just fine. Why have an online documentation? Again: Its more to effort with little benefit.

I would propose we update the docs with the new release (inlcuding the SDK docs and stuff...).
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 oBFusCATed

  • Developer
  • Lives here!
  • *****
  • Posts: 12219
    • Travis build status
Re: CodeBlocks User Manual
« Reply #6 on: January 02, 2020, 11:23:14 am »
Why have an online documentation?
Because people are used to online docs these days. I guess.
(most of the time I ignore long posts)
[strangers don't send me private messages, I'll ignore them; post a topic in the forum, but first read the rules!]

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9528
Re: CodeBlocks User Manual
« Reply #7 on: January 02, 2020, 11:41:38 am »
Because people are used to online docs these days. I guess.
If they are pretty. But what you get out of an automata not targeting modern HTML in the first place is not better than integrated help (like CHM/PDF) inside C::B.

But OK - we can generate HTML if we want. Its a single HTML file and tons of images, so it should be easy to integrate into the homepage. But in that case I would rather generate both versions (en/fr) separately and not having a tool that fixes PNG file names on the second run. I think we don't need that step... (gd_on?)
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 gd_on

  • Lives here!
  • ****
  • Posts: 520
Re: CodeBlocks User Manual
« Reply #8 on: January 02, 2020, 12:32:03 pm »
Code: [Select]
it should be easy to integrate into the homepageIt's already there, in http://www.codeblocks.org/user-manual (tab User Manual on the left side of C::B main page). Sources are in  www.codeblocks.org/docs/. It's why I have provided an all-in-one folder htmlweb : normally a simple copy-replace should do the work (without destroying the previous old work). ::)
Of course, all images are the same for all the html files versions, because it's a lot of work to obtain them localised in 3 languages, and probably with very few benefits.

In the original work, by Mario Cupelli, 3 languages were proposed, German because it's the native language of Mario, English and French (my translation of his work).
Of course, English must be the main source (I should say, the reference). I think that having the manual in other languages is a plus, specially for those who don't speak english enough. Of course, translating the doc is a long work, and certainly difficult to maintain, but it's a ++, I think  :D At least, for French, I can do the work (I already maintain the translation of the code in launchpad codeblocks-gd : template .pot and french translation .po)

In the original work by Mario, I think he had no tools to restore the original png files (was not useful with his tools may be). But, his job was done on Linux with tools I don't have on Windows. I have Miktex 2.9 and HelpNdoc 6, but that's all. May be, it's possible to find equivalent tools on Windows, as the one used by Mario, but I have not found them. So my own tool, to restore the original png file, is probably not necessary, but It's the best solution I have until now (and only used to transform .tex in .html files with htlatex).

gd_on

PS : I published an update of the file after my first release, with the code source of my tool at least. I have not still looked on svn, but did you use the last version (same link as previous) ?
PS2: May be on Windows, WinEdt is a nice solution, but it's a shareware. Is there an alternative free solution ?
« Last Edit: January 02, 2020, 02:45:40 pm by gd_on »
Windows 10, svn C::B (last version or almost!), WxWidgets 3.1.3, Compilers 8.1.0, 64 bits (seh, posix : gcc, g++ and gfortran in C:\MinGW64) or 32 bits (sjlj, posix in C:\MinGW32).

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9528
Re: CodeBlocks User Manual
« Reply #9 on: January 02, 2020, 06:18:50 pm »
It's already there, in http://www.codeblocks.org/user-manual (tab User Manual on the left side of C::B main page). Sources are in  www.codeblocks.org/docs/.
I am aware its there already, just I did not update it yet. The single-source files are no problem, but the homepage with the multiple files is a hassle. That's what I was trying to say... :-)

In the original work, by Mario Cupelli, 3 languages were proposed,
I just wanted to propose different. I think 3 languages is too much.
At least, for French, I can do the work
If that is the case also for the long-run I am happy with en/fr.

PS : I published an update of the file after my first release, with the code source of my tool at least. I have not still looked on svn, but did you use the last version (same link as previous) ?
Yes, I had the most recent one but I did not commit the files I believe we don't need yet. I was able to produce all versions (PDF, CHM, HTML) just fine without the tool.

PS2: May be on Windows, WinEdt is a nice solution, but it's a shareware. Is there an alternative free solution ?
For me its fine to produce the files with WinEdt at release time and that is probably enough anyways ( I usually also produce the SDK docs). Alternative tools are present, like TeXMaker, TeXStudio, TeXnicCenter or... Whether or not they also support HTML/CHM I don't know.
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 gd_on

  • Lives here!
  • ****
  • Posts: 520
Re: CodeBlocks User Manual
« Reply #10 on: January 02, 2020, 06:40:05 pm »
Thanks for all your answers.
I use Miktex. It's nice, but it's not fair to make an html file because the tool htlatex knows only ps files for images apparently. I build the tex files with .png, but need to transform them in .ps. Not difficult with tools like Xnview, but it's a work to do, and it's why I restored the original .png files afterwards (at least to avoid less quality).

For the future, I can continue the work for fr/en.
If there are some remarks, (and for sure, there will have ...), I can make corrections, additions, etc... There will have some modifications when 20.xx version will be published, soon probably.
What is the best (and more secure) solution to do that ? I continue to use the forum ? If it's OK for you, that's OK for me.

gd_on
Windows 10, svn C::B (last version or almost!), WxWidgets 3.1.3, Compilers 8.1.0, 64 bits (seh, posix : gcc, g++ and gfortran in C:\MinGW64) or 32 bits (sjlj, posix in C:\MinGW32).

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9528
Re: CodeBlocks User Manual
« Reply #11 on: January 03, 2020, 08:09:20 pm »
I build the tex files with .png, but need to transform them in .ps. [...] and it's why I restored the original .png files afterwards (at least to avoid less quality).
Maybe I don't get it completely: So you say you run hlatex that uses .ps files, creates .png files out of these with low quality and these are the ones you replace with the original high-quality .png files? Right? If so, there is likely another (better) way to do it.

For the future, I can continue the work for fr/en.
What is the best (and more secure) solution to do that ? I continue to use the forum ?
That is nice to hear, thank you! And yes, you can continue on the forum. If you want, I can setup this topic sticky so it remains on top. If you have important things to merge please also send me a PM as sometimes I don't manage to read all forum posts...
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 gd_on

  • Lives here!
  • ****
  • Posts: 520
Re: CodeBlocks User Manual
« Reply #12 on: January 04, 2020, 01:20:51 pm »
OK,
I should have given more details.
My main tool is Miktex 2.9. I open the file main_codeblocks_en.tex (or main_codeblocks_fr.tex) with miktex-texworks.exe. It is configured for pdfLatex+MakeIndex+BibTex (a default config).
Clicking on the green arrow at the top (composition) produce directly a pdf file. Original images are in png format and the subdirectory figures/png.

To obtain an html version, it need some  more work. As I use the tool htlatex (distributed with miktex), it seems that imput images must be in .eps or .ps format. Apparently, it's possible to use .png files, but I tried without success a few threads indications found on the web (I missed something probably  :( ). To convert all the .png files in .ps file, I use Xnview, which has an option to do all the conversions in one step. So, it's quite easy !
Then I launch my cmd file : 00_ToHtml_en.cmd (or 00_ToHtml_en.cmd), which itself calls 00_ToHtml.cmd (the common version). It creates a subdirectory and call the htlatex tool. The parameters of the call have been found in the files prepared by Mario Cupelli some years ago, and still in svn.
If you stop the process here, you obtain 3 html files (a main one and 2 sub-files called by the main one), and many .png files : The problem, is that they have been converted from the .ps file with a loss of quality (reduces size). All files are in the same sub-directory, but you can see that the original name is lost too. Well, like that, it works well, but It's a shame to have lost the names and the quality. Obviously, Mario Cupelli, with his tools, had not this problems. It's why I have written this small Reset_png tool. There is certainly a way to avoid it, but I have not (still) found how to do.
If you use the html file directly, you see that the table of contents appear twice and the url catalog also. So I delete manually a few lines in the *2.html and *3.html files. Not necessary, but gives a cleaner result.

To obtain a chm version, I use the freeware HelpNDoc V6.6. Here too, some manual work is made.
I import directly the file *3.html produced before, and choose the option to "try to split the document into multiple chapters". This gives quite good results exept that chapters need to contain at least one line of text. It's why I have added some lines from here to here in tex files. But, this has an other consequence, the cover page is not seen as a chapter, and does not appear in the result. To avoid this, I edit manually the *3.html file, keep only the beginning (the cover page) and the 2 last lines, to create a new file cover.html. Then, I can import this new file as a complement to the previous import, move it at the beginning of the table of contents and that's all.
The result is quite OK, but there are still a few problems :
- images and their legends are not centered : does not give a nice look, but is works. It's possible to correct this image by image and legend by legend.
- internal links in the chm file does not work (but they worked in the html files), as for example link to a specific figure or chapter. No problems with externals links, they work. Here too, it's possible to correct this manually by creating new links, but it's quite a lot of work. Is it a bug or a limitation of the free version of HelpNDoc ? I don't know.

As those two problems need some tedious work (not difficult, but long), It has not been done. May be at the end when all will be OK, but not sure...

I hope these detailed explanations will help you to understand my work.

For the future, when I'll have modifications to do, I'll first synchronize my own directory by svn (to be sure to have the last official version) and send you via a PM the results. It's OK for me. Of course, send me also a PM if you want that I add or modify something, at least in the french version.

Happy New Year, :)

gd_on
Windows 10, svn C::B (last version or almost!), WxWidgets 3.1.3, Compilers 8.1.0, 64 bits (seh, posix : gcc, g++ and gfortran in C:\MinGW64) or 32 bits (sjlj, posix in C:\MinGW32).

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9528
Re: CodeBlocks User Manual
« Reply #13 on: January 04, 2020, 04:13:19 pm »
I hope these detailed explanations will help you to understand my work.
OK - that sounds quite like a story. I do all of this directly from WinEdt w/o running tools from the command line. All this stuff, including resolving links by multiple compilations etc. is done by WinEdt. You can adopt/configure the creation process quite detailed. So it might simply be a tooling thing. The other tools I mentioned might quite well have similar capabilities. A colleague of mine is also quite happy with TeXlipse.

I'll check for the quality of the images. If there are PNG files already present, its very weird that the input must be a PS file. LaTeX very well supports PNG files just fine. I'll get back to you...

Happy New Year, :)
Same to you! :-)
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