Code::Blocks Forums

Developer forums (C::B DEVELOPMENT STRICTLY!) => Development => Topic started by: David Perfors on July 15, 2005, 01:37:06 pm

Title: Documentation in various formats
Post by: David Perfors on July 15, 2005, 01:37:06 pm
In reply on this (http://codeblocks.org/index.php?name=PNphpBB2&file=viewtopic&p=3408#3408) 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?)
Title: Documentation in various formats
Post by: darklordsatan on July 15, 2005, 01:43:25 pm
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:
Quote from: mispunt

it is a problem, I can't export wiki pages... (as far as I can see, perhaps an admin is able to do it?)
Title: Documentation in various formats
Post by: David Perfors on July 15, 2005, 01:49:12 pm
Quote from: 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?

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

Quote from: darklordsatan
And what is exactly the problem you're having here:
Quote from: mispunt

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:)
Title: Documentation in various formats
Post by: darklordsatan on July 15, 2005, 02:12:36 pm
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:
Title: Documentation in various formats
Post by: David Perfors on July 15, 2005, 02:31:28 pm
Quote from: darklordsatan
@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" :)
Title: Documentation in various formats
Post by: darklordsatan on July 15, 2005, 02:33:53 pm
And in case there was one, what would be the default behaviour, export to...?
Title: Documentation in various formats
Post by: David Perfors on July 15, 2005, 02:39:34 pm
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.
Title: Documentation in various formats
Post by: darklordsatan on July 15, 2005, 02:48:40 pm
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

Quote from: mispunt

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?
Title: Documentation in various formats
Post by: David Perfors on July 15, 2005, 02:56:15 pm
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:
Title: Documentation in various formats
Post by: darklordsatan on July 15, 2005, 03:10:54 pm
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...)
Title: Documentation in various formats
Post by: kagerato on July 15, 2005, 03:10:59 pm
xchm (http://xchm.sourceforge.net) 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.
Title: Documentation in various formats
Post by: squizzz on July 15, 2005, 03:14:44 pm
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)
Title: Documentation in various formats
Post by: darklordsatan on July 15, 2005, 03:26:30 pm
@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
Title: Documentation in various formats
Post by: David Perfors on July 15, 2005, 03:29:22 pm
Quote from: kagerato
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.)

Quote from: 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)

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:
Title: Documentation in various formats
Post by: darklordsatan on July 15, 2005, 03:45:27 pm
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...
Title: Documentation in various formats
Post by: mandrav on July 15, 2005, 04:00:57 pm
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 (http://www.codeblocks.org/tmp/text.zip). If only we knew what editor he used...

Yiannis.
Title: Documentation in various formats
Post by: David Perfors on July 15, 2005, 04:16:03 pm
I found a tool which generates HTML and PDF from XHTML file, it is "commercial opensource" :? and called htmldoc (http://www.htmldoc.org)

But perhaps it is better to wait for Per :)
Title: Documentation in various formats
Post by: tiwag on July 15, 2005, 04:30:42 pm
Quote from: mandrav
...
Btw, here's the link to this XML file (http://www.codeblocks.org/tmp/text.zip). 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
Title: Documentation in various formats
Post by: darklordsatan on July 15, 2005, 05:37:26 pm
Quote from: mispunt
I found a tool which generates HTML and PDF from XHTML file, it is "commercial opensource" :? and called htmldoc (http://www.htmldoc.org)

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...
Title: Documentation in various formats
Post by: mandrav on July 15, 2005, 05:49:56 pm
Quote from: tiwag
Quote from: mandrav
...
Btw, here's the link to this XML file (http://www.codeblocks.org/tmp/text.zip). 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 (http://www.codeblocks.org/tmp/text2plainhtml.zip) it is.

Yiannis.
Title: Documentation in various formats
Post by: RShadow on July 17, 2005, 02:13:31 pm
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.
Title: Documentation in various formats
Post by: darklordsatan on July 17, 2005, 02:52:02 pm
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...
Title: Documentation in various formats
Post by: RShadow on July 17, 2005, 03:03:00 pm
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


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.
Title: Documentation in various formats
Post by: darklordsatan on July 17, 2005, 03:12:57 pm
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:)
Title: Documentation in various formats
Post by: David Perfors on July 17, 2005, 03:34:03 pm
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.

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.
Title: Documentation in various formats
Post by: darklordsatan on July 17, 2005, 04:40:17 pm
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 (http://www.tldp.org/linuxfocus/English/Archives/lf-2003_11-0309.pdf)
Title: Documentation in various formats
Post by: mandrav on July 17, 2005, 05:29:34 pm
Quote
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.
Title: Documentation in various formats
Post by: David Perfors on July 17, 2005, 07:21:18 pm
Quote from: mandrav
Quote
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?
Title: Documentation in various formats
Post by: mandrav on July 17, 2005, 08:07:33 pm
Quote
or are there many changes wich should be documented?

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

Yiannis.
Title: Documentation in various formats
Post by: RShadow on July 18, 2005, 12:24:15 am
Quote from: mispunt
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 :P 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.

Quote from: darklordsatan

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 :)
Title: Documentation in various formats
Post by: David Perfors on July 18, 2005, 08:51:44 am
I found out that doxygen could make manpages..
Title: Documentation in various formats
Post by: kagerato on July 18, 2005, 05:39:34 pm
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...


Now you're the one being silly :D .

Your argument against CHM is easily translated to apply to man pages as well.  They're not plain text (ever try to view them in notepad? :P ), most Windows users do not even know what they are (far worse than not wanting to use them), and their portability is just as questionable as CHM when a viewer for the files does not exist as part of the base system.

What I dislike about CHM and man pages has little to do with their merits.  Both of them accomplish the function they were designed for.  The two, however, lack familiarity across platforms and offer nothing superior to a web-based approach.

If the documentation authoring program just happens to support additional formats like these, then there's little reason not to generate them.  Maintaining seperate sources for a bunch of esoteric formats, though, would ultimately lead to chaos (including poor synchronization of content and some "versions" of the docs being updated more often than others).

Hope that explains my reasoning more clearly.
Title: Documentation in various formats
Post by: darklordsatan on July 18, 2005, 08:07:04 pm
Ok, lets not get into flame wars here (well, sort of).

The thing is, probably on wednesday or later If Im too busy, Ill give you guys a "taste" of a docbok based end-user docs (the source docs so far seem to support doxygen, so thats outta the question now).
Basically, my current proposal is this:

Title: Documentation in various formats
Post by: David Perfors on July 18, 2005, 10:52:07 pm
Quote from: darklordsatan
We'll have DocBook as the main format. Its the one to be maintained (additions, deletions, modifications, typo correction, and so on)

I agree with this. we probably should use the cvs to store the sources...
Quote
CHMs are good, and I think the "lack of familiarity" is not an issue here. As I said before in this thread, wxwidgets supports CHM "natively" so little or not effort (i.e a simple function call(s)) must be made in order to add support for windows Platform as well for Linux
I think we have to look to the help plugin. perhaps there is already support for CHM in it...

Quote
About PDFs, I dont know, I personally preffer CHMs since I dont need any acrobat readers or ghostviews, and the navigation sucks, as well as selecting/copying text.
I think we have an endless discussion here, on both side there are no really good arguments, it is pobably the "taste" of the user.
The main reason the have PDF format is to make printing the documentation easy. We are writting a book after al ;)

Quote
That said, I think it must be clear now that "esoteric" format support means a simple command line call to the XSLT processor or whatever, given the original, maintainable, official DocBook sources...

So, stay tuned for the next episode
Yeah right  :roll: could you give us a good explanation about the whole proccess after you finished the test?   8)
Title: Documentation in various formats
Post by: darklordsatan on July 18, 2005, 11:46:36 pm
Quote from: mispunt
Yeah right  :roll: could you give us a good explanation about the whole proccess after you finished the test?   8)


Sure thing! thats the idea  :wink: , so that everyone who wants to contribute, can do it in a proper way with all the tools at disposal
That is obviously, if mandrav approves my proposal...
Title: Documentation in various formats
Post by: RShadow on July 19, 2005, 05:39:10 am
Quote from: kagerato

Now you're the one being silly Very Happy .
[snip]


Kagerato I think we are on the same page here, Just misunderstood.  I wouldn't propose that chm's and/or man pages be maintained seperatly.. that would be a horrible idea indeed.

Quote from: darklordsatan

Ok, lets not get into flame wars here (well, sort of).
[snip]

I agree with everything you propose.  Using docbook's SGML / XML format (I guess it first needs to be decided what DTD we would use) will allow us to very easily transform the docbook sources into whatever format floats are boat at the time.

As far as manpages not really making sense for an IDE, I agree.  I think we should use whatever format wx supports nativly (CHM apparently) to do whatever kind of help system the IDE will support.  manpage's (for me anyways) only really make sense for the SDK.  When I'm working on code for C::B and various related stuff (like the scon's build) I don't use C::B. I would imagine most other dev's that are linux users do the same.. and manpages of the SDK would be helpfull.

Quote from: mispunt

I agree with this. we probably should use the cvs to store the sources...

I think using CVS to store the documentation makes the most sense.  Whatever comes out of mandrav doing the nightly snapshots, lets just not forget to do nightly snapshots of the doc's too :)
Title: Documentation in various formats
Post by: kagerato on July 19, 2005, 06:20:18 am
Quote from: mispunt
The main reason the have PDF format is to make printing the documentation easy.


Aye, PDFs are useful for that.  Their primary purpose from initial design, I believe, was to create a WYSIWYG printing format.  Portability of the portable document format was just adobe's scheme to get their technology widely adopted.

Years ago I had a strong distaste for Adobe and their products, but PDF has proven its worth over time.

Quote from: RShadow
Kagerato I think we are on the same page here, Just misunderstood. I wouldn't propose that chm's and/or man pages be maintained seperatly.. that would be a horrible idea indeed.


Agreed.
Title: Documentation in various formats
Post by: David Perfors on July 19, 2005, 09:56:15 am
Quote from: RShadow
and manpages of the SDK would be helpfull.
This is possible, we just have to activate it in the doxygen file.
I think it is usefull to have the whole sdk documentation available for download when releasing Code::Blocks 1.0 (read: official stable release). This gives the developers time to document the whole sdk (because I doesn't see everything in the documentation)
Title: Re: Documentation in various formats
Post by: jmccay on August 11, 2005, 01:15:39 am
So what was decided?  Docbook for the source document  to generate other possible documents?  Also, does anyone know of any good XML editors?  Where is a good play to get started and up and running with both Docbook, and XML.  I've been able to figure out some of XML from looking at files.  Thank you in advance, and good luck with the great Unicode race.

Joe.
Title: Re: Documentation in various formats
Post by: David Perfors on August 26, 2005, 04:57:21 pm
I think docbook is the best choice, but we never get a "taste" of it.

I don't know any good xml editor, I will probably use Notepad or VI.

I think someone has to start producing the necesary files for a good start, but I am not able to help with that, because I am to bussy with work(read: term of probation)  So if there are volunteers to do this, please tell us...
Title: Re: Documentation in various formats
Post by: takeshimiya on August 29, 2005, 10:51:51 pm
I like SciTE for editing XML files (as I like Schintilla).
Title: Re: Documentation in various formats
Post by: tiwag on August 30, 2005, 06:02:40 pm

XML Notepad is also very convenient - for hacking small xml files

http://www.snapfiles.com/get/xmlnotepad.html
Title: Re: Documentation in various formats
Post by: David Perfors on August 30, 2005, 11:15:56 pm
just a thought, but wasn't it possible to modify xml files with C::B? Well, I have to look to it, I can't find a simple way to "compile" the xml files,also I can't find much easy examples... (yes I know, I told you that I didn't have the time to do anything... :P)

--edit--
Ik heb al wat gevonden in de svn van LinuxFromScratch :) a whole workaround... Next week I will try to make something to show...
Title: Re: Documentation in various formats
Post by: Urxae on August 31, 2005, 02:08:01 am
Quote from: mispunt on August 30, 2005, 11:15:56 pm
--edit--
Ik heb al wat gevonden in de svn van LinuxFromScratch :)

Weet je, niet iedereen hier verstaat Nederlands, het is wel zo beleefd om 't bij Engels te houden ;).


For those that don't speak Dutch:
[translation lang="en"]
Quote from: mispunt (rephrased) on August 30, 2005, 11:15:56 pm
--edit--
I've found something in LinuxFromScratch's svn :)

You know, not everyone here understands Dutch, it's rather polite to stick to English ;).
[/translation]
Title: Re: Documentation in various formats
Post by: David Perfors on August 31, 2005, 07:59:01 am
:oops: sorry, it was late, and my mind wasn't clear :oops: please forgive me :P

btw, Yiannis, I think the best way to store the files is in the cvs, should we use a seperate module? (I think so..)
Title: Re: Documentation in various formats
Post by: mandrav on August 31, 2005, 08:37:09 am
Quote from: mispunt on August 31, 2005, 07:59:01 am
:oops: sorry, it was late, and my mind wasn't clear :oops: please forgive me :P

btw, Yiannis, I think the best way to store the files is in the cvs, should we use a seperate module? (I think so..)
I kind of lost you...
Are you talking about documentation files? If so, yes they should be kept in cvs...
Title: Re: Documentation in various formats
Post by: David Perfors on August 31, 2005, 09:17:25 pm
Quote from: mandrav on August 31, 2005, 08:37:09 am
I kind of lost you...
Are you talking about documentation files? If so, yes they should be kept in cvs...
Yes I am talking about the documentation files.. Sorry if I was so unclear...
Title: Re: Documentation in various formats
Post by: David Perfors on September 10, 2005, 12:17:51 pm
Quote from: mispunt on August 30, 2005, 11:15:56 pm
Next week I will try to make something to show...
hmm. it takes a bit longer :P I am going to reinstall my computer this weekend with windows and OpenBSD (yes I like to change distributions ;))
Also I am not going to prommise anything, I see I have to less time to prommise something  :?
Title: Re: Documentation in various formats
Post by: David Perfors on November 02, 2005, 10:20:32 am
Finaly I've got something :lol: it is not much, but it is a start. I started to make a Quick guide, without any colors/style and the only thing that is visible are the "legal" stuff (copyright, disclamer, license (fdl)) I will put this into the cvs very soon, and I am going to find a place to upload this sample. (or could I send it to one of the admins to store it temporary on the server?)
 
It is easier than I thought :) I used the Ubuntu documantation and the LFS documentation, and at the moment I am working on Ubuntu.

The structure I use:
Code
doc/
    common/       <-- all the common stuff like license and stuff.
    libs/               <-- all the settings used by all documantation.
    quickguide/   <-- name of the documantation
    build/             <-- the output directory

To make it possible to store translations in CVS every directory (except libs) have subdirectories with the 2 character code for the country (NL for dutch, fr for France, etc.) The default is C (don't know where that stands for. is also used by Ubuntu  :oops:). For know it is only possible to create HTML files, but as soon as I have found the package FOP in the Ubuntu installer I could add PDF support.

(hmm. no I have to use the commandline to commit things to CVS :?)
Title: Re: Documentation in various formats
Post by: David Perfors on November 03, 2005, 02:41:05 pm
I have created a new module in CVS it is called "docs"
There is one makefile which can build a documentationguide. The documentation guide isn't finished yet, but it will contain some information on how to build and edit the documentation.