Author Topic: Preliminary documentation  (Read 16618 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