Author Topic: Documentation in various formats  (Read 28655 times)

Offline David Perfors

  • Developer
  • Lives here!
  • *****
  • Posts: 560
Documentation in various formats
« Reply #30 on: July 18, 2005, 08:51:44 am »
I found out that doxygen could make manpages..
OS: winXP
Compiler: mingw
IDE: Code::Blocks SVN WX: 2.8.4 Wish list: faster code completion, easier debugging, refactoring

Offline kagerato

  • Multiple posting newcomer
  • *
  • Posts: 56
    • kagerato.net
Documentation in various formats
« Reply #31 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.

darklordsatan

  • Guest
Documentation in various formats
« Reply #32 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:

  • 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

Offline David Perfors

  • Developer
  • Lives here!
  • *****
  • Posts: 560
Documentation in various formats
« Reply #33 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)
OS: winXP
Compiler: mingw
IDE: Code::Blocks SVN WX: 2.8.4 Wish list: faster code completion, easier debugging, refactoring

darklordsatan

  • Guest
Documentation in various formats
« Reply #34 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...

RShadow

  • Guest
Documentation in various formats
« Reply #35 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 :)

Offline kagerato

  • Multiple posting newcomer
  • *
  • Posts: 56
    • kagerato.net
Documentation in various formats
« Reply #36 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.

Offline David Perfors

  • Developer
  • Lives here!
  • *****
  • Posts: 560
Documentation in various formats
« Reply #37 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)
OS: winXP
Compiler: mingw
IDE: Code::Blocks SVN WX: 2.8.4 Wish list: faster code completion, easier debugging, refactoring

Offline jmccay

  • Almost regular
  • **
  • Posts: 202
Re: Documentation in various formats
« Reply #38 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.
OS: WinXP, Win98 SE, & sometimes Linux

a little light reading from the wxWidgets 2.6.2 readme: A detailed 2000-page reference manual is supplied in HTML, PDF and Windows Help form: see the docs hierarchy.

Offline David Perfors

  • Developer
  • Lives here!
  • *****
  • Posts: 560
Re: Documentation in various formats
« Reply #39 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...
OS: winXP
Compiler: mingw
IDE: Code::Blocks SVN WX: 2.8.4 Wish list: faster code completion, easier debugging, refactoring

takeshimiya

  • Guest
Re: Documentation in various formats
« Reply #40 on: August 29, 2005, 10:51:51 pm »
I like SciTE for editing XML files (as I like Schintilla).

Offline tiwag

  • Developer
  • Lives here!
  • *****
  • Posts: 1196
  • sailing away ...
    • tiwag.cb
Re: Documentation in various formats
« Reply #41 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

Offline David Perfors

  • Developer
  • Lives here!
  • *****
  • Posts: 560
Re: Documentation in various formats
« Reply #42 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...
« Last Edit: August 30, 2005, 11:36:29 pm by mispunt »
OS: winXP
Compiler: mingw
IDE: Code::Blocks SVN WX: 2.8.4 Wish list: faster code completion, easier debugging, refactoring

Offline Urxae

  • Regular
  • ***
  • Posts: 376
Re: Documentation in various formats
« Reply #43 on: August 31, 2005, 02:08:01 am »
--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]

Offline David Perfors

  • Developer
  • Lives here!
  • *****
  • Posts: 560
Re: Documentation in various formats
« Reply #44 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..)
« Last Edit: August 31, 2005, 08:07:27 am by mispunt »
OS: winXP
Compiler: mingw
IDE: Code::Blocks SVN WX: 2.8.4 Wish list: faster code completion, easier debugging, refactoring