From owner-freebsd-doc Wed May 14 11:03:42 1997 Return-Path: Received: (from root@localhost) by hub.freebsd.org (8.8.5/8.8.5) id LAA24161 for doc-outgoing; Wed, 14 May 1997 11:03:42 -0700 (PDT) Received: from coconut.blueberry.co.uk ([194.70.52.66]) by hub.freebsd.org (8.8.5/8.8.5) with ESMTP id LAA24152; Wed, 14 May 1997 11:03:33 -0700 (PDT) Received: (from nik@localhost) by coconut.blueberry.co.uk (8.8.5/8.8.5) id TAA03103; Wed, 14 May 1997 19:03:02 +0100 (BST) Message-ID: <19970514190302.20618@blueberry.co.uk> Date: Wed, 14 May 1997 19:03:02 +0100 From: Nik Clayton To: questions@freebsd.org Cc: doc@freebsd.org Subject: Re: Is Thot (WYSIWIG editor) for you? References: <14271.863600208@time.cdrom.com> <3379F24B.934@fps.biblos.unal.edu.co> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.69e In-Reply-To: <3379F24B.934@fps.biblos.unal.edu.co>; from Pedro F. Giffuni on Wed, May 14, 1997 at 10:11:39AM -0700 Organization: Blueberry New Media Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Wed, May 14, 1997 at 10:11:39AM -0700, Pedro F. Giffuni wrote: > Jordan K. Hubbard wrote: > > > > > What I am pitching is for is that if Thot is good we can start advertising it > > > and hopefully standardize our internal documentation based on its format. > > > Internal documentation meaning things like : reports, articles, etc... > > > > But we already have such a standard and it's called SGML.... > > SGML is a format, Thot is a toolset and an editor. Correct me if I'm > wrong, but I haven't seen a good SGML tool in our ports tree. Sort of right, sort of wrong. > Thot produces Latex and HTML. AFAIK HTML is a subset of SGML, so I > guess Thot fits into the "standard". My $0.02 follows. I haven't used Thot (no Motif license) but I have trawled the FTP site, and read the docs. Doubtless John Fieber will jump in if I have any of this wrong. SGML is a meta-language. It describes other languages. HTML is one language that can be described by SGML. There are many others. One of these others is called DocBook. Current thinking on the FreeBSD documentation project (of which I am not a member) is to move from using the LinuxDoc TeX format to writing documents marked up according to the DocBook style. Once this is done, HTML can be produced, as can plain text, PostScript and so on. DocBook is also *much* more expressive than HTML is. For example, a snippet of some docs I'm converting to DocBook (and will then be submitting to the project as a tutorial) is /var/tmp/root now contains all the files that should be placed in appropriate locations below /. You now have to go through each of these files, determining how they differ from your existing files. This is not a task that can be automated (at the moment). Note that some of the files that will have been installed in /var/tmp/root have a leading '.'. Make sure you use As you can see, there is extra markup in there to denote things like commands, and filenames. There are many, many more. This sort of verbosity in the markup is a Good Thing. It allows more useful searches of the information to be carried out. It makes it easier to ensure that information is presented consistently. And it retains as much semantic information about the documentation as possible. Eventually, *all* FreeBSD project documentation will be written with DocBook, in much the same way as it's currently written in LinuxDoc. What is needed, as far as I can tell, is a decent environment for editing these files. Ideally, it should :- 1 Understand an SGML DTD, and prevent you creating invalid documents according to the specification 2 Have an editor that makes editing DocBook as painless as possible. Drop down lists of styles. A sample 'WYSIWYG' display[1], that sort of thing 3 Make it easy to convert DocBook documents to other formats [1] I *know* this term cannot really be applied to semantic markup. However, an editor that supported variable-width fonts, allowed the tags to be hidden, showed different marked up sections in different colours/styles, and was user configurable, would be very handy. We don't have a one stop shop that does all that. Yet. The SGML tools take care of point 1. But they don't do it interactively. It's like writing code, you have the "Edit; Compile; Fix; Compile" cycle. We don't have anything close to 2. The nearest product, as far as I can tell, would be SoftQuad's Author/Editor, which doesn't run on Intel unices anyway (it does, however, work with Win3.1/95, how are the WINE folks getting on :-) ). More info on it at http://www.softquad.co.uk/products/authored/ If my understanding of Thot is correct, *Thot does not do this*. It uses it's own styles and is not SGML aware. Point 3 is handled. At least, I know of (and use) a DocBook -> HTML converter. DocBook -> Text can be kludged with Lynx. Right now, I do all this with Xemacs, the SGML tools that come with 2.2, back fitted to 2.1.7, and a Makefile to automate the conversions. It's not pretty, but it works. John Fieber's documentation at http://fallout.campusview.indiana.edu/~jfieber/docbook/ was invaluable in getting me kickstarted. IMHO, what's needed is for people with an interest in the documentation to build a nice editing environment (based around whichever editor people feel most comfortable with), all the necessary tools, and some samples of documentation -- a cookbook, if you will -- that makes it simpler for people who have the urge to get involved. Plus, of course, documentation so that people can use this. Make it available as a package/port, and make sure it works across as many versions of FreeBSD as possible. I can do some of this. I could probably port the tools (tho' I've never attempted a port before). I could write some of the first-time user documentation. I could write sample documents to show the range of DocBook markup available. But, I can't do all of it. And I'm probably not qualified to anyway, since I have my own questions for the Doc project gurus to answer. Thoughts? I've cc'd this to the 'doc' mailing list, which is (I guess) where this sort of discussion should really be taking place, instead of on questions-. N -- --+=[ Blueberry Hill Blueberry New Media ]=+-- --+=[ http://www.blueberry.co.uk/ 1/9 Chelsea Harbour Design Centre, ]=+-- --+=[ WebMaster@blueberry.co.uk London, England, SW10 0XE ]=+-- --+=[ Those who do not read Dilbert are doomed to repeat it ]ENTP