| Date: Thu, 30 Nov 2006 11:33:56 +0000
| From: Andrew McCarthy <andrewmc-ilug at celt.dias.ie>
| On Thu, Nov 30, 2006 at 11:02:54AM +0000, Cian Davis wrote:
| <snipped a little>
| > Bear in mind that theses take over 6 months to write up.
|[ ... ] I really think people don't realise how much time
| is wasted with dragging things around, highlighting, changing
| fonts, etc.
oh gawds, YES! this is a point I (and some others)
keeping making to my company's management: trying
to "require" WWWYSIAYG (World's Worse What You See
Is All You Get, alias M$-Worthless) vastly increases
the amount of time to write something, discourages
the doc from ever being written or kept updated,
and results in shite-looking Junk (illustrated with
manager-written docs ;-) ). it's Junk not only
because it looks shite, but — more importantly — too
much time was spent fiddling with the formatting and
not enough on the content: Andrew's point.
an invented† rule-of-thumb is that if I can write
the doc as simple UTF-8 text in time N, then either
LaTeX or troff(1) is N+10%, and WWWYSIAYG is >2×N.
and, of course, with UTF-8/LaTeX/troff, I can (and
do) include Linux code examples (important for most
of the docs I work with) hassle-free, but which is a
major pain with WWWYSIAYG (made worse by the company's
templates being a mixture of Français and English (both
USAian and UK) and not at all suited for this sort of
technical writing). which is Andrew's point: lots
of time spent on the wrong things.
up to a point maths is Ok in UTF-8, but really shines
in LaTeX or eqn (troff), whilst yet again being a pain
in WWWYSIAYG (the equation editor _never_ does what I
want!). tables in UTF-8 and troff (tbl) are simple,
can be annoying in LaTeX, and, yet again, are totally
shite in WWWYSIAYG (cue again template silliness to
make it even worse).‡ Andrew's point, yet again.
tools can (and do) generate UTF-8, LaTeX, or troff;
again, WWWYSIAYG looses. badly. a script I recently
wrote took some diagnostic output from the compiler
I maintain, stuffed it into m4(1), which generated
pic(1), whose output was \include'd into a LaTeX
doc: an automatically generated drawing of a parse
tree (AST). excerpts of the LaTeX output of Doxygen
for that same compiler were also included. as part
of the carefully-written content: Andrew's point.
with an index. I've no idea how to index in WWWYSIAYG.
(I did, once, play with OO.org indexing, but quickly
gave up, albeit I can no longer recall the problems.)
using the TUG TeXLive CD, I've found LaTeX as easy
to install as OO.org or Firefox or Sun's Java (JDK).
that CD installs on both Linux and Windross (and I
_think_ on some Unix's and Mac's also?). I _think_
the ISO is available from CTAN. IIRC, the physical
CDs can be bought for a nominal fee from TUG.
(the CD — there's a new one each year — is one of the
benefits of TUG membership, which is how I get mine.)
† “invented” as in I've no hard data to back up the
claims of N+10% (1.1×N) or >2×N.
‡ I have used a WYSIAYG which does a reasonable job
with both maths and tables (and drawing diagrams):
FrameMaker. and it's possible to generate FM docs,
etc etc. I'll guess it rates around N+70% (1.7×N).
but it's very expensive, and last I looked, is not
available for Linux.
Experienced (20+ yrs) kernel/software Eng: | Brian Foster Montpellier,
• Unix, embedded, &tc; • Linux; • doc; | blf at utvinternet.ie FRANCE
• IDL, automated testing, process, &tc. | Stop E$$o (ExxonMobile)!
Résumé (CV) http://www.blf.utvinternet.ie | http://www.stopesso.com
Maintained by the ILUG website team. The aim of Linux.ie is to
support and help commercial and private users of Linux in Ireland. You can
display ILUG news in your own webpages, read backend
information to find out how. Networking services kindly provided by HEAnet, server kindly donated by
Dell. Linux is a trademark of Linus Torvalds,
used with permission. No penguins were harmed in the production or maintenance
of this highly praised website. Looking for the
Indian Linux Users' Group? Try here. If you've read all this and aren't a lawyer: you should be!