Csound Csound-dev Csound-tekno Search About

Re: Manual formats

Date1997-02-13 00:49
FromDarrin Smart
SubjectRe: Manual formats
Just to add my opinion...

.rtf is not very portable, especially if you want to include  
graphics or do non-trivial formatting.

.pdf is not very portable (in fact I've never been able to print a  
pdf document properly)

.ps is reasonably portable, but not editable

.html is portable, but high-quality diagrams are difficult, and  
printing can be a problem (you want the text in lots of little files  
for online use, but one big file for printing. As a side note,  
people printing html files should check out  
http://www.ccsi.canon.com/webrecord/)

.doc (MS-Word) limits portability, and Word's reliability for large  
files or files with images is questionable.

I would recommend that a person take on the role of maintaining the  
manual, and uses the wordprocessor of their choice. From this file,  
.ps, .html and even plain ascii versions should be derived. Most  
wordprocessing software can handle this without to much trouble. I  
tend to prefer FrameMaker but that choice should be left to the  
person doing the manual.

Otherwise, something like troff or even better, lout  
(http://snark.niif.spb.su/~uwe/lout/) is an excellent way to write  
the manual using a markup lanuage.

 - Darrin