On 16 November 2011 12:04, Keith Daniels <keithwdaniels(a)gmail.com> wrote: Why not just use basic markup like markdown for example. Then check it into a git repository so we can track changes (most important part) Then use conversion utilities to export it into different document types. I dunno that's what I'd do:)

I would definitely encourage the usage of an open format flat file (or files), such as fodt or some sort of Latex format, in the GIT repository. This would greatly simplify differences between versions (if needed), and thereby make it easier for those without write access to GIT to jump in, edit the document, and submit a patch with their additions. And I would really like to see this idea take off for R14.0! This is one area where we can really shine compared to other desktops out there. Tim

fodt is the Flat ODT format, which OpenOffice/LibreOffice can read and write natively. The advantage over ODT is that it is not a binary blob, so it doesn't take up massive amounts of space in our SCM, and patches can be made/applied (this is important in a collaborative environment outside of something like Etherpad). Tim

On 16 November 2011 22:00, Darrell Anderson <humanreadable(a)yahoo.com> wrote: Personally, I think PDF is crap. Totally crap. 100% crap. Closed Proprietary locked down garbage. Also not friendly to content management systems. Markdown is really easy, and it is easy to output into many formats. It's similar to wikipedia's markup. I suggest we use markdown. it's easy and not hard to learn, also it's flat file. https://en.wikipedia.org/wiki/Markdown Please read up on it. it's a lot less scary than learning html or dealing with PDF binary blobs. Calvin Morrison

On 16 November 2011 22:46, Kristopher John Gamrat <chaotickjg(a)gmail.com>wrote;wrote: If you read up on markdown like I posted earlier you would realize markdown is almost identical to the Mediawiki style (format is almost the same, but it has the same ideas). Honestly Libreoffice is going to give us a binary blob as well as KOffice. Markdown is just as easy as learning how to use libreoffice. The major advantages with markdown are: 1) Any editor works 2) Formatting can be learned in less than 10 minutes, similar to wikipedia 3) We can use Git to track changes in the repository 4) It is easy to convert into XML, PDF, whatever you like to publish. This makes it very versatile when considering options for distribution. 5) Readability, No nasty tags or hacks like HTML requires. No programming or web development knowledge. Can you provide a similar list for LibreOffice? I'd like to pick the best option before we get to far in Calvin Morrison

On 16 November 2011 23:19, Timothy Pearson <kb9vqf(a)pearsoncomputing.net>wrote;wrote: OK Awesome! (though my one quip is that while fodt is an "open" format, it is only supported by LibreOffice afaik) Calvin Morrison

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

Are you able to get your hands on that tool chain? Darrell

Yes, But if we are suggesting that our users are incapable of editing markup of any kind, I seriously doubt their ability to use patch, diff, and git commands. On Nov 17, 2011 1:41 AM, "Kristopher John Gamrat" <chaotickjg(a)gmail.com> wrote:

Lyx is a front-end wrapper to LaTeX. Basically then we're back to discussing markup. :) Lyx could be an option for some documentation teams, but the internal team still needs to learn LaTex. Doable if those involved have the time for that kind of thing. :) Much of our recent discussion has been how to encourage non team members to contribute where nothing more than everyday word processor skills are expected. For internal purposes the leading focus is using a format that is maintainable in GIT for merging collaborative changes in a team environment. Hence the arguments in favor of markup, which is text based. I think we have agreed to ODT, which fundamentally is XML, which is text based. ODT allows writers to use any software supporting that format and does not limit contributors to a specific tool chain. Darrell

On Thursday 17 November 2011 12:56:56 pm Calvin Morrison wrote: I can't speak toward FODT since I don't use it. I think we should just use plain ODT. If we use FODT, most distros will include OpenOffice/LibreOffice by default. It includes a familiar interface closely resembling most other office apps (except MS Office 2007+, but older version still resemble OOo/LO). OOo and LO both have Windows/Mac version, some Win/Mac users use it. Not all people will want to install it, hence my argument in favor of plain ODT, which is supported by MS Office 2007 and (it now seems) most other office apps. -- Kristopher Gamrat Ark Linux webmaster http://www.arklinux.org/

On Thursday 17 November 2011 01:09:34 pm Timothy Pearson wrote: Possible through a shell script? Would make things easier. -- Kristopher Gamrat Ark Linux webmaster http://www.arklinux.org/

Should be. Most LibreOffice functions can be automated. Tim

On Wed, Nov 16, 2011 at 15:51, Timothy Pearson <kb9vqf(a)pearsoncomputing.net> wrote: May I suggest then https://github.com/github/gollum? -- later daze. :: Robert Xu :: rxu.lincomlinux.org :: protocol.by/rxu