Return-Path: owner-linux-activists@joker.cs.hut.fi Received: from joker.cs.hut.fi (root@joker.cs.hut.fi [130.233.40.32]) by keos.Helsinki.FI (8.6.4/H45) with SMTP id MAA00227 for ; Fri, 10 Dec 1993 12:21:57 +0200 Received: from joker.cs.hut.fi by niksula.hut.fi id <65229-1>; Fri, 10 Dec 1993 05:43:47 +0200 From: "Linux Activists" To: "Linux-Activists" Reply-To: "Linux-Activists" X-Note1: Remember to put 'X-Mn-Key: DOC' to your mail body or header Subject: Linux-Activists - DOC Channel digest. 93-11-10-2:26 X-Mn-Key: DOC Sender: owner-linux-activists@joker.cs.hut.fi Message-Id: <93Dec10.054347eet.65229-1@niksula.hut.fi> Date: Fri, 10 Dec 1993 05:41:34 +0200 Status: RO X-Status: Topics: OTF straw poll ---------------------------------------------------------------------- From: okir@monad.swb.de (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 okir@monad.swb.de Darmstadt, FRG --- suum cuique --- ------------------------------ End of DOC Digest ***************** ------- .