From owner-freebsd-doc Sat Jun 8 17:59:21 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id RAA15520 for doc-outgoing; Sat, 8 Jun 1996 17:59:21 -0700 (PDT) Received: from Fieber-John.campusview.indiana.edu (Fieber-John.campusview.indiana.edu [149.159.1.34]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id RAA15509 for ; Sat, 8 Jun 1996 17:59:17 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id TAA07544; Sat, 8 Jun 1996 19:59:09 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Sat, 8 Jun 1996 19:59:08 -0500 (EST) From: John Fieber X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Chuck Robey cc: Greg Lehey , FreeBSD Documenters Subject: Re: How do I write this SGML stuff? In-Reply-To: Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Sat, 8 Jun 1996, Chuck Robey wrote: > No, we aren't wed to LaTeX, we're discussing sgml tools that convert to > troff (which I like too) and to html, LaTeX, etc. We don't write our > docs in troff, we're doing it in some kinda sgml, and I guess the > discussion is about the tools we're using to get from sgml to (whatever). And SGML has *nothing* to do with formatting. It is about marking up a documents content based on the nature of that content on the premise that a much broader range of uses can be achieved from a document marked up in that manner. The most important use for us here and now is rendering that document as (a) a set of HTML pages, (b) an ascii document and (c) a typeset document. For the latter two, groff will be the tool of choice. Currently groff is used for ascii, with less than stunning results, and LaTeX is used for typsetting, which offers good results but is a hassle because TeX is a port, while groff is standard equipment. The other issue at hand is the desire to free ourselves from the limitations of the linuxdoc DTD whose markup models is based on LaTeX which ultimately undermines the benefits of using SGML. Docbook looks to be a likely choice as the successor, being a DTD designed by and for the software technical writers. Such a move necessitates a more powerful document manipulation tool than we currently have because there is a wider gulf between the descriptive markup that the DTD provides and the procedural markup used to drive a formatter. > view of John Clark's sgml tools. I'm very unhappy with our present ^^^^- James actually > conversion tools from sgml to whatever, because they are one pass things, > have limited intelligence and capability, and were chiefly made to > convert from sgml to LaTeX. And the only reason conversion to html works at all is because of a second and third pass implemented in perl and even that is too limiting. What instant does is read the document into a tree (any conforming sgml document can be represented as a tree) which you can navigate as you please during processing; "passes" is no longer relevant terminology. For example, if I hit a cross reference, I can easily search the tree for the other end of the link, scan up the tree until I find an appropriate sectioning node, eg, , grab the text out of the tag that follows and insert it where I started. A big improvement for HTML output is being able to look ahead at the sectioning and make more intelligent decisions about how to break up the the document into smaller files. The current method provides a terrible mix, with many pages of only a paragraph or so (sections that should be presented together) and others that are terribly long (sections that must be split). -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================