Subject: [clisp-list] Seeking place for CLISP documentation

From: "Hoehle, Joerg-Cyril" <[email-masked]>
Date: Wed Mar 27 06:37:04 2002

Hi,

Reini Urban wrote:
> what about posting it here at first, to let people check its 
> usefulness.
Well, I started writing using MS-Word, since that's what was available on my wife's PeeCee. That probably was a mistake.

MS-word says the file has 24333 characters, but saves to 66KB.doc or 160KB .html, which I'll not send to a mailing list. Acrobat .pdf is also 148KB.

I'd be very happy to use another format. But please don't talk me into Linux-specific tools. I have no access to a Linux box.

I thought about Texinfo since
 o that's what I know.
 o And I have NTEmacs.
 o And it provides automatic indices, which I wouldn't like to write in (X)HTML by hand.
 o And I'm satisfied with texi2html. (I have access to Solaris boxes).
But I'm wondering whether I should just use LaTeX.
Any other options?

Thanks for your help,
	Jorg Hohle

---

From: Jeremy Doolin <[email-masked]>
Date: Wed Mar 27 07:25:09 2002

> But I'm wondering whether I should just use LaTeX.

This would be my suggestion.  After all, it can be used to produce .pdf
or postscript (and as far as I know, ghostscript 7.0 will produce
searchable pdfs).  

Jeremy Doolin
--
May all your disgraces be private.

---

From: William Harold Newman <[email-masked]>
Date: Wed Mar 27 07:55:03 2002

> Well, I started writing using MS-Word, since that's what was available on my wife's PeeCee. That probably was a mistake.

Yes.
 
I worked on a (commercial) project which used MS Word for technical
documentation. It's not impossible, otherwise it wouldn't be so
common, but it's fruitful source of nuisances.
  * You can't easily see the structure of documents. MS Word does support
    abstract structure in documents, so it's not just "what you see
    is all you get". But if your maintainers aren't careful always
    to use the abstract structure, it's hard to tell, because
    e.g. text in a particular place in a particular font looks very
    much like a section header. So while MS Word tries to support
    the notion of not just printing the document but exporting it
    to other formats (especially HTML) it's hard for it to do it
    nearly as cleanly as a more abstract markup language like DocBook.
    (In practice it works OK if you export the document to every
    format you care about before you proof-read it, but that's a 
    chore even for two formats.)
  * You can put the documents under change control (e.g. CVS) but
    you can't easily get meaningful diffs between versions.
  * You can't easily auto-generate documents. It's easy to make
    a script to generate a valid DocBook document describing 
    an IDL specification or a memory map or a table of tag bits. 
    Making a Microsoft Word file is harder.
  * In a company which requires MS products for everyone, it's not
    an immediate issue, but in a more open situation (like open
    source! but also even the same company over a period of decades)
    ensuring that everyone always has software to read the proprietary
    slightly flaky format is a problem. (At the company I was at, I
    didn't see this for MS Word because MS was dominant, but I did
    see it for documents in the older proprietary formats the company
    had used before MS became dominant, and I expect it'll show up
    again when MS isn't dominant.)

> I'd be very happy to use another format. But please don't talk me into Linux-specific tools. I have no access to a Linux box.

DocBook is common for open source documentation. I've been pretty
happy with it (for SBCL). I don't know about using it on MS Windows,
but I'm under the impression that the tools have been ubiquitous for
some years, so I'm 98% sure it's possible.
 
I can't argue very effectively against MS Word for nontechnical
people, since knowledge of how to use Word is so common, and since
WYSIWYG is so much more popular than markup with compilers (like LaTeX
and DocBook) which emit error messages. But for technical people,
DocBook seems like a clear win. Someone who already understands
compilers (concepts like source code and block structure, and basic
skills for fixing problems which correspond to error messages) should
be able to write DocBook documents after studying examples or
tutorials for about 30 minutes. And the exportability, portability,
change control, and script-friendliness advantages are significant.

> But I'm wondering whether I should just use LaTeX.

I don't know enough about texinfo to have a useful opinion.

I liked LaTeX a lot ten years ago, and I'd still be happy to use it
for a document with enough equations that it would be hard to
represent except as a printed document or bitmap. But for documents
that can usefully be exported to de facto portable HTML, I'd go with
something more abstract, like DocBook. LaTeX supports both abstract
markup like "this is a paragraph" and concrete markup like "give me a
6 em break here and switch to 14 point font". If I understand
correctly, you'd need to manually avoid using the concrete markup if
you want to translate correctly to HTML. Instead of carefully limiting
yourself to a subset of LaTeX, why not use a language which is
designed for this, and which can be automatically translated into TeX
as needed?

-- 
William Harold Newman <[email-masked]>
"Now it's a couple of guys sitting in a living room with laptops. (And
jeans turn out not to be the last word in informality.)"
  -- <http://www.paulgraham.com/road.html>
PGP key fingerprint 85 CE 1C BA 79 8D 51 8C  B9 25 FB EE E0 C3 E5 7C