User forums > Using Code::Blocks
Preliminary documentation
Deschamps:
--- Quote from: mandrav ---help us by reading what we have so far and share your views, criticism, suggestions
--- End quote ---
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.
--- End quote ---
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.
mariocup:
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
mandrav:
--- Quote ---What kind of documentation type does the community prefer?
--- End quote ---
I believe there are no objections for latex ;).
David Perfors:
I started with docbook, but if it is true what you say about the pdf generation lets go for Latex :)
Biplab:
--- Quote ---What kind of documentation type does the community prefer?
--- End quote ---
I would vote for LaTEX. I love it. :)
Thanks for your hard work in bringing the first version out.
Navigation
[0] Message Index
[#] Next page
[*] Previous page
Go to full version