> 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.
Not everybody will have a Latex editor at the ready. I
don't know what
fodt
is. Most people will have an ODT-compatible editor
such as LibreOffice or
AbiWord (I think even MS Office can read/save ODT
files since their 2007
edition).
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).
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?
Darrell
