Subject: Linux-Activists - DOC Channel digest. 93-11-10-2:26
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Fri, 10 Dec 1993 05:41:34 +0200

Topics:
	 OTF straw poll

----------------------------------------------------------------------

From: [email-masked] (Olaf Kirch)
Subject: OTF straw poll
Date: Thu, 9 Dec 1993 22:39:21 +0200

Matt Welsh wrote about OTF:

> The goals:
>         * To produce a SIMPLE, LOGICAL markup language for software 
>           documentation. The language must be easy for writers to pick up
>           and use, and not require the writer to do any more work than is 
>           necessary. (E.g., laying out menu items in an Info file.) The 

I believe a typesetting system is always a balancing act between putting
the user in a straitjacket of conventions, and the DIY attitude of
``Here's the pieces, it's all up to you.''  Here are some points
to illustrate what I mean:

 *	Designing a logical language includes prejudicing what the users
 	will want to perform with it. For example, being purely logical
 	would mean you don't have fonts to display things with, but rather
 	content-based text attributes. E.g. with LaTeX, you have \tt,
 	\rm, \it, etc, all of which represent certain font types.
 	In TeXinfo, you have @code, @var, etc, which restrict you to 
 	a certain type of technical documentation.

 *	To be able to produce output for formats as disparate as DVI
 	and (ASCII-) nroff, you have to put limits on what users
 	may do. For example, the usual 80-column format makes wide
 	tables impossible. The same goes for the number of fancy
 	font types you can provide.

 *	You would probably want to have graphics. Some picture can
 	reveal more to readers than twenty lines of written text.
 	On the other hand, you can't have the same picture format
 	for all document output formats (DOFs:). So either you limit
 	users to some worst case graphics you can automatically
 	generate ASCII pictures from, or you go for one ``most
 	suitable'' image format per each DOF (say eepic or eps
 	for TeX, pixmaps for WWW and X-based help browsers, pic
 	for roff, hand-crufted ASCII pictures for pure ASCII output,
 	etc pp)

Possible ``comfort'' options of OTF might be

 *	Redundance. Although it would be nice to, for example, extract
	hypertext information from the sectioning command, it would
	also be useful to perform some of these actions manually,
	like inserting an additional Hypertext node where you don't
	want to start a new section.

> I imagine that 90% of software documentation could be written using the 
> limited number of features that OTF will provide. And, because OTF will allow 
> the writer to cheat if necessary, it should be able to handle the rest. 

Stressing the word *could*. Given that TeXinfo has these features, too,
this leaves me wondering why documentation doesn't get written (and,
even less, read) ;)

I think the very idea of OTF is good, but it has to be *much better*
than any existing tools, else it won't be more than YAFF (Yet Another
Fancy Format).

>         * How should the markup language LOOK? I like using the LaTeX model,
>           because it is easy to parse AND easy for the author to understand. 
>           Of course, OTF will be significantly simpler than LaTeX. 

LaTeX is alright for me. It's much more readable than roff, but you
then have to remember that there are many people who *detest* LaTeX
because they find it too complicated (and exchanging the backslash against
an @-sign as in TeXinfo doesn't help this either, I believe :)

However, there are some caveats. You should not fall for some of
TeX's features such as font changes _within a context_. That is,
allowing font changes like this
	{\bf foo bar}
is evil, because it's very hard to parse. The TeXinfo approach is 
much better, because your parser can easily see which part to highlight:
	@emph{foo bar}

An alternative would be mixture of formats, like this:

\Chapter Tending Aaardvaarks
Bla bla Bla \emph{BLAH BLAH BLAH} bla bla...

where some simple commands extend until the next newline. TeXinfo
uses this, and I've seen this in some X-based help systems, too.
Maybe it's not really esthetical from a programmer's point of view,
but I've talked to people who found this very comfortable for
pieces of text they usually put on a separate line, anyway.

Well, that's it for now.

Olaf
-- 
Olaf Kirch		[email-masked]		    Darmstadt, FRG

		      ---  suum cuique  ---

------------------------------

End of DOC Digest
*****************
-------