Re: [trinity-devel] Trinity User's Guide

I'll reply to several posts here. I referenced Word and FrameMaker only to illustrate the concept of "master documents." That is, merging multiple documents into one, basically by linking all documents into one and formatted with a master style sheet. My apologies for not explaining that I did not mean or intend we use them. :) As a tech writer I'm familiar with both but never would suggest such software for our project. Both LibreOffice Writer and KWord support ODT, which fundamentally is XML. Exporting to PDF is straightforward with both. Actually, I just remembered (doh!) that TDE (KDE) natively supports printing to PDF through the KPrinter engine. Word processors do provide binary blobs but is that a Bad Thing? We are discussing user guides, not forms of documentation that tend to change in real-time. Our user guides will be relatively static. We won't need version control. One advantage about word processors is a low learning curve for people who want to help and participate. The traditional down side is HTML output is horrible. One would think with ODT, being based on XML, that HTML outputs would be a snap but that is not the case. Perhaps that has changed in the last year or so. I'll have to experiment a little. There likely is a way to apply XSLT transforms to the underlying XML created in ODT. XSLT is what people in tech writing shops use when they use Docbook. The big challenge is creating an XSLT transform that provides a desired format. Not easy. Since TDE natively supports printing to PDF, perhaps we should focus on appropriate solutions to support HTML. Perhaps somebody can write a cleanup script of sorts so the XML to HTML conversion validates correctly. With that we could use Writer or KWord. Does KWord support something similar to the "master document" concept? People producing many of the popular distros all have pretty nice HTML documentation. What tools are those folks using to produce their HTML user guides? Regarding PDF: PDF is not proprietary (the specifications for producing PDF are open standards) but can be limited in application. PDFs suck on pocket e-readers, but they still work great on desktop computers. One of the cornerstones in writing is audience evaluation. The customer drives the process. PDF is a de facto standard for portability. We are dealing with end-users, mom-and-pops. Not all future Trinity users will be computer whiz kids. :) Mom and pops want to print documents. PDF lends well to that. HTML does not. I browsed several links regarding Markdown. My resistance to markup languages is first, few people enjoy writing in that environment. Some people are exceptions --- perhaps this is a left-brain, right-brain thing. :) I dislike writing and editing in raw markup languages. I don't know whether I'm left-brained or right --- I'm just old and cantankerous. ;) Regardless, most people view writing in raw markup as inconvenient. WYSIWYG wins the day. :) Second, there is no immediate feedback with markup languages. Documents have to be validated and processed into the final output before anybody notices mistakes. That kind of process is fine for certain tasks but not for others. Third, simple markup languages start to break with complicated text flows, such as tables or professional text wrapping around images. Fourth, documents I have seen written in markup languages, such as Docbook, when converted to PDF are unprofessional looking. A common problem is paragraph headings that dangle at the bottom of a page rather than sticking with the subsequent paragraph. Of course, if we don't publish to PDF then I suppose we don't worry about that. :) Lastly, markup languages have to be validated and processed in some way to produce a desired output. That requires a processing engine. The more complicated the markup, the more complicated the processing engine. LaTex probably is one of the best markup languages for finicky people. But few people want to write in a markup environment. Another cornerstone with writing is if the tools are unpalatable to non geeks then the geeks gets stuck doing all the writing. :) Darrell