From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: "Robert J. Chassell" Newsgroups: gmane.emacs.xemacs.design,gmane.emacs.devel Subject: Re: INFO on add-ons Date: Wed, 4 Sep 2002 14:38:56 +0000 (UTC) Sender: xemacs-design-admin@xemacs.org Message-ID: References: <3D728E82.8000808@cox.net> <87ptvxxkoj.fsf@tleepslib.sk.tsukuba.ac.jp> <87fzwtxad9.fsf@tleepslib.sk.tsukuba.ac.jp> <3D73F6D1.7010002@cox.net> <874rd7wuos.fsf@tleepslib.sk.tsukuba.ac.jp> <3D74D797.7000707@cox.net> <87bs7etocv.fsf@tleepslib.sk.tsukuba.ac.jp> Reply-To: bob@rattlesnake.com NNTP-Posting-Host: localhost.gmane.org X-Trace: main.gmane.org 1031150320 22844 127.0.0.1 (4 Sep 2002 14:38:40 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Wed, 4 Sep 2002 14:38:40 +0000 (UTC) Cc: emacs-devel@gnu.org, xemacs-design@xemacs.org Return-path: Original-Received: from gwyn.tux.org ([207.96.1.200]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 17mbIh-0005ve-00 for ; Wed, 04 Sep 2002 16:38:35 +0200 Original-Received: from gwyn.tux.org (localhost.localdomain [127.0.0.1]) by gwyn.tux.org (8.9.3/8.9.1) with ESMTP id KAA03765; Wed, 4 Sep 2002 10:40:06 -0400 Original-Received: (from turnbull@localhost) by gwyn.tux.org (8.9.3/8.9.1) id KAB03105 for xemacs-design-mailman@xemacs.org; Wed, 4 Sep 2002 10:39:09 -0400 Original-Received: (from mail@localhost) by gwyn.tux.org (8.9.3/8.9.1) id KAA03099 for turnbull@tux.org; Wed, 4 Sep 2002 10:39:09 -0400 Original-Received: from localhost (megalith.rattlesnake.com [140.186.114.245]) by gwyn.tux.org (8.9.3/8.9.1) with ESMTP id KAA03053; Wed, 4 Sep 2002 10:39:04 -0400 Original-Received: by rattlesnake.com via sendmail from stdin id (Debian Smail3.2.0.114) Wed, 4 Sep 2002 14:38:56 +0000 (UTC) Original-To: stephen@xemacs.org In-Reply-To: <87bs7etocv.fsf@tleepslib.sk.tsukuba.ac.jp> (stephen@xemacs.org) X-XEmacs-List: design Errors-To: xemacs-design-admin@xemacs.org X-BeenThere: xemacs-design@xemacs.org X-Mailman-Version: 2.0.1 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: Discussion of design and features for XEmacs. List-Unsubscribe: , Xref: main.gmane.org gmane.emacs.xemacs.design:1386 gmane.emacs.devel:7463 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:7463 Miles> ... how did people write info files then (by hand?!)? "Stephen J. Turnbull" responded: Been there, done that. Texinfo is not an improvement, if restricted to generating Info files. (Obviously the retargetable backend is a _huge_ improvement, and I wouldn't go back, ... and then said: .... although I'd like to go forward from Texinfo to XMLinfo.) Please write a short, introductory document explaining how to convert a document written with XML markup to good, readable Texinfo automatically, so it can then be converted to DVI (and Postscript, PDF, etc), to HTML, to Info, and back again to DocBook and XML. Also, please explain how to output a document written in an XML format to Info and to the various other output formats. This is important. Pretty obviously, many people are writing documentation in some form or other of XML. The best can be converted to Texinfo. Some XML formats require high resolution interfaces for people using their eyes; these formats are poor for documentation. Note that one of the major goals of Texinfo is to inspire and constrain people to write documentation that is readable when typeset and printed, when using a slow connection, or when working eyes-free (as with driving a car or being permanently blind). (That is to say, `readable' means `listen-able using Emacspeak to convert text to speech'.) More than a decade ago, we considered switching from Texinfo to LaTeX as the base markup language. However, I found that people tended to use LaTeX as a markup language for high-resolution typesetting and it could not be used in all the output formats that Texinfo supports. A great XML documentation format has to be constrained in the same way as Texinfo -- this means that the best test for a great XML documentation format is that it converts to good, readable Texinfo automatically. (I keep saying `good, readable Texinfo' because I have been told that sometimes, XML sources are harder to read than Texinfo sources; obviously, if this is true, we want to make sure that Texinfo keeps its good qualities; and in any case, the converter should do a good job.) I am primarily a Texinfo person; I know little about the procedures for converting one or other XML format to Texinfo (although I have done it , to be sure it can be done). I can never remember quite how to describe how XML works. (I.e., XML itself is not a mark up language, but is a set of rules for creating different ones. What determines the mark up language itself, and how do you employ that?) I cannot remember how to determine whether an XML source can be converted to at least as many different output formats as Texinfo, nor how to do that. I cannot remember how to convert an XML source to Texinfo. I do remember how to convert Texinfo to DocBook and XML -- I put the commands in the front of documents I write, so it is easy for me to check my work by copying the commands and executing them in a shell. For example: ## DocBook output makeinfo --docbook --no-split --paragraph-indent=0 \ --verbose Rights-duty-metaphor.texi ## XML output makeinfo --xml --no-split --paragraph-indent=0 \ --verbose Rights-duty-metaphor.texi Please tell me how to create a file for printing, how to convert to Info, and how to convert to HTML these DocBook and XML outputs that makeinfo creates. Also, more generally, please tell me about and what to do with XML: how to convert to Texinfo, how to convert to the various output formats, how to determine if the XML format is any good for documentation and what the good ones are, where to get them for sources, and how to install them from Debian. And when you write, please presume that at least one of your readers (me) is very tired, does not have much time, is situationally (or maybe natively) stupid .... and will have to come back to what you wrote to determine yet again how to do the simplest thing. Thank you. -- Robert J. Chassell bob@rattlesnake.com bob@gnu.org Rattlesnake Enterprises http://www.rattlesnake.com Free Software Foundation http://www.gnu.org GnuPG Key ID: 004B4AC8