Documentation in various formats

[mandrav]

Nice discussion you got going on here

Anyway, I know nothing about documentation and formats, but here's my two cents:
Per, who created our new site (not live yet), has transformed the (inaccurate now ) handbook to XML format. He has also provided a couple of XSL templates to transform the XML to HTML.
I believe that this is the way to go, but Per's answer would be more authoritative. He 'll be away for a while but we can ask him when he comes back
Btw, here's the link to this XML file. If only we knew what editor he used...

Yiannis.

[David Perfors]

I found a tool which generates HTML and PDF from XHTML file, it is "commercial opensource" :? and called htmldoc

But perhaps it is better to wait for Per

[tiwag]

...
Btw, here's the link to this XML file. If only we knew what editor he used...

Yiannis.

do you have the stylesheet "text2plainhtml.xsl" somewhere ?
maybe you then can edit it with any xhtml editor

[darklordsatan]

I found a tool which generates HTML and PDF from XHTML file, it is "commercial opensource" :? and called htmldoc

But perhaps it is better to wait for Per

Since this is an OS project, licensed under the same GPL, I think we can apply for GPL as well (not commercial)

Theres always http://xml.apache.org/xalan-c/

Regarding the stylesheets, theres an excellent tool: XML Spy, probably the big daddy of all XML editors; it allows the creation of XSL stylesheets in a WYSIWYG environment, allowing PDF and HTML creation, however, its commercial... but I used the trial version for the project at collegue I talked about.
Theres a free version however, but I dont know how good it is...
http://www.altova.com/support_freexmlspyhome.asp

Please notice what we need here is the use of some graphical tool, I mean, there are tons of free XML editors (mostly non-xml editors but with an xml plugin or template), that aim for a valid document, but we're looking for some of kind of graphical tool

The quest continues I guess...

[mandrav]

...
Btw, here's the link to this XML file. If only we knew what editor he used...

Yiannis.

do you have the stylesheet "text2plainhtml.xsl" somewhere ?
maybe you then can edit it with any xhtml editor

Here it is.

Yiannis.

[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]

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

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.

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.

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 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.

[darklordsatan]

Havent downloaded/readed it yet (in download queue)
Maybe by means of customizing doxygen output we can generate man pages...

Writing Man-Pages - Linux Focus Magazine

[mandrav]

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?)

Yes, feel free to "play" with it.

Yiannis.

[David Perfors]

It is already possible to make SDK Docs (search the forum) doxygen is used for this. *snip*  Also the doxygen-file should be made "multiplatform" and "multi user" so no hardcoded paths.. (Yiannis shall I change this?)

Yes, feel free to "play" with it.

Commited. also the tinyxml diretory is excluded, afterall this is not our own library or are there many changes wich should be documented?

[mandrav]

or are there many changes wich should be documented?

No, just __declspec() attributes for exporting it from libcodeblocks.a. Nothing fancy

Yiannis.

[RShadow]

I agree with you both, we should try docbook.

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 Do you know if it is possible to make man/info pages with doxygen (SDK) and DocBook>

I'm not sure if we can make man/info pages with doxygen or DocBook, but it wouldn't be too hard manualy.  Man pages are just a simple variation of roff... I can do this task.. I will take the docbook sources and do the manpage thing with them.

Writing Man-Pages - Linux Focus Magazine

lol, I was just reading another linux magazine that had an article about writing man pages.. This is why I only subscribe to one magazine.. they all pretty much have the same articles