Documentation in various formats

[David Perfors]

In reply on this topic I open a new topic.
A summary of the topic:

It would be usefull to have documentation that could be spread in several formats (like CHM, PDF, HTML). This documentation should discribe how Code::Blocks works (the manual). A manual/help file should be included with the installation package od C::B so people have it on there computer. Also there should be a version on the internet so people could always read the newest changes.
The problem is where do we put the documentation. On the wiki? then it should be possible to export it to other formats. So are there other options? (LaTeX?)

[darklordsatan]

What exactly do you mean exporting to other formats? Do you reffer that the main format of the docs should be flexible to allow this?
And what is exactly the problem you're having here:

it is a problem, I can't export wiki pages... (as far as I can see, perhaps an admin is able to do it?)

[David Perfors]

What exactly do you mean exporting to other formats? Do you reffer that the main format of the docs should be flexible to allow this?

The main format of the doc should be flexible indeed, else we can get troubles with exporting to other formats.

And what is exactly the problem you're having here:

it is a problem, I can't export wiki pages... (as far as I can see, perhaps an admin is able to do it?)

You where talking about the format, and I reply to that (I know, I had to quote you :oops:)

[darklordsatan]

Well I think the Doc idea is very neat (I was about to submit a request on this), and should be done ASAP (obviously with the help of non-developers - developers should have enough taks for now!), because once Code::Blocks becomes better and adds more functionality, then the docs will grow up...

Id like to see people opinion on the main format...
Anyway, whatever it might be, I think the starters would be:
1. Create a section-subsection map regarding every topic the docs should cover
2. Create a template for the subsections-sections and the articles itself - This should be done in the docs "main" format to decide yet
3. Agree in which should be the main "source" where documenters should modify/add new articles. From what I know, CVS can handle this, but it would be a pain for people with difficulties accesing the CVS repository, so the first idea is the Wiki
4. Assign someone (or maybe a couple people) to administer the docs, and create the main doc file (directly, or taking the docs from the wiki for example and converting them to the specified format) once its in a stable shape, ready for distribution.

Another thing that I think would be nice is to have images along the tutorials; this should be a plus for newbies who surely wouldnt loose themselves and would provide a more accurate description of whats being explained in a given doc

Notice there should be two kinds of formats:

• The main source format
• The main distribution format
[/list:u]

For the second one, I think CHM is the best alternative, since it simply, rocks, besides, I think wxwidgets can handle CHM in Linux as well, amI right?
For the first one, we're yet to see, I think Latex is complicated and with the lack of a good WYSIWYG editor...

Just some thoughts, probably theyre worthless anyway

@mispunt: What did you mean? I was asking you about the problem you said you had "exporting" the wiki, what was that problem? :smile:

[David Perfors]

@mispunt: What did you mean? I was asking you about the problem you said you had "exporting" the wiki, what was that problem? :smile:

There is no button/link called "export"

[darklordsatan]

And in case there was one, what would be the default behaviour, export to...?

[David Perfors]

I don't know, I was looking if it was possible to export to any (probably HTML) format.

btw. I agree that there should be images in the documentation.
Also I want to say that CVS is usefull to use, but indeed it could be very difficult to use it and not everybody is able to commit. (which is sometimes a possitive thing).

About Latex, you are right, it is difficult, there are other options... Docbook for example, it is used very much by large projects.

I am not sure if wxWidgets is supporting CHM for linux, but I thought they do.

[darklordsatan]

DocBook... the one Ive never wanted to touch... from what I know, its a DTD and you implement the tags and stuff, but have no Idea on how it really works, and what are the tools to make an output... And recently I was searching for WYSIWYG editors for this format (trying to help someone at gamedev), but It seems there are not many (as in "none"); the existing solutions are apparently, crap. So we have again the problem of hand-editing wich can be time consuming and tiring for the big work we have ahead

I am not sure if wxWidgets is supporting CHM for linux, but I thought they do.

Now that it comes in mind, I think the samples show it does indeed. IIRC, thats one of the reasons I was so thrilled with wxwidgets (in the times of wxwindows and 2.4.2). Probably the sample "help" is the one that shows such functionality

About the wiki, what do you mean exporting to html? doesnt it suffices to save it from your browsers "save as" function, or you dont want the extra columns and stuff?

[David Perfors]

With the exporting I mean exporting the articles to html.. and I mean only the text... when you have an article with many chapters all on a sepperate page you have to use a lot the "save as" function. In my opinion it should be possible to export an article with many sub pages to one format so we could use that for distribution.

About the tools, I don't know any usefull WYSIWYG editor which is usefull for us  :cry: I tink it is time to write one  :evil:

[darklordsatan]

My question in the meantime would be then, what are the input formats in order to create a CHM that a tool X would receive?
I'd like to know the names of some "tool X"

IIRC, the utility tex2rtf in wx can generate CHMs from .tex (so goodbye). Also, NSIS uses a modified version of Halibut or something, that can create CHMs as well?
What are the other options?
(Im probably moving towards CHM in a too obvious way, but I bet most people would agree with me its the best format, and besides having a CHM is like having HTMLs, which could serve as the online docs on the way...)

[kagerato]

xchm should view CHM files on linux/gnu.

Personally, I'd author docs in a web format.  This makes it rather simple to post them online.  Even with just HTML and CSS, you can establish strong structure in the documentation using platform-independent format(s).

Using something like CHM or man pages just seems silly to me these days.

[squizzz]

Maybe it would be good idea to write documentation as XML (easy and capable of storing both data and metadata), and then write exporters to different formats... XML->HTML would be trivial, but what about other ones... (like PDF)

[darklordsatan]

@kagerato: CHM stands for Compiled HTML Help, so basically if we had HTML format, we could export to CHM (probably this should be the most accurate option, in order to keep portability as you say; have online docs, and being able to export to other formats...)
Now, CHMs and man pages are not silly! I preffer a good CHM, which is compact,with search capabilities, instead of HTML, for instance...
And theres nothing bad with a good manpage that you can call just like that while working on the shell...

Obvisously in the end we could just take the HTML and embed it into an HTML control (like the one in the welcome tab in the latest CVS), but this seems to "underground" for me...

@squizzz: I dont know, your idea seems kinda cool, and I just remember that a month ago or so (yeah, I had forgotten!!!) I was forced to use Cocoon for a project at collegue, which is sort of to xml, what apache is to php; i.e it can generate PDFs, and HTMLs on the fly (I used these 2 and also WML) with little effort, provided it gets

• An XML defining the data
• An XSL stylesheet defining the visual structure of the document (thus, one for every format - PDF, HTML)
[/list:u]

But it seems rather complicated, and theres still the problem of where on god will the transformation server would be? what other options for working with XML are you aware of?

[David Perfors]

Personally, I'd author docs in a web format.  This makes it rather simple to post them online.  Even with just HTML and CSS, you can establish strong structure in the documentation using platform-independent format(s).

Using something like CHM or man pages just seems silly to me these days.

I agree with the first part, but not with the second. We should focus on a web based solution, with the possibilities to provide it in other formats like CHM and PDF (man pages doesn't fit the purpose I think.)

Maybe it would be good idea to write documentation as XML (easy and capable of storing both data and metadata), and then write exporters to different formats... XML->HTML would be trivial, but what about other ones... (like PDF)

Making your own exporters is much work, especially when DocBook can do this. But I can't find any executable to parse those DocBook files to an other format... :roll:

[darklordsatan]

Well, this is what I found

http://www.xmlmind.com/xmleditor/_distrib/doc/commands/ch05s03s02.html
http://www.dpawson.co.uk/docbook/tools.html#d4e16
http://www.sagehill.net/docbookxsl/

Though Im not very fond of PDF; Im more the CHM guy. Besides, the conversion doesnt seem like a trivial task for the mere mortals...