Developer forums (C::B DEVELOPMENT STRICTLY!) > Development
Documentation in various formats
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:
--- 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.
--- End quote ---
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)
--- End quote ---
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...
Navigation
[0] Message Index
[#] Next page
[*] Previous page
Go to full version