Developer forums (C::B DEVELOPMENT STRICTLY!) > Development
Documentation in various formats
RShadow:
I would strongly recommend using a portable documentation language such as latex or docbook. It is very easy for latex to transform a document into a PDF, HTML, or whatever. CHM is really only a windows thing (Yes I know it is possible to view them under linux.. but not common or liked) and I would not recommend it for a project that is aiming to be cross platform.
I would recommend the documentation to come in two falvors.. a downloaded HTML tarball (or zip) and Online HTML, and of course a downloadable PDF file. There are lots of good examples of this being accomplished. Look at the Gentoo Documentation ( http://www.gentoo.org ). They have a very good system for documentation and its portable.
If we want to provide help within C::B (aka. a menu item) it would be very easy to either open the PDF viewer for whatever system the user is on, or imbedd the HTML version into C::B.
As far as manpages being "silly" I don't understand.. I don't know a linux/unix user that doesn't use a manpage on a daily basis... anyways I would recommend that C::B documentation be transformed into a manpage, however using something such as latex it would be really easy for the linux users out there to transform it into a manpage.. or an info page for that matter.
darklordsatan:
The CHM I was talking about, is proposed as an output format, not the source format (it is compiled anyways...).
As we speak, Ive downloaded an XML/XSLT OS editor: Butterfly. Ive also *finally* understood how docbook works, and Ive downloaded both the XSLTs from the DocBok open repository, as well as Xalan-C, for the XSLT processing.
Since Im interested in helping out in the "Code::Blocks documentation project" as well as for my own project at sourceforge, Ill be giving it a shot, and see what I can come out with in the next couple of days, maybe I shall submit a little "test" to you guys and get some feedback.
Using DocBok is great as It provides the flexibility of XML with the power of XSLT transformations (HTML, PDF, CHM with the help of the freely available Microsoft HTML help toolkit, you name it).
And I agree there should be a downloadable HTML tarball with latest, bleeding edge changes, as well as an online HTML with changes as well, and I would aim to provide the code::blocks release with a CHM file. Why not PDF (well, an available PDF can also be made...) and why CHM, well, CHM I think is better for documentation (more tidy, no acrobat reader needed), and besides, ive looked at the samples in wxwidgets, and In fact, IT DOES support CHM for Linux flawlessly, no need for aditional 3rd party shared objects or anything like that, so Its cross-platform, and we have the advantage C::B is made with that toolkit so...
This is meant for the end user docs, now, probably theres another part of C::B that should be taken in account: the sources (maybe starting with the SDK). For this, I think doxygen does a great job. Ive just seen the CHM bundled with irrlicht latest version, and it rocks. Its probably a "customized" version of doxygen output (with the irrlicht logo and everything - I thought doxygen should only output that horrible logo of itself).
While Im aware probably you need to add "special" comment blocks for the sources (just as javadocs, which Ive used in the past - very easy to setup though), IIRC, it can extract information from undocumented sources (like the C::B ones), so it should be fine at least for a start...
Stay tuned...
Cheers
[edit]
Butterfly plainly sucks. In fact Java based apps suck. Slow, clumsy, crappy GUI. Im hitting myself against my monitor for those 12 Mb, and Im sure my 56k dialup wasnt so happy either.
The journey continues...
RShadow:
--- Quote from: darklordsatan ---The CHM I was talking about, is proposed as an output format, not the source format (it is compiled anyways...).
As we speak, Ive downloaded an XML/XSLT OS editor: Butterfly. Ive also *finally* understood how docbook works, and Ive downloaded both the XSLTs from the DocBok open repository, as well as Xalan-C, for the XSLT processing.
Since Im interested in helping out in the "Code::Blocks documentation project" as well as for my own project at sourceforge, Ill be giving it a shot, and see what I can come out with in the next couple of days, maybe I shall submit a little "test" to you guys and get some feedback.
Using DocBok is great as It provides the flexibility of XML with the power of XSLT transformations (HTML, PDF, CHM with the help of the freely available Microsoft HTML help toolkit, you name it).
And I agree there should be a downloadable HTML tarball with latest, bleeding edge changes, as well as an online HTML with changes as well, and I would aim to provide the code::blocks release with a CHM file. Why not PDF (well, an available PDF can also be made...) and why CHM, well, CHM I think is better for documentation (more tidy, no acrobat reader needed), and besides, ive looked at the samples in wxwidgets, and In fact, IT DOES support CHM for Linux flawlessly, no need for aditional 3rd party shared objects or anything like that, so Its cross-platform, and we have the advantage C::B is made with that toolkit so...
This is meant for the end user docs, now, probably theres another part of C::B that should be taken in account: the sources (maybe starting with the SDK). For this, I think doxygen does a great job. Ive just seen the CHM bundled with irrlicht latest version, and it rocks. Its probably a "customized" version of doxygen output (with the irrlicht logo and everything - I thought doxygen should only output that horrible logo of itself).
While Im aware probably you need to add "special" comment blocks for the sources (just as javadocs, which Ive used in the past - very easy to setup though), IIRC, it can extract information from undocumented sources (like the C::B ones), so it should be fine at least for a start...
Stay tuned...
Cheers
--- End quote ---
I think docbook is a great choice for the documentation, because as you said you have the power of transforms. As far as CHM.. If wxWidgets supports it natively then why not.. as long as we provide premaid transform in several formats available for download.
Documentation wise I see three area
C::B user manual
SDK Docs - I think doxygen is a good start, but manual entries need to be made to make certain stuff clearer.. and to add examples.
Documentation - We needs doc's on how to make doc's for the project :) something like hey this is the format.. this what you can use.. this is what you cant etc..etc.. this way plugin developers and whatnot can submit documentation for there additions. It will also allow multiple dev's to work on the documenation in parallel.
darklordsatan:
Agreed.
And yeah, docs for the docs should be made as well (and as a paradox, the docs for the docs should be made with the docs, so you'd have generated docs on how to make the docs using the docs :smile:)
David Perfors:
I agree with you both, we should try docbook.
--- Quote from: RShadow ---As far as manpages being "silly" I don't understand.. I don't know a linux/unix user that doesn't use a manpage on a daily basis... anyways I would recommend that C::B documentation be transformed into a manpage, however using something such as latex it would be really easy for the linux users out there to transform it into a manpage.. or an info page for that matter.
--- End quote ---
Why manpages are silly? I think manpages are only usefull for commandline programs, and for libraries (so the sdk documentation could be a man page). Also I don't use manpages very much (I am not working on linux on a daily basis :P Do you know if it is possible to make man/info pages with doxygen (SDK) and DocBook>
@darklord..: Please try docbook and commit your tests, we could discuss the final output when we have started documenting :)
It is already possible to make SDK Docs (search the forum) doxygen is used for this. The only thing that should be done (in my opinion) is the layout. Also the doxygen-file should be made "multiplatform" and "multi user" so no hardcoded paths.. (Yiannis shall I change this?) the doxygen file is available in the CVS.
Navigation
[0] Message Index
[#] Next page
[*] Previous page
Go to full version