Documentation in various formats

[David Perfors]

I found out that doxygen could make manpages..

[kagerato]

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 .

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

[darklordsatan]

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:

• We'll have DocBook as the main format. Its the one to be maintained (additions, deletions, modifications, typo correction, and so on)
  
• Given the DocBook sources, the we can generate the real docs that the users will see (The "output" formats). For example a HTML to be meant online and probably PDF, CHM and manpages.
  
• None of the mentioned "output" formats above are to be maintained separately!!! They will be generate from the DocBook sources...
  
• Manpages then, are meant for the linux C::B distro. This is just a proposal, given the fact that manpages are more meant for console based apps, and not IDEs. but if users would like them, then we should please them
  
• 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
  
• 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.
  [/list:u]
  
  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

[David Perfors]

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

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

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

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?  

[darklordsatan]

Yeah right  :roll: could you give us a good explanation about the whole proccess after you finished the test?  

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

[RShadow]

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.

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.

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

[kagerato]

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.

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.

[David Perfors]

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)

[jmccay]

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.

[David Perfors]

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

[takeshimiya]

I like SciTE for editing XML files (as I like Schintilla).

[tiwag]

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

http://www.snapfiles.com/get/xmlnotepad.html

[David Perfors]

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

--edit--
Ik heb al wat gevonden in de svn van LinuxFromScratch a whole workaround... Next week I will try to make something to show...

[Urxae]

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

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

[David Perfors]

:oops: sorry, it was late, and my mind wasn't clear :oops: please forgive me

btw, Yiannis, I think the best way to store the files is in the cvs, should we use a seperate module? (I think so..)