17 Nov
2011
17 Nov
'11
10:15 a.m.
On 16 November 2011 22:00, Darrell Anderson <humanreadable(a)yahoo.com> 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?
Darrell
---------------------------------------------------------------------
To unsubscribe, e-mail:
trinity-devel-unsubscribe(a)lists.pearsoncomputing.net
For additional commands, e-mail:
trinity-devel-help(a)lists.pearsoncomputing.net
Read list messsages on the Web archive:
http://trinity-devel.pearsoncomputing.net/
Please remember not to top-post:
http://trinity.pearsoncomputing.net/mailing_lists/#top-posting
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
> 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).