> On 16 November 2011 22:46, Kristopher John Gamrat > <chaotickjg@...>wrote: > >> On Wednesday 16 November 2011 10:00:22 pm Darrell Anderson wrote: >> > There are several responses to my original query about a user guide. >> I'll >> > use this most recent reply to respond. >> > >> > Side comment: I want to produce something for R14. Something. >> > >> > There are two aspects to this discussion. The second part can be split >> into >> > two components. >> > >> > One aspect is the formats we want to produce. The other is the tools >> we >> > use. Within this latter area we have the desire to produce >> professional >> > user guides. We also need to maintain TDE Help files, much of which >> are >> > long overdue for reviews and updating. >> > >> > A) Formats: >> > >> > HTML and PDF. These formats are portable and do not require being >> connected >> > to the web. The HTML version may be duplicated at the web site and is >> easy >> > to slip into a distro's desktop. PDF is useful for studying without >> > flip-flopping around computer screens because they are designed for >> > printing. >> > >> > B) Tool chains: >> > >> > 1) User guides? How do other groups support both formats? Docbook is >> > somewhat popular but a custom post processing tool chain is needed to >> > produce quality professional output. This post processing tool chain >> is >> not >> > easy to create or use. Additional challenge: few people like editing >> in a >> > raw markup language, which discourages people from helping. >> > >> > 2) Help files: they are in Docbook. I don't believe we need to perform >> any >> > post processing on these files. I believe the underlying viewing >> engine >> > does that on-the-fly. These files can be edited and merged upstream >> like >> > software patches. Yet we still need to edit in raw markup. Is there a >> > better way? >> > >> > More to consider: >> > >> > Do we want to showcase Trinity and use only tools provided by Trinity >> to >> > maintain the user guides and Help files? What is the perception by >> others >> > if we uses tools not in Trinity? >> > >> > Tools like Latex are useful to a minority of people, but tools like >> that >> > will not be adopted by the typical person who wants to help with >> > documentation. What tools do we use to encourage others to help and >> > participate? Do we need a two step process (writer to editor) with >> respect >> > to other people participating? >> > >> > With the user guides we want to modularize information --- something >> > commonly called master documents. In the proprietary world MS Word and >> > Adobe FrameMaker support this concept. I think LibreOffice Writer does >> (but >> > Writer is not a Trinity app). I don't know whether KWord supports the >> > feature although KWord supports ODT. >> > >> > Traditionally word processors support PDF exporting quite well but >> produce >> > horrible non-validating HTML. Has this changed? >> >> I agree with the point of avoiding markup. There is a markup format that >> most >> people will be familiar with from Wikipedia, but a switch to MediaWiki >> seems >> unlikely, and not everybody will be comfortable with that. >> >> I think most hard-core F\OSS users will want to avoid proprietary >> softwares, >> and not everybody can afford programs like MS Office. Yes, LibreOffice >> does >> have support for doc and docx formats, but I doubt it supports all >> features, >> that is not a garentee, and the only place I'd use the MS format is for >> my >> job anyway. Personally, I believe that since we're a F\OSS community, we >> should use F\OSS software and formats. I'd say it's acceptable to >> distribute >> PDFs of the finished guides, but I certainly think we should avoid them >> until >> then. >> >> We're probably better off using either LibreOffice or KOffice. I don't >> think >> anybody will harp on us for using LibreOffice because of how widely-used >> it >> is, and how widely-used it's predecessor was. It's also open source, and >> it >> uses the same ODT format as KOffice. In fact, most open source editors >> support ODT, and I remember opening an ODT at school using MS Office >> 2007, >> before realizing that I forgot to convert it to their format, so anybody >> who >> does use MS Office should be able to contribute. >> >> Another option is using an HTML IDE. Most open source ones produce plain >> HTML >> code without all the excessive meta tags. Some add a meta tag to >> identify >> the >> IDE, but otherwise just the code needed to properly display the page. >> >> If we put the guides in their own section of git (I think that was >> mentioned >> earlier in this thread) and make that section read-only, that'll make it >> easier to keep track of the changes, collaborate, and revert in case of >> a >> mistake. >> >>> >>> Kristopher Gamrat >>> Ark Linux webmaster >>> http://www.arklinux.org/ >>> >> >> > 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 > LibreOffice can do all of the above, and more, as most of the computer literate world knows how to use a word processor. We want to make it *easy* for people to contribute to the documentation. Any new language learning requirements, no matter how "simple", *will* cause people not to contribute. Tim