Re: Something I would like to see (rant warning)

[Gary Lawrence Murphy <garym@canada.com>]

>>>>> "J" == Joshua Drake <poet@linuxports.com> writes:

    J> Learning curve

Getting out of bed has a learning curve.  Linux has a learning
curve.  WP8 has a learning cliff.  Isn't it the Fortune file that
proclaims "No one ever learned _all_ of word perfect"?

Seriously, I agree 100% that we don't want to turn people away, but we
do have pragmatic concerns as expressed by one pot-of-gold posting: To
be effective technical documentation, we have to be technical
documentation, not scattered notes on napkins.

    J> Image handling (in linuxdoc)

DocBook handles images in both HTML and PS-based outputs.  My makefile
converts between what is given and what is needed, eg, if the image
was EPS, it uses that for print and makes a bitmap for HTML and vice
versa.  True, it involves netpbm, which is not point and click, but
it only needs to be done right once.

    J> Ease of editing - Most of us are very comfortable at the
    J> command line. A lot of new - very intelligent Linux users are
    J> not.

Anyone who can code a webpage can code a basic DocBook doc.  It's
1/10th as cryptic as LaTeX and 1/100th as cryptic as NROFF; back in
the 1980's the most precious book in our entire company was the one
lone NROFF manual.

True, there are LDP docs where it won't matter, but these will become
the ghetto of our collection.  Unread, unindexed, unfound,
unmaintained, unused.

If we just pile papers into a corner, that's what we will get.  If we
instead take a good ASCII author and pair them with a volunteer who
can help them do the markup, then we have something we can use.

Should Linus accept a good contribution if it is written in Visual
Basic?  I am certain the kernel developers would welcome a clever
algorithm, even in VB, but they will quickly translate it into the C
they can weave into the core opus, and they will look less friendly
upon frequent updates also delivered in VB.

    J> Processing - SGML can be a pain to process and a pain to find
    J> errors in.

True, as can HTML --- my wife spent 3 hours this evening trying to
discover why her homepage invoked a horizontal scroll bar when none
was visibly needed.  

If a document uses simple structure, SGML is pretty foolproof, and if
they work from a template, it's pretty easy to avoid errors.  As with
NROFF or LaTeX, a well documented template is a lot less frightening
than an empty buffer.

    J> It's ugly

Do tell me, please, what is wrong with Norm Walsh's DocBook site, or
http://www.teledyn.com/help/linux/Consulting ?  They look fine to me.
http://kernelbook.sourceforge.net is another.  It's every bit as
nicely done as the old LaTeX2HTML.

If, on the other hand, we want to splay graphics and fonts wontonly
over a page, these tools are not appropriate.  Documentation tools
like LaTeX and DocBook aim to encapsulate what we know about the
science of typesetting, about readability and clarity of presentation.
This is the completely opposite goal from graphic designers who call
their advertising-industry methods of random acts of fonts and colour
"the art and science of pursuasion"; their aim is to manufacture
consent, not to inform and teach.

Now, if you just don't like the plain ordinary layout of the bundled
stylesheets, flexible formatting _is_ what DocBook is all about.
Content is content, visual (or audio) presentation is someone else's
job.  If you find it ugly, it's not the fault of DocBook, it's the
fault of the stylesheet author.  With DocBook, you can change the
stylesheet a thousand times, but leave the original content untouched.

How do you put a WP document into a palm pilot?  How do you render it
as speech?  With SGML, both are simply alternate stylesheets.

    J> Word Perfect 8 has the ability to open just about any document
    J> format, including Frame Maker.  It has the ability to save to
    J> HTML, Postcript, Text and RTF.

And it confuses layout with content.  

I have tried to use font painters to write, I really have, ever since
the first WP for Windows 2.1 and Framemaker for X on the Sun 360, but
the impact on my writing is so delibitating, I had to refuse writing
contracts who demanded it.  

I just can't get into looking at a poor-quality "page" metaphor. It is
too distracting to be thinking about orphaned paragraphs or picas of
indentation when what is really important is the module API.  I also
need to have my writing integrate with my life online; my email gets
book parts pasted in, books get email pasted in, and Rememberance
Agent keeps track of my mounds and mounds of note email file snippets.

Maybe it is just me, but I don't care if I italicized here but
*bolded* there, and I don't want to search for all the places that are
*bold* _underlined_ italic roman; I want to search for the places
where I used a variable name that I now want to change.

Several publishers know my name because of this ;) More than one
corporation still balks when I hand in my very elegant (and logically
consistent typeset) documentation, and MCP will probably curse me
forever as the guy who wouldn't budge until they conceded to go
DocBook.

Try this experiment: For one week, use WP for all your email.  Do a
word count and see if you wrote more or wrote less, and also do a
followup study to see if your correspondents appreciated the
experiment.  Usenet and email still rule the Internet (66% of all
packets) because content is still more important than presentation.

I don't even like receiving HTML email.  I can't imagine writing it.
It's probably the number one least used feature in MSIE.

    J> Wordperfect 9 has the ability to save to PDF, HTML, Text, and
    J> RTF.

One at a time, after navigating silly GUI boxes for each one,
hammering another nail in your wrist's coffin while you click through
them.  Human hands were never designed to point with potatoes.

    J> They both have the ability to create internal linking and table
    J> of contents. They both can handle just about every image format
    J> widely in use.

But not if you start changing between file formats.  WP can only
maintain the semantic integrity of a document if it stays in WP
format.  That means authors are locked in and must make all revisions
in WP format; since WP format is proprietary, highly secret and not
open, they cannot use Applix, LyX or StarOffice.  DocBook also locks
them in, but at least they can use any tools they wish to manipulate
it, even vi.

    J> I just don't believe that we can continue to grow the LDP
    J> without having a simple way for people to contribute. People
    J> should be able to just type something up in Wordperfect.

I say we should not look gift horses in the mouth; if someone sends us
a killer doc written in Microsoft Word 2.0 for Mac, we should graciously
take it, and throw it into a pile.  But the core of our work, to
create a consistent and useful opus of technical documentation, will
necessarily be based on some sort of SGML, and at the present time,
DocBook DTD is more mature and more widely supported than anything we
might devise.

BTW: WordPerfect2000 for Windows speaks DocBook, or so I have been
told.  Framemaker for Windows also has an XML edition.  I have no
interest in either because they force DocBook into a live GUI
pseudo-page presentation instead of doing the right thing and helping
the author to preserve the semantics of their document, but GUI
addicts tell me both tools do a pretty good job.

Those who really hate text editors and tags in their work can always
use LyX today, and probably WP, MsWord and StarOffice by this time
next year.  I'm actually amazed the Applix is not on that list; their
native format is already an XML, yet when ever I ask them about
DocBook, they change the subject.

    J> ... They can save to multiple formats with a single
    J> button.

Please show me that button.  My WP8 does not have it.  My DocBook
makefile, on the other hand, may not have any buttons, but it does
have one command that generates HTML, ASCII, PDF, and RTF: I just type
"make all" and wait (actually, I go for a smoke) --- I suppose you
could write a Tk applet to put a button around it.

    J> Am I suggesting that we dumb some stuff down? You're damn
    J> right. :)

Seriously, and at the foot of all this rant, understand that I'm not
trying to be difficult, but I do wonder if the words of Bucky Fuller
are apropos: 

        "If you make a system so even a fool can use it, 
         only fools will use it." 

I have this same trouble in recruiting authors for my commmercial
publications, and while I have some very stellar exceptions, veritable
wizards of MsWord, predominantly, anyone who cannot handle Linux-based
document publishing usually cannot handle writing good technical Linux
documentation.  If they know Linux well enough to write decently about
it, they're generally clued in enough to handle a makefile command and
a jade RPM.

Again, gift horses are another matter.  

It is wonderful that someone would want to write something in Quark
Express for us, and we will gladly have it available for download, but
we just don't have the manpower to create a document management system
that is both effective and format independent.  

Check out the latest round of sample programs on the Apache Cocoon
distribution for some ideas of where DocBook might take us.  What we
can handle, especially as the tools come available, is DocBook.  It's
good enough for Sun Microsystem.  It's good enough for the PHP
project, for KDE, for Tidy, for newt, for lesstif, for ext2ed, for
isdn4linux, kbd, vbox and samba, and it's likely good enough for the
LDP as well.

<!-- 
Local Variables:
mode:sgml-evangelism
mode:rant-mode
sgml-doctype:("pro-docbook.sgml" "email" "rant")
sgml-insert-missing-element-comment: nil
sgml-default-dtd-file:"~/mail/ldp/rantmode.ced"
End:
-->

-- 
Gary Lawrence Murphy <garym@linux.ca>: office voice/fax: 01 519 4222723
TCI - Business Innovations through Open Source : http://www.teledyn.com
Canadian Co-ordinators for Bynari International : http://ca.bynari.net/
Free Internet for a Free O/S? - http://www.teledyn.com/products/FreeWWW/



--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org