Developer forums (C::B DEVELOPMENT STRICTLY!) > Development
Documentation in various formats
David Perfors:
I found out that doxygen could make manpages..
kagerato:
--- 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...
--- End quote ---
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:
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:
--- 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)
--- End quote ---
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
--- End quote ---
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.
--- End quote ---
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
--- End quote ---
Yeah right :roll: could you give us a good explanation about the whole proccess after you finished the test? 8)
darklordsatan:
--- Quote from: mispunt ---Yeah right :roll: could you give us a good explanation about the whole proccess after you finished the test? 8)
--- End quote ---
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...
Navigation
[0] Message Index
[#] Next page
[*] Previous page
Go to full version