From owner-freebsd-doc Sun Jun 2 06:39:16 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id GAA19234 for doc-outgoing; Sun, 2 Jun 1996 06:39:16 -0700 (PDT) Received: from upsmot01.msn.com (upsmot01.msn.com [204.95.110.78]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id GAA19229 for ; Sun, 2 Jun 1996 06:39:14 -0700 (PDT) Received: from upmajb04.msn.com ([204.95.110.81]) by upsmot01.msn.com (8.6.8.1/Configuration 4) with SMTP id GAA11987 for ; Sun, 2 Jun 1996 06:31:04 -0700 Date: Sun, 2 Jun 96 14:37:09 UT From: "marc pechter" <30895-oem@msn.com> Message-Id: To: doc@freebsd.org Subject: pechter family relative Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk dear bill i wonder if we are related. my name is maec pechter, i live in fort lauderdale fla (30895-oem@msn.com) let me hear from you , Cousin Marc From owner-freebsd-doc Sun Jun 2 13:07:17 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id NAA07055 for doc-outgoing; Sun, 2 Jun 1996 13:07:17 -0700 (PDT) Received: from who.cdrom.com (who.cdrom.com [204.216.27.3]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id NAA07043 for ; Sun, 2 Jun 1996 13:07:15 -0700 (PDT) Received: from timber20 (timber20.timberland.lib.wa.us [199.250.57.20]) by who.cdrom.com (8.6.12/8.6.11) with ESMTP id NAA03230 for ; Sun, 2 Jun 1996 13:07:08 -0700 Received: by timber20 (SMI-8.6/SMI-SVR4) id NAA26679; Sun, 2 Jun 1996 13:05:44 -0700 Date: Sun, 2 Jun 1996 13:05:44 -0700 Message-Id: <199606022005.NAA26679@timber20> To: freebsd-doc@FreeBSD.ORG X-Mailer: Lynx, Version 2.3 X-Personal_name: Rick Brandon From: E.101.Lakeway.Dr.;Shelton@who.cdrom.com;;, Wa.98584@timberland.lib.wa.us Sender: owner-doc@FreeBSD.ORG X-Loop: FreeBSD.org Precedence: bulk From owner-freebsd-doc Mon Jun 3 00:44:46 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id AAA16739 for doc-outgoing; Mon, 3 Jun 1996 00:44:46 -0700 (PDT) Received: from cdale1.midwest.net (root@cdale1.midwest.net [204.248.40.2]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id AAA16734 for ; Mon, 3 Jun 1996 00:44:44 -0700 (PDT) Received: from jmiller.midwest.net (peoria6.midwest.net [206.158.80.6]) by cdale1.midwest.net (8.7.3/8.7.3) with SMTP id CAA20797 for ; Mon, 3 Jun 1996 02:27:57 -0500 (CDT) Message-ID: <31B29821.247E@midwest.net> Date: Mon, 03 Jun 1996 02:45:37 -0500 From: Jeffrey Miller Organization: Peoria Adult Education Center X-Mailer: Mozilla 2.0 (Win95; U) MIME-Version: 1.0 To: doc@freebsd.org Subject: Internet Training CD-ROMS?? X-URL: http://www.freebsd.org/tutorials/index.html Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk I am looking for a CD-ROM that would be a simulation of being on the NET for educatuional uses. We have 1 computer for 200 adult users on the NET and thought if I could find a CD-ROM that "mirrored" the contents of the Web & FTP sites (etc) that I could instruct the students via CD-ROM before they ever got plugged into the NET (one at a time!) I just know that someone has to have someting like this already produced but I don't know where to look. I thought you could lead me in the right direction, or may know off hand where I should check??? Thank you so much! -- Jeffrey Miller Peoria Adult Education Center jmiller@midwest.net From owner-freebsd-doc Mon Jun 3 06:52:47 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id GAA16265 for doc-outgoing; Mon, 3 Jun 1996 06:52:47 -0700 (PDT) Received: from uu.elvisti.kiev.ua ([193.125.28.132]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id GAA16112; Mon, 3 Jun 1996 06:47:56 -0700 (PDT) Received: from office.elvisti.kiev.ua (office.elvisti.kiev.ua [193.125.28.129]) by uu.elvisti.kiev.ua (8.7.5/8.7.3) with ESMTP id QAA15213; Mon, 3 Jun 1996 16:49:21 +0300 (EET DST) Received: (from stesin@localhost) by office.elvisti.kiev.ua (8.6.12/8.ElVisti) id QAA09685; Mon, 3 Jun 1996 16:49:15 +0300 From: "Andrew V. Stesin" Message-Id: <199606031349.QAA09685@office.elvisti.kiev.ua> Subject: Mystery has gone! Thanks! (How a non-obvious HW problem was solved) To: se@zpr.uni-koeln.de (Stefan Esser) Date: Mon, 3 Jun 1996 16:49:13 +0300 (EET DST) Cc: hardware@freebsd.org, doc@freebsd.org In-Reply-To: <199606022214.AA22260@Sisyphos> from "Stefan Esser" at Jun 3, 96 00:14:33 am X-Mailer: ELM [version 2.4 PL24alpha5] Content-Type: text Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk Dear Stefan and FreeBSD people, it seems to me that I found a REAL solution to this. See below. [... a configuration I'm talking about: ...] # } A machine, our recently built firewall gateway to Internet, # } is: # } ATC-1425B mainboard, PCI, SiS 496/7 chipset; # } 16Mb RAM; # } AMD 5x133 CPU; # } NCR 53c810 SCSI; # } 1Gb Conner CFP1060S drive (recent, good one); # } two modems on the onboard COMs (SLIP lines to the world); # } 1 Ethernet card. # } # } OS: FreeBSD-stable as of late March. # } Add-ons: IPfilter 3.0.3+ (by Darren Reed) as in-kernel IP filtering # } facility, Squid 1.0beta7 WWW proxy cache daemon. # } # } The machine was experiencing spontaneous reboots from time to time. # } Either silent reboots, or prefaced with messages from NCR driver # } (like "NCR dead?"). [... kind explanations and suggestions mostly omitted ...] # The main difference is that the 21041 is a PCI bus-master. Yes, that's why I took it out -- my first guess was that this particular MB has some breakage in PCI implementation internals, which breaks busmastering PCI devices (isn't NCR a busmaster, too, btw?) Now I see I was wrong. # There have been other motherboards that did not work correctly # with multiple PCI bus masters, but I have no idea about the SiS # chip set being broken in such a way. SiS 496/7 -based MBs are "the line of choise" for 486 boards at our site. They're generally Ok -- not as fast as ASUS SP3G (I have some experience with those, too, but they dissapeared recently from stocks); they're stable and reliable. We have some older SiS boards from SOYO, and ATC-1425B -s are from different vendor (some Taiwanese, too) and they do support AMD 5x133. Have also seen ASUS with SiS 496/7 (SP3), too -- I didn't liked them (only 2 RAM sockets, were unstable under FreeBSD, though people claims that it was due to ancient BIOS firmware). As for multiple busmasters in SiS boards... We had a 4-ether router for a while, with: NCR, 2 'lnc' AMD PCI boards, and Realtek PCI NE2000 clone. All 4 PCI slots were full. Lance ethers are busmasters, supported by ISA driver (PCI NE2000 worked with ISA 'ed' driver). CPU was AMD dx2/80 This monster was reliable and fast, but it threw couples of messages about failed DMA on lnc[01] and "NCR dead?" occasionally under peak loads. But drivers performed hardware reset, and it worked for weeks this way. Being a cautious person, I redesigned network layout recently :) when Realtek PCI NE2000 card died :-))) My experience tells me that SiS 496/7 boards are Ok, reasonably "old" and stable, but they do not enjoy overloading of their slots with peripherials. If you'll fill all ISA and PCI slots -- be ready to get spontaneous crashes and hardware troubles. (Seen this on our UUCP mail host). Having at least one ISA and one PCI slot empty is Ok. # Some systems did not work reliably with all PCI performance # options enabled (e.g. PCI Burst Mode, Write Buffers, ...), and As I was told by hardware technical guys, these problems were pretty often half a year ago; recent revisions of BIOSes (Award, AMI) are improved and the problems (kinda of?) went away. # I have seen other reports where a high interrupt load made the # kernel fail with the PC pointing into the NCR driver. But I do # not think this necessarliy points out a driver problem, since Your'e 101% right. [...] # I've been using the NCR and a DEC 21040 based Znyx 312 for some # time in my ASUS SP3G system, and never had the kind of trouble # you see. Our "approved" kind of HW setup is: SiS496/7 based board, AMD 5x133 CPU, NCR 53c810, IBM SCSI drive(s), DEC 21040-based ether, any S3 868 video, other periph. to your taste, 16+ megs of RAM. Cheap, solid and productive; I highly recommend it. # If your system currently got any performance options enabled, I'd # just try without them. Wait states added to memory and cache accesses # and PCI setup to work without burst transfers should help find a # possible hardware performance problem. The final solution which I found: SIMMs weren't of appropriate quality!!! despite they were marked as 60ns!!!! WHAT A FSCK!!!! The DRAM chips on the SIMMs are Texas Instruments, detailed chip info available upon request (in case anyone interested). ATC-1425B has "Auto configuration" option in BIOS setup. "Huh, it should be a pretty safe kind of setup, if it puts ISA to 7.159MHz!" -- I thought initially :) It was turned "on". After all kinds of fighting with PCI setup options (performance degrade -- but still crashes!) that's what I did two days ago: 1. Turned "Auto config" in BIOS "off". 2. ISA BUS clock -- put to 33MHz/4 -- it's appropriate. 3. Added a _single_ (!) wait state to the BIOS timing which manages transfers between L2 cache (btw L2 cache is 15ns on ATC-1425B board) and main DRAM, just changed it from 2 to 3. (The machine is up now, if someone needs an exact spelling of how this BIOS option is called -- ask). And -- YESS!!! the problem dissapeared! (The machine stood up bravely under flood pings and TCP shoots from 3(!) other FreeBSD boxes, and with disk activity artificially inspired -- for 48 hours non-stop, previously just 5-10 minutes of stress killed it). The box is still up now, no more problems observed. (Probably I'll try to put Lance ether into it, just for experiment -- but I simply don't want to reboot it at all, it holds our Inet connection!) Thanks to all you friends who supported me! Please take my sincere apologies for taking your time! I hope my experience will be of some use for Hardware Compatibility Guide which is now in preparation, and people will benefit a bit from it. -- With best regards -- Andrew Stesin. +380 (44) 2760188 +380 (44) 2713457 +380 (44) 2713560 "You may delegate authority, but not responsibility." Frank's Management Rule #1. From owner-freebsd-doc Mon Jun 3 08:49:20 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id IAA25395 for doc-outgoing; Mon, 3 Jun 1996 08:49:20 -0700 (PDT) Received: from persprog.com (persprog.com [204.215.255.203]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id IAA25386; Mon, 3 Jun 1996 08:49:14 -0700 (PDT) Received: by persprog.com (8.7.5/4.10) id KAA10561; Mon, 3 Jun 1996 10:33:21 -0500 Received: from novell(192.2.2.201) by cerberus.ppi.com via smap (V1.3) id sma010557; Mon Jun 3 11:33:20 1996 Received: from NOVELL/SpoolDir by novell.persprog.com (Mercury 1.12); Mon, 3 Jun 96 11:31:44 +0500 Received: from SpoolDir by NOVELL (Mercury 1.12); Mon, 3 Jun 96 11:31:22 +0500 From: "David Alderman" Organization: Personalized Programming, Inc. To: "Andrew V. Stesin" , hardware@FreeBSD.org, doc@FreeBSD.org Date: Mon, 3 Jun 1996 11:31:21 EST Subject: Re: Mystery has gone! Thanks! (How a non-obvious HW problem was X-Confirm-Reading-To: "David Alderman" X-pmrqc: 1 Priority: normal X-mailer: Pegasus Mail for Windows (v2.31) Message-ID: Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk > From: "Andrew V. Stesin" > Subject: Mystery has gone! Thanks! (How a non-obvious HW problem was solved) Lot's of useful stuff deleted... > I hope my experience will be of some use for Hardware > Compatibility Guide which is now in preparation, and > people will benefit a bit from it. > Is the Hardware Compatibility Guide available in draft? I would not mind proofreading it, that is, I really want to see what does and does not work and would be willing to offer corrections for the privilege! Who knows, I might be able to add some items that have worked and not worked at the University of Florida (where I still know a few people) and at home. Also, is there a place to submit known hardware incompatibities (after thrashing them out here, of course)? ====================================== When philosophy conflicts with reality, choose reality. Dave Alderman -- dave@persprog.com ====================================== From owner-freebsd-doc Mon Jun 3 10:10:09 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id KAA03142 for doc-outgoing; Mon, 3 Jun 1996 10:10:09 -0700 (PDT) Received: from uu.elvisti.kiev.ua ([193.125.28.132]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id KAA02981; Mon, 3 Jun 1996 10:07:24 -0700 (PDT) Received: from office.elvisti.kiev.ua (office.elvisti.kiev.ua [193.125.28.129]) by uu.elvisti.kiev.ua (8.7.5/8.7.3) with ESMTP id UAA18840; Mon, 3 Jun 1996 20:09:15 +0300 (EET DST) Received: (from stesin@localhost) by office.elvisti.kiev.ua (8.6.12/8.ElVisti) id UAA16968; Mon, 3 Jun 1996 20:09:15 +0300 From: "Andrew V. Stesin" Message-Id: <199606031709.UAA16968@office.elvisti.kiev.ua> Subject: Re: Mystery has gone! Thanks! (How a non-obvious HW problem was To: dave@persprog.com (David Alderman) Date: Mon, 3 Jun 1996 20:09:14 +0300 (EET DST) Cc: stesin@elvisti.kiev.ua, hardware@FreeBSD.org, doc@FreeBSD.org In-Reply-To: from "David Alderman" at Jun 3, 96 11:31:21 am X-Mailer: ELM [version 2.4 PL24alpha5] Content-Type: text Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk Hi Dave, # Is the Hardware Compatibility Guide available in draft? Francisco Reyes was the exact person who spoke about it recently. I hope he monitors the appropriate lists. -- With best regards -- Andrew Stesin. +380 (44) 2760188 +380 (44) 2713457 +380 (44) 2713560 "You may delegate authority, but not responsibility." Frank's Management Rule #1. From owner-freebsd-doc Tue Jun 4 10:21:17 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id KAA26719 for doc-outgoing; Tue, 4 Jun 1996 10:21:17 -0700 (PDT) Received: from diablo.ppp.de (diablo.ppp.de [193.141.101.34]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id KAA26707 for ; Tue, 4 Jun 1996 10:21:12 -0700 (PDT) Received: from allegro.lemis.de by diablo.ppp.de with smtp (Smail3.1.28.1 #1) id m0uQzmo-000Qa0C; Tue, 4 Jun 96 19:20 MET DST From: grog@lemis.de (Greg Lehey) Organisation: LEMIS, Schellnhausen 2, 36325 Feldatal, Germany Phone: +49-6637-919123 Fax: +49-6637-919122 Received: (grog@localhost) by allegro.lemis.de (8.6.9/8.6.9) id TAA13705 for doc@FreeBSD.org; Tue, 4 Jun 1996 19:14:05 +0200 Message-Id: <199606041714.TAA13705@allegro.lemis.de> Subject: How do I write this SGML stuff? To: doc@FreeBSD.org (FreeBSD Documenters) Date: Tue, 4 Jun 1996 19:14:05 +0200 (MET DST) X-Mailer: ELM [version 2.4 PL23] MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk I've just been trying to convert my roff text on installing a second disk into SGML, and I find that I don't have any documentation. I've guessed a lot from the table sources, but I've probably made a lot of mistakes, and I can't find how to do pictures and tables. If there's no easy way to do that in SGML, is there a way to import PostScript? That would do just as easily. If somebody can point me to documentation on the subject, I'd be grateful. On an allied subject, is there any way to just browse through the manual without having to remember where in the structure you are, and possibly even such advanced things as paging with the keyboard keys instead of the mouse? Greg From owner-freebsd-doc Tue Jun 4 12:19:02 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id MAA06846 for doc-outgoing; Tue, 4 Jun 1996 12:19:02 -0700 (PDT) Received: from gatekeeper.fsl.noaa.gov (gatekeeper.fsl.noaa.gov [137.75.131.181]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id MAA06841 for ; Tue, 4 Jun 1996 12:19:00 -0700 (PDT) Received: from emu.fsl.noaa.gov (kelly@emu.fsl.noaa.gov [137.75.60.32]) by gatekeeper.fsl.noaa.gov (8.7.5/8.7.3) with ESMTP id TAA09724; Tue, 4 Jun 1996 19:18:52 GMT Message-Id: <199606041918.TAA09724@gatekeeper.fsl.noaa.gov> Received: by emu.fsl.noaa.gov (1.40.112.3/16.2) id AA016605931; Tue, 4 Jun 1996 13:18:51 -0600 Date: Tue, 4 Jun 1996 13:18:51 -0600 From: Sean Kelly To: grog@lemis.de Cc: doc@freebsd.org In-Reply-To: <199606041714.TAA13705@allegro.lemis.de> (grog@lemis.de) Subject: Re: How do I write this SGML stuff? Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk >>>>> "Greg" == Greg Lehey writes: Greg> I've just been trying to convert my roff text on installing Greg> a second disk into SGML, and I find that I don't have any Greg> documentation. I've guessed a lot from the table sources, Greg> but I've probably made a lot of mistakes, and I can't find Greg> how to do pictures and tables. I had three main sources of info to learn the DTD we're using. First was the (C-c, <) key in Emacs (to list what the valid tags are in the current context). Second was existing text. Third was the DTD itself. I finally figured out how to import PostScript ... although I don't know if this usage is ``blessed.'' (John? Comments?)
Any caption text.
In LaTeX, this becomes a \figure environment using \epsffile to insert blah.ps. Our DTD adds the `.ps' no matter what, so don't name your EPS files `.eps'. On my system, I also have to modify the \documentstyle line and add epsf to it: \documentstyle[linuxdoc,epsf]{article} In HTML, nothing appears. In ASCII, just the caption appears. You can also replace with (which means nothing as far as I'm concerned) to get a vetical space in which to put a figure later. skips 24 picas. Any TeX units will work. Again, no effect in HTML, and just the caption in ASCII. Next, I need to learn what you've learned: the tables! Greg> On an allied subject, is there any way to just browse Greg> through the manual without having to remember where in the Greg> structure you are, and possibly even such advanced things as Greg> paging with the keyboard keys instead of the mouse? Depends on your web browser---if you're browsing the HTML version. On Netscape, the PageUp/PageDown keys work. Maybe we'll come up with a special browser just for the handbook that'll have an adjunct window in which a ``You Are Here'' display will be constantly updated. Or just a Java app. -- Sean Kelly NOAA Forecast Systems Laboratory kelly@fsl.noaa.gov Boulder Colorado USA http://www-sdd.fsl.noaa.gov/~kelly/ From owner-freebsd-doc Tue Jun 4 13:37:37 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id NAA11753 for doc-outgoing; Tue, 4 Jun 1996 13:37:37 -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 NAA11745 for ; Tue, 4 Jun 1996 13:37:30 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id PAA07676; Tue, 4 Jun 1996 15:36:50 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Tue, 4 Jun 1996 15:36:49 -0500 (EST) From: John Fieber X-Sender: jfieber@Fieber-John.campusview.indiana.edu Reply-To: John Fieber To: Greg Lehey cc: FreeBSD Documenters Subject: Re: How do I write this SGML stuff? In-Reply-To: <199606041714.TAA13705@allegro.lemis.de> 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 Tue, 4 Jun 1996, Greg Lehey wrote: > I've just been trying to convert my roff text on installing a second > disk into SGML, and I find that I don't have any documentation. I've > guessed a lot from the table sources, but I've probably made a lot of > mistakes, and I can't find how to do pictures and tables. This is a bit of a dilemma. Currently the handbook is made readable by the lowest common denominator, which means lynx, which means no tables or graphics. Adding support for tables would be trivial. In fact, it should already work for LaTeX output, but I have not actually tried it. The (lame) workaround is ascii graphics in a element. > If there's > no easy way to do that in SGML, is there a way to import PostScript? > That would do just as easily. If somebody can point me to > documentation on the subject, I'd be grateful. There is some documentation in /usr/src/share/sgml/FreeBSD/doc. It needs to be changed to reflect how things really are, but it should give you the basics. Just ignore all the stuff on the mechanics of making the conversions. > On an allied subject, is there any way to just browse through the > manual without having to remember where in the structure you are, What sort of cues would be most useful? The one element that is almost always on-screen in most browsers is (in html that is). I would target that for a more effective use, but space is tight. The general rule on <title> is that it should not be more than 64 characters. Any brilliant ideas on using this better are most welcome. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Tue Jun 4 14:02:15 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id OAA13248 for doc-outgoing; Tue, 4 Jun 1996 14:02:15 -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 OAA13230 for <doc@freebsd.org>; Tue, 4 Jun 1996 14:02:10 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id QAA07767; Tue, 4 Jun 1996 16:01:52 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Tue, 4 Jun 1996 16:01:51 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Sean Kelly <kelly@fsl.noaa.gov> cc: grog@lemis.de, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <199606041918.TAA09724@gatekeeper.fsl.noaa.gov> Message-ID: <Pine.NEB.3.93.960604153720.422P-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, Sean Kelly wrote: > Third was the DTD itself. Gee, and didn't you just about puke? ;-) In pondering what to do about it, I had visions of a totally new system and ditching the linuxdoc dtd. Unfortunately with the time I've been able to devote to it I don't see that happening very soon so I'm now plotting out a de-crufting project. I'll give a fair warning that <p> tags will NOT be implied by a blank line after the de-crufting. The way it is now is a headache downstream in the processing. And while I've got some troff experts on the line, how do I tell troff that I want the first character of a line to be a period, not a troff command? For example a line comes out of the sgml parser like this: .login is the file you put all your csh goodies in but need to do something so that . is a printing character instead of an error. > I finally figured out how to import PostScript ... although I don't > know if this usage is ``blessed.'' (John? Comments?) > > <figure> > <eps file="blah"> > <caption>Any caption text.</caption> > </figure> > > In LaTeX, this becomes a \figure environment using \epsffile to insert > blah.ps. Our DTD adds the `.ps' no matter what, so don't name your > EPS files `.eps'. Actually, its part of the translation, not the dtd, and it could be trivially changed. Would you like it changed? Frankly it makes more sense to me to NOT assume an extension. > On my system, I also have to modify the > \documentstyle line and add epsf to it: > > \documentstyle[linuxdoc,epsf]{article} You should be able to to this in your opening <article>, <report>, or <book> tag: <article opts="epsf"> > In HTML, nothing appears. In ASCII, just the caption appears. The current [nt]roff translation is: <eps> + ".if t .PSPIC [file].ps\n" ".if n .sp 4" + </eps> The HTML translation could probably be mashed into an <a href="file">file</a>. The file would have to manually be added to the makefile to get installed with the html files. > You can also replace <eps> with <ph> (which means nothing as far as > I'm concerned) to get a vetical space in which to put a figure later. Hmm... Picture Here? Preallocate Hole? Yes, the dtd needs some comments. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Tue Jun 4 14:53:17 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id OAA17338 for doc-outgoing; Tue, 4 Jun 1996 14:53:17 -0700 (PDT) Received: from gatekeeper.fsl.noaa.gov (gatekeeper.fsl.noaa.gov [137.75.131.181]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id OAA17333 for <doc@freebsd.org>; Tue, 4 Jun 1996 14:53:14 -0700 (PDT) Received: from emu.fsl.noaa.gov (kelly@emu.fsl.noaa.gov [137.75.60.32]) by gatekeeper.fsl.noaa.gov (8.7.5/8.7.3) with ESMTP id VAA10567; Tue, 4 Jun 1996 21:53:04 GMT Message-Id: <199606042153.VAA10567@gatekeeper.fsl.noaa.gov> Received: by emu.fsl.noaa.gov (1.40.112.3/16.2) id AA020905183; Tue, 4 Jun 1996 15:53:03 -0600 Date: Tue, 4 Jun 1996 15:53:03 -0600 From: Sean Kelly <kelly@fsl.noaa.gov> To: jfieber@indiana.edu Cc: grog@lemis.de, doc@freebsd.org In-Reply-To: <Pine.NEB.3.93.960604153720.422P-100000@Fieber-John.campusview.indiana.edu> (message from John Fieber on Tue, 4 Jun 1996 16:01:51 -0500 (EST)) Subject: Re: How do I write this SGML stuff? Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk >>>>> "John" == John Fieber <jfieber@indiana.edu> writes: >> Third was the DTD itself. John> Gee, and didn't you just about puke? ;-) I definitely felt ill. But since I'm hardly an SGML expert, it wasn't too bad! I didn't even call in sick the next day ... although I can almost hear my boss saying ``I saw a disgusting DTD yesterday and won't be in today.'' :-) John> In pondering what to do about it, I had visions of a totally John> new system and ditching the linuxdoc dtd. You're not the only one. For one, it has the substring `linux' in it. Okay, I'll admit that that particular string occurs often in quite a lot of FreeBSD. More importantly, it's a much better DTD for writing journal articles than for technical documentation of a computer system---but that's far more because of its lineage in all likelihood. Anyway, yes, I'd love to see a DTD that really reflects the needs of technical writing. Sure, it needs section headings and code blocks, but it also needs warning boxes, and tricks/tips areas. And it'd certainly be nice to have figures of some sort (pbmtoascii, anyone?) but tables even more so. And if not tables, than at least two-column lists. John> Unfortunately with the time I've been able to devote to it I John> don't see that happening very soon Yes, time's the problem. I unfortunately have quite a deficit of it as well :-( John> I'll give a fair warning that <p> tags will NOT be implied John> by a blank line after the de-crufting. No problem. John> a headache downstream in the processing. And while I've got John> some troff experts on the line, how do I tell troff that I John> want the first character of a line to be a period, not a John> troff command? Given that we already can go to LaTeX which can go to professionally typeset documents, why do we need to also go to troff which can go to professionally typeset documents? (And while I'm dreaming, how about ``sgmlfmt -f ps'' or ``sgmlfmt -f pdf''?) John> Actually, its part of the translation, not the dtd, and it John> could be trivially changed. See! Told ya I wasn't an SGML expert! :-) John> Would you like it changed? Frankly it makes more sense to John> me to NOT assume an extension. Absolutely. John> The HTML translation could probably be mashed into an <a John> href="file">file</a>. The file would have to manually be John> added to the makefile to get installed with the html files. Or perhaps sgmlfmt could do gs -dNOPAUSE -dSAFER -sDEVICE=gif -sOutputFile=- <file> -c quit for each referenced EPS file in the SGML source during the HTML conversion. Maybe even add the alt="Image Here" for the benefit of Lynx users or the ASCII version. But then there's the time problem again ... sigh. -- Sean Kelly NOAA Forecast Systems Laboratory kelly@fsl.noaa.gov Boulder Colorado USA http://www-sdd.fsl.noaa.gov/~kelly/ From owner-freebsd-doc Tue Jun 4 15:37:31 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id PAA19970 for doc-outgoing; Tue, 4 Jun 1996 15:37:31 -0700 (PDT) Received: from distortion.eng.umd.edu (distortion.eng.umd.edu [129.2.98.6]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id PAA19961 for <doc@freebsd.org>; Tue, 4 Jun 1996 15:37:28 -0700 (PDT) Received: from ginger.eng.umd.edu (ginger.eng.umd.edu [129.2.98.204]) by distortion.eng.umd.edu (8.7.5/8.7.3) with ESMTP id SAA10115; Tue, 4 Jun 1996 18:32:21 -0400 (EDT) Received: (from chuckr@localhost) by ginger.eng.umd.edu (8.7.5/8.7.3) id SAA27677; Tue, 4 Jun 1996 18:32:21 -0400 (EDT) Date: Tue, 4 Jun 1996 18:32:20 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@ginger.eng.umd.edu To: John Fieber <jfieber@indiana.edu> cc: Sean Kelly <kelly@fsl.noaa.gov>, grog@lemis.de, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <Pine.NEB.3.93.960604153720.422P-100000@Fieber-John.campusview.indiana.edu> Message-ID: <Pine.OSF.3.91.960604175325.26610C-100000@ginger.eng.umd.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, John Fieber wrote: > On Tue, 4 Jun 1996, Sean Kelly wrote: > > > Third was the DTD itself. > > Gee, and didn't you just about puke? ;-) > > In pondering what to do about it, I had visions of a totally new > system and ditching the linuxdoc dtd. Unfortunately with the > time I've been able to devote to it I don't see that happening > very soon so I'm now plotting out a de-crufting project. I'll > give a fair warning that <p> tags will NOT be implied by a blank > line after the de-crufting. The way it is now is a headache > downstream in the processing. And while I've got some troff > experts on the line, how do I tell troff that I want the first > character of a line to be a period, not a troff command? For > example a line comes out of the sgml parser like this: > > .login is the file you put all your csh goodies in > > but need to do something so that . is a printing character > instead of an error. I'm in the opposite corner, I can handle troff, but not sgml (lord knows I've tried). There's several answers to starting a line with .login. You could do \.login, to escape the dot. You could alternatively use the .tr command to translate some character (I'll use #, you'll get the idea) to make things simpler: .tr #. Then if #login shows up in the text, .login will print, even at the beginning of a line. You could do a macro that first defined # as ., then reset it .tr #. \" don't use # in the following string! #login (no other pounds in this line!) .tr ## However, that translation from # to . will stay in effect until troff breaks the line (at the end of the line). One last method uses the define strings command. groff has an extension (non-standard in troff) that lets me use long names here. you usually print one character defined string using \*X (where X indicates string name) of \*(XX (where XX indicates string name, 2 char). Groff allows for \*[anyLongNameILike] so do this: .ds LeadingDot \&. \" \& is zero width char, foil the logic! \*[LeadingDot]login That'll do it too. Of course, just prepending \& to any dot makes it unintelligible to troff, and that's compatible with standard troff (who'd use that?) > ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- From owner-freebsd-doc Tue Jun 4 15:44:00 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id PAA20436 for doc-outgoing; Tue, 4 Jun 1996 15:44:00 -0700 (PDT) Received: from jolt.eng.umd.edu (jolt.eng.umd.edu [129.2.102.5]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id PAA20427 for <doc@freebsd.org>; Tue, 4 Jun 1996 15:43:58 -0700 (PDT) Received: from ginger.eng.umd.edu (ginger.eng.umd.edu [129.2.98.204]) by jolt.eng.umd.edu (8.7.5/8.7.3) with ESMTP id SAA28284; Tue, 4 Jun 1996 18:43:53 -0400 (EDT) Received: (from chuckr@localhost) by ginger.eng.umd.edu (8.7.5/8.7.3) id SAA29666; Tue, 4 Jun 1996 18:43:52 -0400 (EDT) Date: Tue, 4 Jun 1996 18:43:52 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@ginger.eng.umd.edu To: Sean Kelly <kelly@fsl.noaa.gov> cc: jfieber@indiana.edu, grog@lemis.de, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <199606042153.VAA10567@gatekeeper.fsl.noaa.gov> Message-ID: <Pine.OSF.3.91.960604184209.26610D-100000@ginger.eng.umd.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, Sean Kelly wrote: > >>>>> "John" == John Fieber <jfieber@indiana.edu> writes: > > >> Third was the DTD itself. > John> Gee, and didn't you just about puke? ;-) > > I definitely felt ill. But since I'm hardly an SGML expert, it wasn't > too bad! I didn't even call in sick the next day ... although I can > almost hear my boss saying ``I saw a disgusting DTD yesterday and > won't be in today.'' :-) > > John> In pondering what to do about it, I had visions of a totally > John> new system and ditching the linuxdoc dtd. > > You're not the only one. For one, it has the substring `linux' in > it. Okay, I'll admit that that particular string occurs often in > quite a lot of FreeBSD. If you guys would adopt any system for producing docs that's documented enough so I could actually use it, I'd be real happy. Tossing linuxdoc would make my day. ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- From owner-freebsd-doc Tue Jun 4 17:21:47 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id RAA24729 for doc-outgoing; Tue, 4 Jun 1996 17:21:47 -0700 (PDT) Received: from mailbox.neosoft.com (mailbox.neosoft.com [206.109.1.16]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id RAA24713 for <doc@freebsd.org>; Tue, 4 Jun 1996 17:21:27 -0700 (PDT) Received: from bonkers.taronga.com (root@bonkers.neosoft.com [206.109.2.48]) by mailbox.neosoft.com (8.7.5/8.7.3) with SMTP id TAA27460 for <doc@freebsd.org>; Tue, 4 Jun 1996 19:20:30 -0500 (CDT) Received: (from peter@localhost) by bonkers.taronga.com (8.6.11/8.6.9) id TAA18778; Tue, 4 Jun 1996 19:20:27 -0500 Date: Tue, 4 Jun 1996 19:20:27 -0500 From: peter@taronga.com (Peter da Silva) Message-Id: <199606050020.TAA18778@bonkers.taronga.com> To: doc@freebsd.org Subject: Re: How do I write this SGML stuff? Newsgroups: taronga.freebsd.doc In-Reply-To: <199606042153.VAA10567@gatekeeper.fsl.noaa.gov> References: <Pine.NEB.3.93.960604153720.422P-100000@Fieber-John.campusview.indiana.edu> Organization: none Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk In article <199606042153.VAA10567@gatekeeper.fsl.noaa.gov> you write: >Given that we already can go to LaTeX which can go to professionally >typeset documents, why do we need to also go to troff which can go to >professionally typeset documents? Because TeX is soggy and hard to light, producing huge amounts of gibberish output in which real error messages (which are likely bogus anyway) are almost impossible to find. Because some people *prefer* the output of troff/groff. Because Computer Modern doesn't look very nice on 300 dpi and lower devices and TeX doesn't get along well with Adobe fonts. (I admire TeX, but I prefer to do so from a distance) From owner-freebsd-doc Tue Jun 4 18:26:31 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id SAA29806 for doc-outgoing; Tue, 4 Jun 1996 18:26:31 -0700 (PDT) Received: from gatekeeper.fsl.noaa.gov (gatekeeper.fsl.noaa.gov [137.75.131.181]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id SAA29800 for <doc@freebsd.org>; Tue, 4 Jun 1996 18:26:29 -0700 (PDT) Received: from emu.fsl.noaa.gov (kelly@emu.fsl.noaa.gov [137.75.60.32]) by gatekeeper.fsl.noaa.gov (8.7.5/8.7.3) with ESMTP id BAA11608; Wed, 5 Jun 1996 01:26:27 GMT Message-Id: <199606050126.BAA11608@gatekeeper.fsl.noaa.gov> Received: by emu.fsl.noaa.gov (1.40.112.3/16.2) id AA025027986; Tue, 4 Jun 1996 19:26:27 -0600 Date: Tue, 4 Jun 1996 19:26:27 -0600 From: Sean Kelly <kelly@fsl.noaa.gov> To: peter@taronga.com Cc: doc@freebsd.org In-Reply-To: <199606050020.TAA18778@bonkers.taronga.com> (peter@taronga.com) Subject: Re: How do I write this SGML stuff? Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk >>>>> "Peter" == Peter da Silva <peter@taronga.com> writes: Peter> In article <199606042153.VAA10567@gatekeeper.fsl.noaa.gov> Peter> you write: >> Given that we already can go to LaTeX which can go to >> professionally typeset documents, why do we need to also go to >> troff which can go to professionally typeset documents? Peter> Because TeX is soggy and hard to light, and troff doesn't stay crispy in milk. The score: 0 to 0. Peter> producing huge amounts of gibberish output in which real Peter> error messages (which are likely bogus anyway) are almost Peter> impossible to find. Absolutely right. troff wins a point. Peter> Because some people *prefer* the output of Peter> troff/groff. And some people prefer the output of TeX. Score unchanged. Peter> Because Computer Modern doesn't look very nice Peter> on 300 dpi and lower devices Another judgement call. 11 point CM roman works quite well for me at 300 dpi whereas Adobe Times Roman at the same size doesn't. So, score remains unchanged. Peter> and TeX doesn't get along well with Adobe fonts. I've run TeX with Adobe fonts for a number of years. While it was painful in the beginning, such is not the case today. Since troff was around before Adobe fonts were, I'm sure it suffered some ups & downs as well. So the final score is troff 1, TeX 0. But it still doesn't answer the question. If the DTD and the replacement rules are up to snuff, it doesn't matter whether we go to TeX, troff, Scribe, or who knows what. The end result is a nicely typeset document, and the LaTeX results seemed adequate. I don't see why supporting an additonal output format that has similar end results is necessary. So, I asked why. :-) -- Sean Kelly NOAA Forecast Systems Laboratory kelly@fsl.noaa.gov Boulder Colorado USA http://www-sdd.fsl.noaa.gov/~kelly/ From owner-freebsd-doc Tue Jun 4 18:40:27 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id SAA00740 for doc-outgoing; Tue, 4 Jun 1996 18:40:27 -0700 (PDT) Received: from distortion.eng.umd.edu (distortion.eng.umd.edu [129.2.98.6]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id SAA00735 for <FreeBSD-doc@FreeBSD.org>; Tue, 4 Jun 1996 18:40:25 -0700 (PDT) Received: from ginger.eng.umd.edu (ginger.eng.umd.edu [129.2.98.204]) by distortion.eng.umd.edu (8.7.5/8.7.3) with ESMTP id VAA12781 for <FreeBSD-doc@FreeBSD.org>; Tue, 4 Jun 1996 21:40:23 -0400 (EDT) Received: (from chuckr@localhost) by ginger.eng.umd.edu (8.7.5/8.7.3) id VAA01099; Tue, 4 Jun 1996 21:40:23 -0400 (EDT) Date: Tue, 4 Jun 1996 21:40:23 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@ginger.eng.umd.edu To: FreeBSD-doc@FreeBSD.org Subject: Linuxdoc Message-ID: <Pine.OSF.3.91.960604212648.26610G-100000@ginger.eng.umd.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk I sent this to John Fieber, then I realized I should have let the list in on it. I was noting that the idea of making an intermediate language like linuxdoc is a good one, the only bad part (for me) is the specific choice of linuxdoc. The reasons that I can't use it are (1) I've never been able to undersatnd sgml all that well, and (2) linuxdoc seems to be undocumented. I'm pretty sure it wouldn't be all that hard for me to do up a macro package using groff to do all the stuff we've used linuxdoc for. I think it might be doable in TeX eve better (tho I don't persoanlly understand TeX as well as I do troff code). I think TeX would be a good choice because it has a wider user base than groff, and is somewhat more modern. I think the TeX/LaTeX distribution in /usr/ports/print/teTeX is a great starting point, if largeish. I think groff would be a better choice because I already know it and I'm lazy. It could produce the ascii version pretty directly, and just use the groff tool we already have. I'd be happy to accept linuxdoc, if it were just well-documented, like groff and TeX. I can buy books on either TeX or groff. The sheer generality of sgml has always defeated me. When I get confused by something in groff, I break it up into pieces that at least have definitions. The pieces of sgml basically don't have any base, concrete definitions. Are there any other possibilities for discussion? ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- From owner-freebsd-doc Tue Jun 4 18:47:10 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id SAA01043 for doc-outgoing; Tue, 4 Jun 1996 18:47:10 -0700 (PDT) Received: from time.cdrom.com (time.cdrom.com [204.216.27.226]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id SAA01038 for <doc@freebsd.org>; Tue, 4 Jun 1996 18:47:08 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by time.cdrom.com (8.7.5/8.6.9) with SMTP id SAA06881; Tue, 4 Jun 1996 18:44:54 -0700 (PDT) To: Chuck Robey <chuckr@Glue.umd.edu> cc: Sean Kelly <kelly@fsl.noaa.gov>, jfieber@indiana.edu, grog@lemis.de, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-reply-to: Your message of "Tue, 04 Jun 1996 18:43:52 EDT." <Pine.OSF.3.91.960604184209.26610D-100000@ginger.eng.umd.edu> Date: Tue, 04 Jun 1996 18:44:54 -0700 Message-ID: <6879.833939094@time.cdrom.com> From: "Jordan K. Hubbard" <jkh@time.cdrom.com> Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk > If you guys would adopt any system for producing docs that's documented > enough so I could actually use it, I'd be real happy. Tossing linuxdoc > would make my day. Ain't gonna happen though - too much invested in it for a wholesale replacement, unless you're volunteering to rewrite the handbook and FAQ documents from scratch in a comfortably finite period of time.. :-) I have to wonder why you can handle troff (yuck!) and not SGML though. It's not as if the markup languages are THAT arcane, and if you've learned one you should be able to learn the other (the rest of us did, and we had nothing more to go on than the examples :-). Jordan From owner-freebsd-doc Tue Jun 4 19:02:10 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id TAA02193 for doc-outgoing; Tue, 4 Jun 1996 19:02:10 -0700 (PDT) Received: from time.cdrom.com (time.cdrom.com [204.216.27.226]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id TAA02184 for <FreeBSD-doc@FreeBSD.org>; Tue, 4 Jun 1996 19:02:04 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by time.cdrom.com (8.7.5/8.6.9) with SMTP id SAA07008; Tue, 4 Jun 1996 18:58:27 -0700 (PDT) To: Chuck Robey <chuckr@Glue.umd.edu> cc: FreeBSD-doc@FreeBSD.org Subject: Re: Linuxdoc In-reply-to: Your message of "Tue, 04 Jun 1996 21:40:23 EDT." <Pine.OSF.3.91.960604212648.26610G-100000@ginger.eng.umd.edu> Date: Tue, 04 Jun 1996 18:58:27 -0700 Message-ID: <7005.833939907@time.cdrom.com> From: "Jordan K. Hubbard" <jkh@time.cdrom.com> Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk > I sent this to John Fieber, then I realized I should have let the list in > on it. I was noting that the idea of making an intermediate language > like linuxdoc is a good one, the only bad part (for me) is the specific > choice of linuxdoc. The reasons that I can't use it are (1) I've never > been able to undersatnd sgml all that well, and (2) linuxdoc seems to be > undocumented. My understanding is that linuxdoc is just a DTD, and poorly documented or not only one part of our SGML environment. The choice of SGML itself seems to be a non-issue. Everyone from Sun to HP to DEC (I live with a tech writer who's a docs project manager for Sun and worked everywhere else before that) is moving to SGML and some DTD, O'Reilly and associates has all of its authors writing in SGML using their own DTD (which they'll provide to anyone for free, BTW) and the world in general is just moving away from groff and TeX. So we're on the right train, let's not let the color of the upholstery motivate us into switching back to the more familiar yet outmoded horse and buggy. :-) Jordan From owner-freebsd-doc Tue Jun 4 19:06:48 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id TAA02591 for doc-outgoing; Tue, 4 Jun 1996 19:06:48 -0700 (PDT) Received: from distortion.eng.umd.edu (distortion.eng.umd.edu [129.2.98.6]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id TAA02585 for <doc@freebsd.org>; Tue, 4 Jun 1996 19:06:44 -0700 (PDT) Received: from ginger.eng.umd.edu (ginger.eng.umd.edu [129.2.98.204]) by distortion.eng.umd.edu (8.7.5/8.7.3) with ESMTP id WAA13283; Tue, 4 Jun 1996 22:06:39 -0400 (EDT) Received: (from chuckr@localhost) by ginger.eng.umd.edu (8.7.5/8.7.3) id WAA01461; Tue, 4 Jun 1996 22:06:38 -0400 (EDT) Date: Tue, 4 Jun 1996 22:06:37 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@ginger.eng.umd.edu To: "Jordan K. Hubbard" <jkh@time.cdrom.com> cc: Sean Kelly <kelly@fsl.noaa.gov>, jfieber@indiana.edu, grog@lemis.de, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <6879.833939094@time.cdrom.com> Message-ID: <Pine.OSF.3.91.960604220308.26610I-100000@ginger.eng.umd.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, Jordan K. Hubbard wrote: > > If you guys would adopt any system for producing docs that's documented > > enough so I could actually use it, I'd be real happy. Tossing linuxdoc > > would make my day. > > Ain't gonna happen though - too much invested in it for a wholesale replacement, unless you're volunteering to rewrite the handbook and FAQ documents from > scratch in a comfortably finite period of time.. :-) > > I have to wonder why you can handle troff (yuck!) and not SGML > though. It's not as if the markup languages are THAT arcane, and if > you've learned one you should be able to learn the other (the rest of > us did, and we had nothing more to go on than the examples :-). I need examples of stuff. Show me an example of a table. I could do that trivially in either troff or LaTeX, but I can't find any in the handbook, and there's no explanation anywhere I can find. I could even turn on underlining, only one kind of emphasis. The idea of having to go thru thousands of lines looking for one example, it makes it too hard to figure out. I did do a doc, and it got me even more frustrated. ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- From owner-freebsd-doc Tue Jun 4 19:12:44 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id TAA03023 for doc-outgoing; Tue, 4 Jun 1996 19:12:44 -0700 (PDT) Received: from jolt.eng.umd.edu (jolt.eng.umd.edu [129.2.102.5]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id TAA03017 for <FreeBSD-doc@FreeBSD.org>; Tue, 4 Jun 1996 19:12:37 -0700 (PDT) Received: from ginger.eng.umd.edu (ginger.eng.umd.edu [129.2.98.204]) by jolt.eng.umd.edu (8.7.5/8.7.3) with ESMTP id WAA00812; Tue, 4 Jun 1996 22:12:35 -0400 (EDT) Received: (from chuckr@localhost) by ginger.eng.umd.edu (8.7.5/8.7.3) id WAA01584; Tue, 4 Jun 1996 22:12:34 -0400 (EDT) Date: Tue, 4 Jun 1996 22:12:33 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@ginger.eng.umd.edu To: "Jordan K. Hubbard" <jkh@time.cdrom.com> cc: FreeBSD-doc@FreeBSD.org Subject: Re: Linuxdoc In-Reply-To: <7005.833939907@time.cdrom.com> Message-ID: <Pine.OSF.3.91.960604220813.26610J-100000@ginger.eng.umd.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, Jordan K. Hubbard wrote: > > I sent this to John Fieber, then I realized I should have let the list in > > on it. I was noting that the idea of making an intermediate language > > like linuxdoc is a good one, the only bad part (for me) is the specific > > choice of linuxdoc. The reasons that I can't use it are (1) I've never > > been able to undersatnd sgml all that well, and (2) linuxdoc seems to be > > undocumented. > > My understanding is that linuxdoc is just a DTD, and poorly documented or > not only one part of our SGML environment. > > The choice of SGML itself seems to be a non-issue. Everyone from Sun > to HP to DEC (I live with a tech writer who's a docs project manager > for Sun and worked everywhere else before that) is moving to SGML and > some DTD, O'Reilly and associates has all of its authors writing in SGML > using their own DTD (which they'll provide to anyone for free, BTW) > and the world in general is just moving away from groff and TeX. > > So we're on the right train, let's not let the color of the upholstery > motivate us into switching back to the more familiar yet outmoded > horse and buggy. :-) If Someone who understands sgml would go to the trouble of providing examples of how all the parts of the dtd we use should be used in a document, I would be happy to go and make the changes in the troff substitution code to make the groff output look like it was supposed to. As it stands now, I can't do it, because I don't understand what the sgml sequences that are supposed to drive our code look like. I don't care if we leave sgml or not, I'd like to leave an undocumented system. ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- From owner-freebsd-doc Tue Jun 4 19:13:48 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id TAA03074 for doc-outgoing; Tue, 4 Jun 1996 19:13:48 -0700 (PDT) Received: from time.cdrom.com (time.cdrom.com [204.216.27.226]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id TAA03066 for <doc@freebsd.org>; Tue, 4 Jun 1996 19:13:42 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by time.cdrom.com (8.7.5/8.6.9) with SMTP id TAA07086; Tue, 4 Jun 1996 19:11:32 -0700 (PDT) To: Chuck Robey <chuckr@Glue.umd.edu> cc: Sean Kelly <kelly@fsl.noaa.gov>, jfieber@indiana.edu, grog@lemis.de, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-reply-to: Your message of "Tue, 04 Jun 1996 22:06:37 EDT." <Pine.OSF.3.91.960604220308.26610I-100000@ginger.eng.umd.edu> Date: Tue, 04 Jun 1996 19:11:32 -0700 Message-ID: <7083.833940692@time.cdrom.com> From: "Jordan K. Hubbard" <jkh@time.cdrom.com> Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk > I need examples of stuff. Show me an example of a table. I could do > that trivially in either troff or LaTeX, but I can't find any in the It's all there in the current body of stuff. No, there are no tables because we don't USE tables. Be sure to keep seperate your needs for whatever documentation system you use in your own work (in which case you're free to use anything from nroff to LaTeX and the whole point is somewhat moot) and the needs of the project, in which you don't NEED no steenkin' table examples! :-) Jordan From owner-freebsd-doc Tue Jun 4 19:16:35 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id TAA03193 for doc-outgoing; Tue, 4 Jun 1996 19:16:35 -0700 (PDT) Received: from distortion.eng.umd.edu (distortion.eng.umd.edu [129.2.98.6]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id TAA03186 for <doc@freebsd.org>; Tue, 4 Jun 1996 19:16:31 -0700 (PDT) Received: from ginger.eng.umd.edu (ginger.eng.umd.edu [129.2.98.204]) by distortion.eng.umd.edu (8.7.5/8.7.3) with ESMTP id WAA13493; Tue, 4 Jun 1996 22:16:20 -0400 (EDT) Received: (from chuckr@localhost) by ginger.eng.umd.edu (8.7.5/8.7.3) id WAA01956; Tue, 4 Jun 1996 22:16:19 -0400 (EDT) Date: Tue, 4 Jun 1996 22:16:19 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@ginger.eng.umd.edu To: "Jordan K. Hubbard" <jkh@time.cdrom.com> cc: Sean Kelly <kelly@fsl.noaa.gov>, jfieber@indiana.edu, grog@lemis.de, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <7083.833940692@time.cdrom.com> Message-ID: <Pine.OSF.3.91.960604221359.26610L-100000@ginger.eng.umd.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, Jordan K. Hubbard wrote: > > I need examples of stuff. Show me an example of a table. I could do > > that trivially in either troff or LaTeX, but I can't find any in the > > It's all there in the current body of stuff. No, there are no tables > because we don't USE tables. Be sure to keep seperate your needs for > whatever documentation system you use in your own work (in which case > you're free to use anything from nroff to LaTeX and the whole point is > somewhat moot) and the needs of the project, in which you don't NEED > no steenkin' table examples! :-) They're in linuxdoc, they're just undocumented. I know how to do them in troff and LaTeX, and our man pages have them. Our handbook is full of them, Jordan, but they're all done but suspending the formatting, because no one can figure out how to do it right. That's not the only example. ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- From owner-freebsd-doc Tue Jun 4 19:20:09 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id TAA03410 for doc-outgoing; Tue, 4 Jun 1996 19:20:09 -0700 (PDT) Received: from mailbox.neosoft.com (mailbox.neosoft.com [206.109.1.16]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id TAA03341 for <doc@freebsd.org>; Tue, 4 Jun 1996 19:19:55 -0700 (PDT) Received: from bonkers.taronga.com (root@bonkers.neosoft.com [206.109.2.48]) by mailbox.neosoft.com (8.7.5/8.7.3) with SMTP id VAA06438 for <doc@freebsd.org>; Tue, 4 Jun 1996 21:19:06 -0500 (CDT) Received: (from peter@localhost) by bonkers.taronga.com (8.6.11/8.6.9) id VAA20501; Tue, 4 Jun 1996 21:18:37 -0500 Date: Tue, 4 Jun 1996 21:18:37 -0500 From: peter@taronga.com (Peter da Silva) Message-Id: <199606050218.VAA20501@bonkers.taronga.com> To: doc@freebsd.org Subject: Re: How do I write this SGML stuff? Newsgroups: taronga.freebsd.doc In-Reply-To: <199606050126.BAA11608@gatekeeper.fsl.noaa.gov> References: <199606050020.TAA18778@bonkers.taronga.com> Organization: none Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk >But it still doesn't answer the question. If the DTD and the >replacement rules are up to snuff, it doesn't matter whether we go to >TeX, troff, Scribe, or who knows what. Sure it does. I need to install and maintain it locally, and even with packages and ports I don't want to have to keep a copy of TeX "live" just to generate documentation. TeX and I just don't get along... Plus troff code run through nroff looks pretty good. Much better than the straight "plain text" output of Linuxdoc. From owner-freebsd-doc Tue Jun 4 19:33:23 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id TAA05849 for doc-outgoing; Tue, 4 Jun 1996 19:33:23 -0700 (PDT) Received: from gatekeeper.fsl.noaa.gov (gatekeeper.fsl.noaa.gov [137.75.131.181]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id TAA05834 for <FreeBSD-doc@FreeBSD.org>; Tue, 4 Jun 1996 19:33:20 -0700 (PDT) Received: from emu.fsl.noaa.gov (kelly@emu.fsl.noaa.gov [137.75.60.32]) by gatekeeper.fsl.noaa.gov (8.7.5/8.7.3) with ESMTP id CAA11953; Wed, 5 Jun 1996 02:33:16 GMT Message-Id: <199606050233.CAA11953@gatekeeper.fsl.noaa.gov> Received: by emu.fsl.noaa.gov (1.40.112.3/16.2) id AA029021995; Tue, 4 Jun 1996 20:33:15 -0600 Date: Tue, 4 Jun 1996 20:33:15 -0600 From: Sean Kelly <kelly@fsl.noaa.gov> To: chuckr@Glue.umd.edu Cc: FreeBSD-doc@FreeBSD.org In-Reply-To: <Pine.OSF.3.91.960604212648.26610G-100000@ginger.eng.umd.edu> (message from Chuck Robey on Tue, 4 Jun 1996 21:40:23 -0400 (EDT)) Subject: Re: Linuxdoc Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk >>>>> "Chuck" == Chuck Robey <chuckr@Glue.umd.edu> writes: Chuck> The sheer generality of sgml has always defeated me. I agree. I can't believe that some documentation units will require SGML experience and then spend the next month or two training a new hire on the specifics of their own DTD. SGML is easy---it's just angle brackets. It's the specific DTDs that are hard! Chuck> Are there any other possibilities for discussion? How about WYSIWYG tools? Have we all set in our ``me too'' messages to that one company that produces an office suite that Jordan Hubbard announced several weeks ago? While I like being able to focus entirely on substance instead of on format with tools like TeX, *roff, and even SGML, the best document production package I ever used was Interleaf. Sure, it was WYSIWYG, but it had the best thought out document structuring system I've ever used. The user interface blew all the others away. I spend all of my time mousing around with FrameMaker, but Interleaf's context sensitive popup menus with intelligent defaults were quite a joy and a heck of a lot easier on the wrist. It had superb revision control and document locking for large projects. And for special requirements for certain projects, we'd just write some custom Interleaf Lisp to do the job---yes, it's the Emacs of desktop publishing. But, it seems like they're going out of business---if they haven't already. Okay, back to the topic: other possibilities. Interleaf's an impossibility, but I don't know of any other freely available (or not) tools besides TeX, groff, and our good ol' linuxdoc. And of those, some kind of SGML-based tool still seems like a good choice if it at least means that most the groffers and the TeXies will be on common footing---plus we could have an automatic conversion of our source documents from linuxdoc to whatever its successor might be. And to be honest, it's not all that hard to use linuxdoc or another DTD especially if there are good instructions available. The fellow who made linuxdoc had some instructions on how to use it that weren't too bad. And the Emacs SGML helper mode certainly does work well in reminding you what's legal at a certain point and what's not. After awhile, it becomes second nature. Even reading the DTD specification files starts to make sense! :-) -- Sean Kelly NOAA Forecast Systems Laboratory kelly@fsl.noaa.gov Boulder Colorado USA http://www-sdd.fsl.noaa.gov/~kelly/ From owner-freebsd-doc Tue Jun 4 19:35:30 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id TAA06244 for doc-outgoing; Tue, 4 Jun 1996 19:35:30 -0700 (PDT) Received: from gatekeeper.fsl.noaa.gov (gatekeeper.fsl.noaa.gov [137.75.131.181]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id TAA06224 for <doc@freebsd.org>; Tue, 4 Jun 1996 19:35:25 -0700 (PDT) Received: from emu.fsl.noaa.gov (kelly@emu.fsl.noaa.gov [137.75.60.32]) by gatekeeper.fsl.noaa.gov (8.7.5/8.7.3) with ESMTP id CAA11958; Wed, 5 Jun 1996 02:35:17 GMT Message-Id: <199606050235.CAA11958@gatekeeper.fsl.noaa.gov> Received: by emu.fsl.noaa.gov (1.40.112.3/16.2) id AA029092117; Tue, 4 Jun 1996 20:35:17 -0600 Date: Tue, 4 Jun 1996 20:35:17 -0600 From: Sean Kelly <kelly@fsl.noaa.gov> To: jkh@time.cdrom.com Cc: chuckr@Glue.umd.edu, jfieber@indiana.edu, grog@lemis.de, doc@freebsd.org In-Reply-To: <7083.833940692@time.cdrom.com> (jkh@time.cdrom.com) Subject: Re: How do I write this SGML stuff? Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk >>>>> "Jordan" == "Jordan K Hubbard" <jkh@time.cdrom.com> writes: Jordan> and the needs of the project, in which you Jordan> don't NEED no steenkin' table examples! :-) But boy they'd sure be nice to have. ;-) -- Sean Kelly NOAA Forecast Systems Laboratory kelly@fsl.noaa.gov Boulder Colorado USA http://www-sdd.fsl.noaa.gov/~kelly/ From owner-freebsd-doc Tue Jun 4 19:38:14 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id TAA07242 for doc-outgoing; Tue, 4 Jun 1996 19:38:14 -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 TAA07220 for <doc@freebsd.org>; Tue, 4 Jun 1996 19:38:10 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id VAA10065; Tue, 4 Jun 1996 21:35:59 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Tue, 4 Jun 1996 21:35:58 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Chuck Robey <chuckr@Glue.umd.edu> cc: "Jordan K. Hubbard" <jkh@time.cdrom.com>, Sean Kelly <kelly@fsl.noaa.gov>, grog@lemis.de, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <Pine.OSF.3.91.960604221359.26610L-100000@ginger.eng.umd.edu> Message-ID: <Pine.NEB.3.93.960604212245.422R-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, Chuck Robey wrote: > They're in linuxdoc, they're just undocumented. I know how to do them in > troff and LaTeX, and our man pages have them. Our handbook is full of > them, Jordan, but they're all done but suspending the formatting, because > no one can figure out how to do it right. That's not the only example. No, the primary reason they are not done is that lynx does not handle them and browsing the handbook with more is rather less than ideal. Also, tables don't come out in the in the HTML anyway, although when I get a spare moment, I'll change that. The moment linux supports tables, we can launch an all out assault on the stuff in the handbook that needs it (and there is plenty!). So, without further delay, behold a table! <table> <tabular ca="ccc"> Column 1<colsep>Column 2<colsep>Column 3<rowsep> Column 1<colsep>Column 2<colsep>Column 3<rowsep> </tabular> <caption>This is the caption</caption> </table> This works for ascii and LaTeX output. The ca attribute is what you specify for your column formats in LaTeX, which is apparently pretty similar to what us use for in the troff world since the results are the same. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Tue Jun 4 19:48:04 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id TAA11562 for doc-outgoing; Tue, 4 Jun 1996 19:48:04 -0700 (PDT) Received: from distortion.eng.umd.edu (distortion.eng.umd.edu [129.2.98.6]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id TAA11527 for <doc@freebsd.org>; Tue, 4 Jun 1996 19:48:01 -0700 (PDT) Received: from ginger.eng.umd.edu (ginger.eng.umd.edu [129.2.98.204]) by distortion.eng.umd.edu (8.7.5/8.7.3) with ESMTP id WAA13980; Tue, 4 Jun 1996 22:47:52 -0400 (EDT) Received: (from chuckr@localhost) by ginger.eng.umd.edu (8.7.5/8.7.3) id WAA32443; Tue, 4 Jun 1996 22:47:51 -0400 (EDT) Date: Tue, 4 Jun 1996 22:47:51 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@ginger.eng.umd.edu To: John Fieber <jfieber@indiana.edu> cc: "Jordan K. Hubbard" <jkh@time.cdrom.com>, Sean Kelly <kelly@fsl.noaa.gov>, grog@lemis.de, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <Pine.NEB.3.93.960604212245.422R-100000@Fieber-John.campusview.indiana.edu> Message-ID: <Pine.OSF.3.91.960604224229.26610N-100000@ginger.eng.umd.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, John Fieber wrote: > On Tue, 4 Jun 1996, Chuck Robey wrote: > > > They're in linuxdoc, they're just undocumented. I know how to do them in > > troff and LaTeX, and our man pages have them. Our handbook is full of > > them, Jordan, but they're all done but suspending the formatting, because > > no one can figure out how to do it right. That's not the only example. > > No, the primary reason they are not done is that lynx does not > handle them and browsing the handbook with more is rather less > than ideal. Also, tables don't come out in the in the HTML > anyway, although when I get a spare moment, I'll change that. > The moment linux supports tables, we can launch an all out > assault on the stuff in the handbook that needs it (and there is > plenty!). > > So, without further delay, behold a table! > > <table> > <tabular ca="ccc"> > Column 1<colsep>Column 2<colsep>Column 3<rowsep> > Column 1<colsep>Column 2<colsep>Column 3<rowsep> > </tabular> > <caption>This is the caption</caption> > </table> OK. if "ccc" means what I think it does, column 1 centered, column 2 centered, and column 3 centered, this is great. There should be others, like l, r (obvious), s (continue column), and n(decimal). Let me look at the linuxdoc stuff, see how this works (or doesn't). If it's broke in troff mode, I'll fix it. If I fix this, will you document it? > > This works for ascii and LaTeX output. The ca attribute is what > you specify for your column formats in LaTeX, which is apparently > pretty similar to what us use for in the troff world since the > results are the same. > > -john > > == jfieber@indiana.edu =========================================== > == http://fallout.campusview.indiana.edu/~jfieber ================ > > ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- From owner-freebsd-doc Tue Jun 4 19:48:07 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id TAA11584 for doc-outgoing; Tue, 4 Jun 1996 19:48:07 -0700 (PDT) Received: from gatekeeper.fsl.noaa.gov (gatekeeper.fsl.noaa.gov [137.75.131.181]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id TAA11560 for <doc@FreeBSD.org>; Tue, 4 Jun 1996 19:48:04 -0700 (PDT) Received: from emu.fsl.noaa.gov (kelly@emu.fsl.noaa.gov [137.75.60.32]) by gatekeeper.fsl.noaa.gov (8.7.5/8.7.3) with ESMTP id CAA12002; Wed, 5 Jun 1996 02:47:51 GMT Message-Id: <199606050247.CAA12002@gatekeeper.fsl.noaa.gov> Received: by emu.fsl.noaa.gov (1.40.112.3/16.2) id AA029322871; Tue, 4 Jun 1996 20:47:51 -0600 Date: Tue, 4 Jun 1996 20:47:51 -0600 From: Sean Kelly <kelly@fsl.noaa.gov> To: peter@taronga.com Cc: doc@FreeBSD.org In-Reply-To: <199606050218.VAA20501@bonkers.taronga.com> (peter@taronga.com) Subject: Re: How do I write this SGML stuff? Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk >>>>> "Peter" == Peter da Silva <peter@taronga.com> writes: Peter> Sure it does. I need to install and maintain it locally, And groff comes installed as part of /usr/bin. Good point. Okay, I'm sold! -- Sean Kelly NOAA Forecast Systems Laboratory kelly@fsl.noaa.gov Boulder Colorado USA http://www-sdd.fsl.noaa.gov/~kelly/ From owner-freebsd-doc Tue Jun 4 20:24:26 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id UAA18288 for doc-outgoing; Tue, 4 Jun 1996 20:24:26 -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 UAA18281 for <doc@FreeBSD.org>; Tue, 4 Jun 1996 20:24:19 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id WAA10227; Tue, 4 Jun 1996 22:24:11 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Tue, 4 Jun 1996 22:24:10 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Sean Kelly <kelly@fsl.noaa.gov> cc: peter@taronga.com, doc@FreeBSD.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <199606050126.BAA11608@gatekeeper.fsl.noaa.gov> Message-ID: <Pine.NEB.3.93.960604221234.422X-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, Sean Kelly wrote: > Another judgement call. 11 point CM roman works quite well for me at > 300 dpi whereas Adobe Times Roman at the same size doesn't. So, score > remains unchanged. Well, I think both times and CM are ugly, and BTW, how can I make groff use New Century Schoolbook? (Yes, LaTeX uses it just fine) Anyway, in the context of an sgml based document processing system, troff or TeX plays the role of as(1) in a C based programming environment. Its there, its plays a critical role but you rarely ever encounter it directly. If I had to choose between troff or TeX for direct use, I would take TeX without a second thought. But freebsd docs, I think troff is a much better choice because (a) its standard equipment (b) is much easier to hide behind a shell script and (c) can actually generate decent ascii output. The *only* reason sgmlfmt generates LaTeX right now is that the [nt]roff output is hopelessly brain dammaged and I confess I don't know enough to fix it. Unfortunately those who do don't know enough SGML to do it either. :( -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Tue Jun 4 20:33:09 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id UAA18792 for doc-outgoing; Tue, 4 Jun 1996 20:33:09 -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 UAA18781 for <doc@freebsd.org>; Tue, 4 Jun 1996 20:33:05 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id WAA10270; Tue, 4 Jun 1996 22:32:21 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Tue, 4 Jun 1996 22:32:19 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Chuck Robey <chuckr@Glue.umd.edu> cc: "Jordan K. Hubbard" <jkh@time.cdrom.com>, Sean Kelly <kelly@fsl.noaa.gov>, grog@lemis.de, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <Pine.OSF.3.91.960604224229.26610N-100000@ginger.eng.umd.edu> Message-ID: <Pine.NEB.3.93.960604222544.422Y-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, Chuck Robey wrote: > OK. if "ccc" means what I think it does, column 1 centered, column 2 > centered, and column 3 centered, this is great. There should be others, > like l, r (obvious), s (continue column), and n(decimal). Let me look at > the linuxdoc stuff, see how this works (or doesn't). If it's broke in > troff mode, I'll fix it. c = center l = left align r = right align | = a vertical line (between columns) I'm not sure what the semantics of s are, but n doesn't appear to be directly supported in LaTeX's tabular enivornment, although this may have changed in LaTeX2e. My TeX is is a little rusty. Without some tweaks to sgmlfmt, we are limited to the intersection of the troff and LaTeX table formats. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Tue Jun 4 20:40:51 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id UAA19498 for doc-outgoing; Tue, 4 Jun 1996 20:40:51 -0700 (PDT) Received: from jolt.eng.umd.edu (jolt.eng.umd.edu [129.2.102.5]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id UAA19486 for <doc@freebsd.org>; Tue, 4 Jun 1996 20:40:48 -0700 (PDT) Received: from ginger.eng.umd.edu (ginger.eng.umd.edu [129.2.98.204]) by jolt.eng.umd.edu (8.7.5/8.7.3) with ESMTP id XAA01780; Tue, 4 Jun 1996 23:40:34 -0400 (EDT) Received: (from chuckr@localhost) by ginger.eng.umd.edu (8.7.5/8.7.3) id XAA02715; Tue, 4 Jun 1996 23:40:33 -0400 (EDT) Date: Tue, 4 Jun 1996 23:40:33 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@ginger.eng.umd.edu To: John Fieber <jfieber@indiana.edu> cc: "Jordan K. Hubbard" <jkh@time.cdrom.com>, Sean Kelly <kelly@fsl.noaa.gov>, grog@lemis.de, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <Pine.NEB.3.93.960604222544.422Y-100000@Fieber-John.campusview.indiana.edu> Message-ID: <Pine.OSF.3.91.960604233731.26610Q-100000@ginger.eng.umd.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, John Fieber wrote: > On Tue, 4 Jun 1996, Chuck Robey wrote: > > > OK. if "ccc" means what I think it does, column 1 centered, column 2 > > centered, and column 3 centered, this is great. There should be others, > > like l, r (obvious), s (continue column), and n(decimal). Let me look at > > the linuxdoc stuff, see how this works (or doesn't). If it's broke in > > troff mode, I'll fix it. > > c = center > l = left align > r = right align > | = a vertical line (between columns) > > I'm not sure what the semantics of s are, but n doesn't appear to > be directly supported in LaTeX's tabular enivornment, although > this may have changed in LaTeX2e. My TeX is is a little rusty. S means span, make the column the s belongs to part of the previous column. I'm certain LaTeX2e covers it, but I just leant out my two LaTeX manuals. I can do it in troff, I need help just now in LaTeX2e. BTW, lets stick to LaTeX2e, not get older version stuff. It often does make a difference. Otherwise, you have to wait until I get my manuals back. Doing troff now. > > Without some tweaks to sgmlfmt, we are limited to the > intersection of the troff and LaTeX table formats. > > -john > > == jfieber@indiana.edu =========================================== > == http://fallout.campusview.indiana.edu/~jfieber ================ > > ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- From owner-freebsd-doc Tue Jun 4 20:58:10 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id UAA21767 for doc-outgoing; Tue, 4 Jun 1996 20:58:10 -0700 (PDT) Received: from distortion.eng.umd.edu (distortion.eng.umd.edu [129.2.98.6]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id UAA21756 for <doc@freebsd.org>; Tue, 4 Jun 1996 20:58:07 -0700 (PDT) Received: from ginger.eng.umd.edu (ginger.eng.umd.edu [129.2.98.204]) by distortion.eng.umd.edu (8.7.5/8.7.3) with ESMTP id XAA14764; Tue, 4 Jun 1996 23:57:59 -0400 (EDT) Received: (from chuckr@localhost) by ginger.eng.umd.edu (8.7.5/8.7.3) id XAA03337; Tue, 4 Jun 1996 23:57:58 -0400 (EDT) Date: Tue, 4 Jun 1996 23:57:58 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@ginger.eng.umd.edu To: John Fieber <jfieber@indiana.edu> cc: Sean Kelly <kelly@fsl.noaa.gov>, peter@taronga.com, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <Pine.NEB.3.93.960604221234.422X-100000@Fieber-John.campusview.indiana.edu> Message-ID: <Pine.OSF.3.91.960604235626.26610S-100000@ginger.eng.umd.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, John Fieber wrote: > On Tue, 4 Jun 1996, Sean Kelly wrote: > > > Another judgement call. 11 point CM roman works quite well for me at > > 300 dpi whereas Adobe Times Roman at the same size doesn't. So, score > > remains unchanged. > > Well, I think both times and CM are ugly, and BTW, how can I make > groff use New Century Schoolbook? (Yes, LaTeX uses it just fine) Use .fam N \" change font family to New Century Schoolbook Try looking in /usr/share/groff/groff_font for others. The first letter is the font family. > > Anyway, in the context of an sgml based document processing > system, troff or TeX plays the role of as(1) in a C based > programming environment. Its there, its plays a critical role > but you rarely ever encounter it directly. If I had to choose > between troff or TeX for direct use, I would take TeX without a > second thought. But freebsd docs, I think troff is a much better > choice because (a) its standard equipment (b) is much easier to > hide behind a shell script and (c) can actually generate decent > ascii output. > > The *only* reason sgmlfmt generates LaTeX right now is that the > [nt]roff output is hopelessly brain dammaged and I confess I > don't know enough to fix it. Unfortunately those who do don't > know enough SGML to do it either. :( > > -john > > == jfieber@indiana.edu =========================================== > == http://fallout.campusview.indiana.edu/~jfieber ================ > > ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- From owner-freebsd-doc Tue Jun 4 20:58:40 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id UAA21866 for doc-outgoing; Tue, 4 Jun 1996 20:58:40 -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 UAA21847 for <FreeBSD-doc@freebsd.org>; Tue, 4 Jun 1996 20:58:35 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id WAA10362; Tue, 4 Jun 1996 22:58:24 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Tue, 4 Jun 1996 22:58:24 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Sean Kelly <kelly@fsl.noaa.gov> cc: chuckr@Glue.umd.edu, FreeBSD-doc@freebsd.org Subject: Re: Linuxdoc In-Reply-To: <199606050233.CAA11953@gatekeeper.fsl.noaa.gov> Message-ID: <Pine.NEB.3.93.960604224345.422Z-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, Sean Kelly wrote: > While I like being able to focus entirely on substance instead of on > format with tools like TeX, *roff, and even SGML, the best document > production package I ever used was Interleaf. Sure, it was WYSIWYG, ^^^^^^^^^ ...Who was on the SGML bandwagon quite some time ago. > But, it seems like they're going out of business---if they haven't > already. Rumor has it that the spelling checker in Frame will suggest "Framemaker" if it finds the word "Interleaf" in your document... > And of those, some kind of SGML-based tool still seems like a good > choice if it at least means that most the groffers and the TeXies will The holy grail of SGML is to decouple documents from the tools. This is not just desirable, it is a basic requirement for document longevity and portability. SGML standardizes the parsing of data so that any parser on any platform can read any document and make its data easily available to your application. What you DO with it is up to you; most likely you will use some proprietary tool that works well at the time, for the task. When the comany that made that nifty proprietary tool gets put out of business by Mr. Gates, it won't take the data with it if it used SGML. I come from a library background where we *expect* materials to be just as accessible in 150 years as they are today. With digital data locked up in proprietary formats intimately tied to the software that created them, and the computer architecture on which that software ran, we already have data less than a decade old that is lost. SGML is a Good Thing, but we are still climbing the learning curve and the tools are pretty green. Things are getting better though. Rumor has it that the next release of WordPerfect will have their SGML extensions (which are actually pretty good) as standard equipment. Not that it will affect us directly, as the number of applications increase, so do the benefits of using SGML. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Wed Jun 5 03:17:24 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id DAA09380 for doc-outgoing; Wed, 5 Jun 1996 03:17:24 -0700 (PDT) Received: from epprod.elsevier.co.uk (epprod.elsevier.co.uk [193.131.222.35]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id DAA09351 for <doc@FreeBSD.org>; Wed, 5 Jun 1996 03:17:14 -0700 (PDT) Received: from snowdon.elsevier.co.uk (snowdon.elsevier.co.uk [193.131.197.164]) by epprod.elsevier.co.uk (8.6.13/8.6.12) with ESMTP id LAA04901 for <doc@FreeBSD.org>; Wed, 5 Jun 1996 11:15:58 +0100 Received: from tees by snowdon with SMTP (PP); Wed, 5 Jun 1996 11:16:05 +0100 Received: (from dpr@localhost) by tees (SMI-8.6/8.6.12) id LAA21049; Wed, 5 Jun 1996 11:15:36 +0100 Date: Wed, 5 Jun 1996 11:15:36 +0100 Message-Id: <199606051015.LAA21049@tees> To: John Fieber <jfieber@indiana.edu> Subject: Re: How do I write this SGML stuff? In-Reply-To: <Pine.NEB.3.93.960604152205.422O-100000@Fieber-John.campusview.indiana.edu> References: <199606041714.TAA13705@allegro.lemis.de> <Pine.NEB.3.93.960604152205.422O-100000@Fieber-John.campusview.indiana.edu> Reply-To: p.richards@elsevier.co.uk From: Paul Richards <p.richards@elsevier.co.uk> X-Attribution: Paul X-Mailer: GNU Emacs [19.30.1], RMAIL, Mailcrypt [3.3] CC: doc@FreeBSD.org Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk >>>>> "John" == John Fieber <jfieber@indiana.edu> writes: John> On Tue, 4 Jun 1996, Greg Lehey wrote: >> I've just been trying to convert my roff text on installing a >> second disk into SGML, and I find that I don't have any >> documentation. I've guessed a lot from the table sources, but I've >> probably made a lot of mistakes, and I can't find how to do >> pictures and tables. John> This is a bit of a dilemma. Currently the handbook is made John> readable by the lowest common denominator, which means lynx, John> which means no tables or graphics. Adding support for tables John> would be trivial. In fact, it should already work for LaTeX John> output, but I have not actually tried it. The (lame) workaround John> is ascii graphics in a <verb></verb> element. >> If there's no easy way to do that in SGML, is there a way to import >> PostScript? That would do just as easily. If somebody can point >> me to documentation on the subject, I'd be grateful. John> There is some documentation in /usr/src/share/sgml/FreeBSD/doc. John> It needs to be changed to reflect how things really are, but it John> should give you the basics. Just ignore all the stuff on the John> mechanics of making the conversions. Umm, this isn't really in the spirit of SGML. You shouldn't worry *AT ALL* about the output format, that's the whole point. If you want to mark the objects of your documents in some sensible way then you should just do so. There's no problem with tables or images or anything else you might want (I'm working in publishing at the moment, SGML conversion is what I have to battle with every day amongst other things and we publish technical journals so math, tables, images and all sorts of weird characters are the norm). Just create a DTD that has all the elements that we might need in our documentation and then worry about the output formats *after*. It's not that difficult to develop suitable mappings for any tags you might decide to use. LaTeX is particularly easy to cope with, groff is failry easy and html kind of varies depending on what browsers you plan to support. Incidentally, using LateX like centering instructions isn't in the spirit of SGML either since their layout instructions, the true SGML way would be to define elements such as <TABLEHEADING>, <CURRENCY> and so forth and then decide in your mapping whether they should be centered or not, you need to be a bit of a SGML pedant though to do this properly :-) >From another mail I noticed that HTML doesn't show images, it shouldn't be very hard to change the mapping to make them links or even to include them inline. Lynx should just ignore them. From owner-freebsd-doc Wed Jun 5 04:20:35 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id EAA15433 for doc-outgoing; Wed, 5 Jun 1996 04:20:35 -0700 (PDT) Received: from uu.elvisti.kiev.ua ([193.125.28.132]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id EAA15310 for <doc@freebsd.org>; Wed, 5 Jun 1996 04:19:47 -0700 (PDT) Received: from office.elvisti.kiev.ua (office.elvisti.kiev.ua [193.125.28.129]) by uu.elvisti.kiev.ua (8.7.5/8.7.3) with ESMTP id OAA08113; Wed, 5 Jun 1996 14:23:05 +0300 (EET DST) Received: (from stesin@localhost) by office.elvisti.kiev.ua (8.6.12/8.ElVisti) id OAA01953; Wed, 5 Jun 1996 14:22:57 +0300 From: "Andrew V. Stesin" <stesin@elvisti.kiev.ua> Message-Id: <199606051122.OAA01953@office.elvisti.kiev.ua> Subject: Re: How do I write this SGML stuff? To: jfieber@indiana.edu Date: Wed, 5 Jun 1996 14:22:55 +0300 (EET DST) Cc: grog@lemis.de, doc@freebsd.org In-Reply-To: <Pine.NEB.3.93.960604152205.422O-100000@Fieber-John.campusview.indiana.edu> from "John Fieber" at Jun 4, 96 03:36:49 pm X-Mailer: ELM [version 2.4 PL24alpha5] Content-Type: text Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk Hi, # This is a bit of a dilemma. Currently the handbook is made # readable by the lowest common denominator, which means lynx, # which means no tables ^^^^^^^^^ New Lynx (2.5 or later) which is in the ports handles tables pretty well. -- With best regards -- Andrew Stesin. +380 (44) 2760188 +380 (44) 2713457 +380 (44) 2713560 "You may delegate authority, but not responsibility." Frank's Management Rule #1. From owner-freebsd-doc Wed Jun 5 04:49:19 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id EAA18491 for doc-outgoing; Wed, 5 Jun 1996 04:49:19 -0700 (PDT) Received: from mailbox.neosoft.com (mailbox.neosoft.com [206.109.1.16]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id EAA18486 for <doc@freebsd.org>; Wed, 5 Jun 1996 04:49:16 -0700 (PDT) Received: from bonkers.taronga.com (bonkers.neosoft.com [206.109.2.48]) by mailbox.neosoft.com (8.7.5/8.7.3) with SMTP id GAA03515 for <doc@freebsd.org>; Wed, 5 Jun 1996 06:48:03 -0500 (CDT) Received: (from peter@localhost) by bonkers.taronga.com (8.6.11/8.6.9) id GAA04621; Wed, 5 Jun 1996 06:46:52 -0500 Date: Wed, 5 Jun 1996 06:46:52 -0500 From: peter@taronga.com (Peter da Silva) Message-Id: <199606051146.GAA04621@bonkers.taronga.com> To: doc@freebsd.org Subject: Re: Linuxdoc Newsgroups: taronga.freebsd.doc In-Reply-To: <199606050233.CAA11953@gatekeeper.fsl.noaa.gov> References: <Pine.OSF.3.91.960604212648.26610G-100000@ginger.eng.umd.edu> Organization: none Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk In article <199606050233.CAA11953@gatekeeper.fsl.noaa.gov>, Sean Kelly <kelly@fsl.noaa.gov> wrote: > Chuck> Are there any other possibilities for discussion? >How about WYSIWYG tools? Having spent an inordinate amount of time trying to deal with the sheer non-greppability of WYSIWYG file formats and the absolutely hideous output of the ones that claim to produce human-readable output (what Microsoft's Internet Assistant and Word Perfect's HTML generator do is better left undescribed), I recently came to the conclusion that what FreeBSD is currently using... warts and all... is better. If Interleaf's so fine and grand it's an exception to this rather depressing rule, and they're going out of business... perhaps there's an opportunity there. From owner-freebsd-doc Wed Jun 5 07:20:46 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id HAA03560 for doc-outgoing; Wed, 5 Jun 1996 07:20:46 -0700 (PDT) Received: from novell.com (prv-ums.Provo.Novell.COM [137.65.40.4]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id HAA03552 for <FreeBSD-doc@freebsd.org>; Wed, 5 Jun 1996 07:20:43 -0700 (PDT) Received: from INET-PRV-Message_Server by fromGW with Novell_GroupWise; Wed, 05 Jun 1996 08:20:52 -0600 Content-Type: text/plain Message-ID: <s1b54364.036@fromGW> X-Mailer: Novell GroupWise 4.1 Date: Wed, 05 Jun 1996 08:26:38 -0600 From: DARREND@novell.com (Darren Davis) To: chuckr@Glue.umd.edu, jkh@time.cdrom.com Cc: FreeBSD-doc@freebsd.org Subject: Re: Linuxdoc - Reply Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk >>> Jordan K. Hubbard <jkh@time.cdrom.com> 6/ 4 7:58pm >>> The choice of SGML itself seems to be a non-issue. Everyone from Sun to HP to DEC (I live with a tech writer who's a docs project manager for Sun and worked everywhere else before that) is moving to SGML and some DTD, O'Reilly and associates has all of its authors writing in SGML using their own DTD (which they'll provide to anyone for free, BTW) and the world in general is just moving away from groff and TeX. So we're on the right train, let's not let the color of the upholstery motivate us into switching back to the more familiar yet outmoded horse and buggy. :-) Jordan >>> Let me add that Novell/UnixWare was also in the process of converting all the documentation to SGML. We found too many advantages in doing this. (Like hey, all the UnixWare manual pages and documentation are available on: http://www.novell.com/manuals/index.html I still vote for moving all the documentation and man pages to HTML (or SGMLand convert to HTML) and having them hypertext linked. This puts all documentation in a single form and in a single place! Darren R. Davis Senior Software Engineer Novell, Inc. From owner-freebsd-doc Wed Jun 5 07:33:20 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id HAA04436 for doc-outgoing; Wed, 5 Jun 1996 07:33:20 -0700 (PDT) Received: from novell.com ([147.2.128.54]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id HAA04430 for <FreeBSD-doc@freebsd.org>; Wed, 5 Jun 1996 07:33:16 -0700 (PDT) Received: from INET-NJ-Message_Server by fromGW with Novell_GroupWise; Wed, 05 Jun 1996 10:30:21 -0400 Content-Type: text/plain Message-ID: <s1b561bd.050@fromGW> X-Mailer: Novell GroupWise 4.1 Date: Wed, 05 Jun 1996 10:39:28 -0400 From: DARREND@novell.com (Darren Davis) To: kelly@fsl.noaa.gov, jfieber@indiana.edu Cc: FreeBSD-doc@freebsd.org, chuckr@Glue.umd.edu Subject: Re: Linuxdoc - Reply Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk >>> John Fieber <jfieber@indiana.edu> 6/ 4 9:58pm >>> SGML is a Good Thing, but we are still climbing the learning curve and the tools are pretty green. Things are getting better though. Rumor has it that the next release of WordPerfect will have their SGML extensions (which are actually pretty good) as standard equipment. Not that it will affect us directly, as the number of applications increase, so do the benefits of using SGML. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ >>> Yes, this is a TRUE statement. The next version of WordPerfect WILL have the SGML support built in. Too bad we can't get someone like Caldera to make a FreeBSD version of WordPerfect like they are doing for Linux. Though, I guess we can run probably run the Linux binary (Ack). Darren R. Davis Senior Software Engineer Novell, Inc. From owner-freebsd-doc Wed Jun 5 09:39:23 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id JAA13812 for doc-outgoing; Wed, 5 Jun 1996 09:39:23 -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 JAA13806 for <FreeBSD-doc@freebsd.org>; Wed, 5 Jun 1996 09:39:21 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id LAA11708; Wed, 5 Jun 1996 11:39:04 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Wed, 5 Jun 1996 11:39:03 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Darren Davis <DARREND@novell.com> cc: chuckr@Glue.umd.edu, jkh@time.cdrom.com, FreeBSD-doc@freebsd.org Subject: Re: Linuxdoc - Reply In-Reply-To: <s1b54364.036@fromGW> Message-ID: <Pine.NEB.3.93.960605113741.422f-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Wed, 5 Jun 1996, Darren Davis wrote: > I still vote for moving all the documentation and man pages to HTML (or > SGMLand convert to HTML) and having them hypertext linked. This puts all > documentation in a single form and in a single place! Well, I'll confess to a secret desire to convert man pages to SGML too, but I'm not quite ready to make waves of that magnitude. :) -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Wed Jun 5 09:45:26 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id JAA14143 for doc-outgoing; Wed, 5 Jun 1996 09:45:26 -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 JAA14138 for <doc@freebsd.org>; Wed, 5 Jun 1996 09:45:24 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id LAA11729; Wed, 5 Jun 1996 11:43:57 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Wed, 5 Jun 1996 11:43:56 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Paul Richards <p.richards@elsevier.co.uk> cc: doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <199606051015.LAA21049@tees> Message-ID: <Pine.NEB.3.93.960605113917.422g-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Wed, 5 Jun 1996, Paul Richards wrote: > Umm, this isn't really in the spirit of SGML. You shouldn't worry *AT ALL* > about the output format, that's the whole point. Alas, there is still a gulf between the spirt of SGML and the reality of SGML. It is shrinking, but it is still there. By considering some aspects of the processing that will happen, some small tweaks that don't compromise the integrity of the DTD can be made that go a long way toward making conversion with existing tools easier. Unfortunately, linuxdoc is basically LaTeX with angle brackets instead of backslashes, and no ability to define macros. It converts to LaTeX very easily, but it is an insult to the spirit of SGML. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Wed Jun 5 09:48:02 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id JAA14328 for doc-outgoing; Wed, 5 Jun 1996 09:48:02 -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 JAA14305 for <doc@freebsd.org>; Wed, 5 Jun 1996 09:48:00 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id LAA11736; Wed, 5 Jun 1996 11:45:37 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Wed, 5 Jun 1996 11:45:37 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: "Andrew V. Stesin" <stesin@elvisti.kiev.ua> cc: grog@lemis.de, doc@freebsd.org Subject: Re: How do I write this SGML stuff? In-Reply-To: <199606051122.OAA01953@office.elvisti.kiev.ua> Message-ID: <Pine.NEB.3.93.960605114501.422h-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Wed, 5 Jun 1996, Andrew V. Stesin wrote: > New Lynx (2.5 or later) which is in the ports > handles tables pretty well. Last time I tried the port, the build crashed and burned. Will try again... -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Wed Jun 5 09:50:34 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id JAA14490 for doc-outgoing; Wed, 5 Jun 1996 09:50:34 -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 JAA14483 for <FreeBSD-doc@FreeBSD.org>; Wed, 5 Jun 1996 09:50:29 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id LAA11743; Wed, 5 Jun 1996 11:50:23 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Wed, 5 Jun 1996 11:50:22 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Chuck Robey <chuckr@Glue.umd.edu> cc: FreeBSD-doc@FreeBSD.org Subject: Re: Linuxdoc In-Reply-To: <Pine.OSF.3.91.960604212648.26610G-100000@ginger.eng.umd.edu> Message-ID: <Pine.NEB.3.93.960605114652.422i-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, Chuck Robey wrote: > When I get confused > by something in groff, I break it up into pieces that at least have > definitions. The pieces of sgml basically don't have any base, concrete > definitions. Just switch groff and sgml in that statment and you have my view of the world. :-) -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Wed Jun 5 09:56:36 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id JAA14888 for doc-outgoing; Wed, 5 Jun 1996 09:56:36 -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 JAA14881 for <FreeBSD-doc@freebsd.org>; Wed, 5 Jun 1996 09:56:32 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id LAA11757; Wed, 5 Jun 1996 11:56:20 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Wed, 5 Jun 1996 11:56:20 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Chuck Robey <chuckr@Glue.umd.edu> cc: "Jordan K. Hubbard" <jkh@time.cdrom.com>, FreeBSD-doc@freebsd.org Subject: Re: Linuxdoc In-Reply-To: <Pine.OSF.3.91.960604220813.26610J-100000@ginger.eng.umd.edu> Message-ID: <Pine.NEB.3.93.960605115322.422j-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, 4 Jun 1996, Chuck Robey wrote: > If Someone who understands sgml would go to the trouble of providing > examples of how all the parts of the dtd we use should be used in a > document, I put some stuff up on freefall: http://www.freebsd.org/tutorials/linuxdoc/guide.sgml http://www.freebsd.org/tutorials/linuxdoc/guide.html Ignore the first two sections of the guide; they are about how to convert things and are irrelevant. Just look at the sgmlfmt(1) man page for that information. http://www.freebsd.org/tutorials/linuxdoc/example.sgml http://www.freebsd.org/tutorials/linuxdoc/example.html A little example. Neither of these are very complete. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Wed Jun 5 11:08:16 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id LAA20830 for doc-outgoing; Wed, 5 Jun 1996 11:08:16 -0700 (PDT) Received: from distortion.eng.umd.edu (distortion.eng.umd.edu [129.2.98.6]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id LAA20824 for <FreeBSD-doc@freebsd.org>; Wed, 5 Jun 1996 11:08:14 -0700 (PDT) Received: from skipper.eng.umd.edu (skipper.eng.umd.edu [129.2.98.208]) by distortion.eng.umd.edu (8.7.5/8.7.3) with ESMTP id OAA24489; Wed, 5 Jun 1996 14:08:05 -0400 (EDT) Received: (from chuckr@localhost) by skipper.eng.umd.edu (8.7.5/8.7.3) id OAA32226; Wed, 5 Jun 1996 14:08:04 -0400 (EDT) Date: Wed, 5 Jun 1996 14:08:02 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@skipper.eng.umd.edu To: Darren Davis <DARREND@novell.com> cc: jkh@time.cdrom.com, FreeBSD-doc@freebsd.org Subject: Re: Linuxdoc - Reply In-Reply-To: <s1b5436a.037@fromGW> Message-ID: <Pine.OSF.3.91.960605140604.31106A-100000@skipper.eng.umd.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Wed, 5 Jun 1996, Darren Davis wrote: > >>> Jordan K. Hubbard <jkh@time.cdrom.com> 6/ 4 7:58pm >>> > > So we're on the right train, let's not let the color of the upholstery > motivate us into switching back to the more familiar yet outmoded horse > and buggy. :-) > > Let me add that Novell/UnixWare was also in the process of converting all > the documentation to SGML. We found too many advantages in doing this. > (Like hey, all the UnixWare manual pages and documentation are available > on: > > http://www.novell.com/manuals/index.html > > I still vote for moving all the documentation and man pages to HTML (or > SGMLand convert to HTML) and having them hypertext linked. This puts all > documentation in a single form and in a single place! Darren, I don't mind using a good sgml tool, if well documented. We don't have one right now. I can't document it, I can't even figure it out, except for a real minimum subset. ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- From owner-freebsd-doc Wed Jun 5 14:46:12 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id OAA08553 for doc-outgoing; Wed, 5 Jun 1996 14:46:12 -0700 (PDT) Received: from mexico.brainstorm.eu.org (root@mexico.brainstorm.eu.org [193.56.58.253]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id OAA08532 for <doc@freebsd.org>; Wed, 5 Jun 1996 14:46:06 -0700 (PDT) Received: from brasil.brainstorm.eu.org (brasil.brainstorm.eu.org [193.56.58.33]) by mexico.brainstorm.eu.org (8.7.5/8.7.3) with ESMTP id XAA05860; Wed, 5 Jun 1996 23:46:03 +0200 Received: (from uucp@localhost) by brasil.brainstorm.eu.org (8.6.12/8.6.12) with UUCP id XAA24936; Wed, 5 Jun 1996 23:45:25 +0200 Received: (from roberto@localhost) by keltia.freenix.fr (8.8.Alpha.4/keltia-uucp-2.8) id IAA02040; Wed, 5 Jun 1996 08:33:54 +0200 (MET DST) From: Ollivier Robert <roberto@keltia.freenix.fr> Message-Id: <199606050633.IAA02040@keltia.freenix.fr> Subject: Re: How do I write this SGML stuff? To: chuckr@Glue.umd.edu (Chuck Robey) Date: Wed, 5 Jun 1996 08:33:54 +0200 (MET DST) Cc: doc@freebsd.org (FreeBSD documentation list) In-Reply-To: <Pine.OSF.3.91.960604220308.26610I-100000@ginger.eng.umd.edu> from Chuck Robey at "Jun 4, 96 10:06:37 pm" X-Operating-System: FreeBSD 2.2-CURRENT ctm#2073 X-Mailer: ELM [version 2.4ME+ PL19 (25)] MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk It seems that Chuck Robey said: > that trivially in either troff or LaTeX, but I can't find any in the > handbook, and there's no explanation anywhere I can find. I could even > turn on underlining, only one kind of emphasis. The idea of having to go > thru thousands of lines looking for one example, it makes it too hard to To be honest, if you know LaTeX, you know the Linuxdoc DTD. Instead of \em, you just use <em/.../ or <em>...</em>.That was part of this reason I recommended using the Linuxdoc and started using it for the FAQ two years ago. At the time, there was no real tool to generate text, HTML, LaTeX from a a common source document. The Linuxdoc is far from perfect but at the time it seemed one of the best solution... :-) -- Ollivier ROBERT -=- The daemon is FREE! -=- roberto@keltia.freenix.fr FreeBSD keltia.freenix.fr 2.2-CURRENT #6: Tue Jun 4 00:25:26 MET DST 1996 From owner-freebsd-doc Wed Jun 5 14:46:14 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id OAA08564 for doc-outgoing; Wed, 5 Jun 1996 14:46:14 -0700 (PDT) Received: from mexico.brainstorm.eu.org (root@mexico.brainstorm.eu.org [193.56.58.253]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id OAA08531 for <doc@freebsd.org>; Wed, 5 Jun 1996 14:46:06 -0700 (PDT) Received: from brasil.brainstorm.eu.org (brasil.brainstorm.eu.org [193.56.58.33]) by mexico.brainstorm.eu.org (8.7.5/8.7.3) with ESMTP id XAA05858; Wed, 5 Jun 1996 23:46:02 +0200 Received: (from uucp@localhost) by brasil.brainstorm.eu.org (8.6.12/8.6.12) with UUCP id XAA24937; Wed, 5 Jun 1996 23:45:25 +0200 Received: (from roberto@localhost) by keltia.freenix.fr (8.8.Alpha.4/keltia-uucp-2.8) id IAA02050; Wed, 5 Jun 1996 08:37:53 +0200 (MET DST) From: Ollivier Robert <roberto@keltia.freenix.fr> Message-Id: <199606050637.IAA02050@keltia.freenix.fr> Subject: Re: How do I write this SGML stuff? To: chuckr@Glue.umd.edu (Chuck Robey) Date: Wed, 5 Jun 1996 08:37:53 +0200 (MET DST) Cc: doc@freebsd.org (FreeBSD documentation list) In-Reply-To: <Pine.OSF.3.91.960604233731.26610Q-100000@ginger.eng.umd.edu> from Chuck Robey at "Jun 4, 96 11:40:33 pm" X-Operating-System: FreeBSD 2.2-CURRENT ctm#2073 X-Mailer: ELM [version 2.4ME+ PL19 (25)] MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk It seems that Chuck Robey said: > BTW, lets stick to LaTeX2e, not get older version stuff. It often does > make a difference. Yes, we should not use LaTeX 2.09 any more. LaTeX 2e is far better for many things. LaTeX 2.09 is dead. -- Ollivier ROBERT -=- The daemon is FREE! -=- roberto@keltia.freenix.fr FreeBSD keltia.freenix.fr 2.2-CURRENT #6: Tue Jun 4 00:25:26 MET DST 1996 From owner-freebsd-doc Wed Jun 5 14:53:18 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id OAA08943 for doc-outgoing; Wed, 5 Jun 1996 14:53:18 -0700 (PDT) Received: from who.cdrom.com (who.cdrom.com [204.216.27.3]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id OAA08933 for <doc@freebsd.org>; Wed, 5 Jun 1996 14:53:16 -0700 (PDT) Received: from jolt.eng.umd.edu (jolt.eng.umd.edu [129.2.102.5]) by who.cdrom.com (8.6.12/8.6.11) with ESMTP id OAA16424 for <doc@freebsd.org>; Wed, 5 Jun 1996 14:53:05 -0700 Received: from skipper.eng.umd.edu (skipper.eng.umd.edu [129.2.98.208]) by jolt.eng.umd.edu (8.7.5/8.7.3) with ESMTP id RAA13920; Wed, 5 Jun 1996 17:51:22 -0400 (EDT) Received: (from chuckr@localhost) by skipper.eng.umd.edu (8.7.5/8.7.3) id RAA00320; Wed, 5 Jun 1996 17:51:21 -0400 (EDT) Date: Wed, 5 Jun 1996 17:51:21 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@skipper.eng.umd.edu To: Ollivier Robert <roberto@keltia.freenix.fr> cc: FreeBSD documentation list <doc@freebsd.org> Subject: Re: How do I write this SGML stuff? In-Reply-To: <199606050633.IAA02040@keltia.freenix.fr> Message-ID: <Pine.OSF.3.91.960605174948.32250B-100000@skipper.eng.umd.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Wed, 5 Jun 1996, Ollivier Robert wrote: > It seems that Chuck Robey said: > > that trivially in either troff or LaTeX, but I can't find any in the > > handbook, and there's no explanation anywhere I can find. I could even > > turn on underlining, only one kind of emphasis. The idea of having to go > > thru thousands of lines looking for one example, it makes it too hard to > > To be honest, if you know LaTeX, you know the Linuxdoc DTD. Instead of \em, > you just use <em/.../ or <em>...</em>.That was part of this reason I > recommended using the Linuxdoc and started using it for the FAQ two years > ago. > > At the time, there was no real tool to generate text, HTML, LaTeX from a a > common source document. The Linuxdoc is far from perfect but at the time it > seemed one of the best solution... :-) It's doing the mapping from a dtd to a document that has me confused. I'm learning LaTeX, but not making much headway with sgml. Maybe I have to go out and buy Yet Another Book. ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- From owner-freebsd-doc Thu Jun 6 06:10:24 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id GAA25413 for doc-outgoing; Thu, 6 Jun 1996 06:10:24 -0700 (PDT) Received: from diablo.ppp.de (diablo.ppp.de [193.141.101.34]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id GAA25405 for <doc@FreeBSD.org>; Thu, 6 Jun 1996 06:10:20 -0700 (PDT) Received: from allegro.lemis.de by diablo.ppp.de with smtp (Smail3.1.28.1 #1) id m0uRepO-000QXsC; Thu, 6 Jun 96 15:10 MET DST From: grog@lemis.de (Greg Lehey) Organisation: LEMIS, Schellnhausen 2, 36325 Feldatal, Germany Phone: +49-6637-919123 Fax: +49-6637-919122 Received: (grog@localhost) by allegro.lemis.de (8.6.9/8.6.9) id OAA02995; Thu, 6 Jun 1996 14:32:47 +0200 Message-Id: <199606061232.OAA02995@allegro.lemis.de> Subject: Re: Linuxdoc To: jkh@time.cdrom.com (Jordan K. Hubbard) Date: Thu, 6 Jun 1996 14:32:47 +0200 (MET DST) Cc: doc@FreeBSD.org (FreeBSD Documenters) In-Reply-To: <7005.833939907@time.cdrom.com> from "Jordan K. Hubbard" at Jun 4, 96 06:58:27 pm X-Mailer: ELM [version 2.4 PL23] MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk Jordan K. Hubbard writes: > > The choice of SGML itself seems to be a non-issue. Everyone from Sun > to HP to DEC (I live with a tech writer who's a docs project manager > for Sun and worked everywhere else before that) is moving to SGML and > some DTD, O'Reilly and associates has all of its authors writing in SGML > using their own DTD (which they'll provide to anyone for free, BTW) Well, this was news to me, and I'm one of the ORA authors you mentioned. Lenny Muellner only recently discouraged me from using SGML. I forwarded this message and got this reply: > The statement "O'Reilly and Associates has all of its authors writing in SGML > using their own DTD" is not correct, but it does not imply that we are having > all of our authors write in SGML. Some of our authors--especially the > Linux authors--are very comfortable writing in SGML and have chosen to > provide us their source in it. The DocBook is not "our" DTD--it is the > DTD developed by a consortium of many companies called the Davenport Group and > of which we are one of the founders and sponsors. A very large group > of companies are using it for computer documentation. > > Again, if you want to write your book in SGML, that's fine. It's just that you > are comfortable with troff, you know our macros, and we are set up to convert > what you produce to SGML, so that the process will be faster and easier. > You can concentrate on your content. There's no learning curve for you. > But if you want to take the plunge, go for it. > > Lenny > So we're on the right train, let's not let the color of the upholstery > motivate us into switching back to the more familiar yet outmoded > horse and buggy. :-) There's been so much mail on this subject in the last couple of days that I haven't found time to analyse it, but I think we can say: - Nobody likes TeX or groff that much. - SGML would be a good idea - Linuxdoc is probably a bad choice - We need a documented DTD. What do you say we examine DocBook? Greg From owner-freebsd-doc Thu Jun 6 08:06:39 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id IAA07617 for doc-outgoing; Thu, 6 Jun 1996 08:06:39 -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 IAA07609 for <doc@freebsd.org>; Thu, 6 Jun 1996 08:06:31 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id KAA16906; Thu, 6 Jun 1996 10:06:12 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Thu, 6 Jun 1996 10:06:11 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Ollivier Robert <roberto@keltia.freenix.fr> cc: Chuck Robey <chuckr@Glue.umd.edu>, FreeBSD documentation list <doc@freebsd.org> Subject: Re: How do I write this SGML stuff? In-Reply-To: <199606050637.IAA02050@keltia.freenix.fr> Message-ID: <Pine.NEB.3.93.960606100453.422y-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Wed, 5 Jun 1996, Ollivier Robert wrote: > It seems that Chuck Robey said: > > BTW, lets stick to LaTeX2e, not get older version stuff. It often does > > make a difference. > > Yes, we should not use LaTeX 2.09 any more. LaTeX 2e is far better for many > things. LaTeX 2.09 is dead. ^^^^ I don't think I even have that any more! Hasn't 2e been around for a couple *years* now? -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Thu Jun 6 08:08:08 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id IAA07808 for doc-outgoing; Thu, 6 Jun 1996 08:08:08 -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 IAA07690 for <doc@FreeBSD.org>; Thu, 6 Jun 1996 08:08:00 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id KAA16891; Thu, 6 Jun 1996 10:04:29 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Thu, 6 Jun 1996 10:04:28 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Greg Lehey <grog@lemis.de> cc: "Jordan K. Hubbard" <jkh@time.cdrom.com>, FreeBSD Documenters <doc@FreeBSD.org> Subject: Re: Linuxdoc In-Reply-To: <199606061232.OAA02995@allegro.lemis.de> Message-ID: <Pine.NEB.3.93.960606091459.422x-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk On Thu, 6 Jun 1996, Greg Lehey wrote: > There's been so much mail on this subject in the last couple of days > that I haven't found time to analyse it, but I think we can say: > > - Nobody likes TeX or groff that much. > - SGML would be a good idea > - Linuxdoc is probably a bad choice > - We need a documented DTD. > > What do you say we examine DocBook? A benefit of Docbook is that it is becoming a defacto standard exchange dtd for computer system documentation, software in particular. It is very rich, but also pretty complex. Fortunately it is documented. Unfortunately, due to its complexity it is quite a chore to convert to (troff|tex|html). The current tool that does our conversion grunt work (sgmlsasp) is totally inadequate. Since we are in general agreement that we are probably on the right train, but the color of the upholstry is making us sick, I'm looking at the following: 1) Replace sgmlsasp with instant (anyone got a better name?). It Intstant was developed by OSF to facilitate conversions of SGML documents. Its small (text: 65536, data: 4096, bss 896), pretty fast, has a BSD compatible license, and is *much* more powerful than sgmlsasp. It parses the whole document into a tree, and then traverses the tree applying rules that you specify in a "transpec" file. Rules can reference other rules and most importantly, rules can search the tree for other nodes (i.e. cross reference targets). There are sophisticated mechanisms for specifying rule matching criteria (which rules get applied to which nodes) that include presence of and/or values of attributes in the node, or in ancestor, parent, sibling, or child nodes. You can create variables to stash things, and when instant can't do something itself, rules can call execute system commands. On the down side, the tool clearly has some rough edges. In particular the transpec file format is difficult to use. I'm working on a little hack to allow the transpec files to be written in sgml which will make writing them much less painful. I have instant bmake'd and it could drop in more or less instantly, although it can't be used until the next two steps are done. 2a) Using intstant makes de-crufting the linuxdoc DTD highly desirable. In particular, there is a lot of stuff in the DTD that is there to overcome problems in the conversion. I speak mainly of all the SHORTREF stuff that has caused me no end of frustration, but there are other cleaning opportunities as well. This decrufting is in progress. 2b) To move over from sgmlsasp to instant, "transpec" files need to be created. Since instant provides all the functionality of sgmlsasp, hacked up a perl script to convert sgmlsasp mapping files to instant transpec files. With these, instant becomes a plug-in replacement for sgmlasp which could then be removed from FreeBSD. I am currently testing the newly generated transpec files. 3) The recent issue of tables has inspired me to look more closely at the tables in linuxdoc. What I propose is to remove the tables from linuxdoc before we have documents that use them and replace them with CALS tables from Docbook. CALS tables are used in quite a few DTDs. I think this will be relatively painless to do at the DTD level and I already have some primitive cals table -> html conversion stuff for instant. I could probably hack the cals -> LaTeX, but would definately need help with cals -> groff. 4) Up to this point, we are using a cleaned up linuxdoc DTD, but with a new improved conversion engine. The improved conversion engine will make enhancements to the DTD much easier to implement. This is fairly important because the Handbook is over 350 pages and the prospect of converting it to another DTD is not something i'm looking forward to doing. I think it ultimately will happen, but not this week. For those concerned about the L-word, the DTD will be changed enough that would could call it something else. :) 5) If we bring in docbook tables, we may as well bring in Docbook. It wouldn't be immediately used, but it would be at least surveying the land and ultimately paving the way. Docbook is around 130k and the ISO entity sets are another 90k. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Thu Jun 6 08:24:33 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id IAA08661 for doc-outgoing; Thu, 6 Jun 1996 08:24:33 -0700 (PDT) Received: from diablo.ppp.de (diablo.ppp.de [193.141.101.34]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id IAA08645 for <doc@FreeBSD.org>; Thu, 6 Jun 1996 08:24:27 -0700 (PDT) Received: from allegro.lemis.de by diablo.ppp.de with smtp (Smail3.1.28.1 #1) id m0uRgvA-000QXtC; Thu, 6 Jun 96 17:24 MET DST From: grog@lemis.de (Greg Lehey) Organisation: LEMIS, Schellnhausen 2, 36325 Feldatal, Germany Phone: +49-6637-919123 Fax: +49-6637-919122 Received: (grog@localhost) by allegro.lemis.de (8.6.9/8.6.9) id RAA03718; Thu, 6 Jun 1996 17:17:34 +0200 Message-Id: <199606061517.RAA03718@allegro.lemis.de> Subject: Re: Linuxdoc To: jfieber@indiana.edu (John Fieber) Date: Thu, 6 Jun 1996 17:17:33 +0200 (MET DST) Cc: doc@FreeBSD.org (FreeBSD Documenters) In-Reply-To: <Pine.NEB.3.93.960606091459.422x-100000@Fieber-John.campusview.indiana.edu> from "John Fieber" at Jun 6, 96 10:04:28 am X-Mailer: ELM [version 2.4 PL23] MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk John Fieber writes: > > On Thu, 6 Jun 1996, Greg Lehey wrote: > >> There's been so much mail on this subject in the last couple of days >> that I haven't found time to analyse it, but I think we can say: >> >> - Nobody likes TeX or groff that much. >> - SGML would be a good idea >> - Linuxdoc is probably a bad choice >> - We need a documented DTD. >> >> What do you say we examine DocBook? > > A benefit of Docbook is that it is becoming a defacto standard > exchange dtd for computer system documentation, software in > particular. It is very rich, but also pretty complex. > Fortunately it is documented. Unfortunately, due to its > complexity it is quite a chore to convert to (troff|tex|html). > The current tool that does our conversion grunt work (sgmlsasp) > is totally inadequate. > > Since we are in general agreement that we are probably on the > right train, but the color of the upholstry is making us sick, > I'm looking at the following: > > 1) Replace sgmlsasp with instant (anyone got a better name?). It > Intstant was developed by OSF to facilitate conversions of > SGML documents. Its small (text: 65536, data: 4096, bss 896), > pretty fast, has a BSD compatible license, and is *much* more > powerful than sgmlsasp. It parses the whole document into > a tree, and then traverses the tree applying rules that you > specify in a "transpec" file. Rules can reference other rules > and most importantly, rules can search the tree for other > nodes (i.e. cross reference targets). There are sophisticated > mechanisms for specifying rule matching criteria (which rules > get applied to which nodes) that include presence of and/or > values of attributes in the node, or in ancestor, parent, > sibling, or child nodes. You can create variables to stash > things, and when instant can't do something itself, rules > can call execute system commands. > > On the down side, the tool clearly has some rough edges. In > particular the transpec file format is difficult > to use. I'm working on a little hack to allow the transpec > files to be written in sgml which will make writing them > much less painful. > > I have instant bmake'd and it could drop in more or less > instantly, although it can't be used until the next two > steps are done. Sounds like a reasonable thing to examine. You might like to ask Lenny if ORA is prepared to release their conversion tools. FYI, ORA do their formatting with groff, and to do that they convert their SGML base to their .ms variant. For various reasons, I'd rather not be involved in the asking. > 3) The recent issue of tables has inspired me to look more > closely at the tables in linuxdoc. What I propose is to > remove the tables from linuxdoc before we have documents > that use them and replace them with CALS tables from Docbook. > CALS tables are used in quite a few DTDs. > I think this will be relatively painless to do at the DTD > level and I already have some primitive cals table -> html > conversion stuff for instant. I could probably hack the > cals -> LaTeX, but would definately need help with cals -> > groff. I think the things you say later on make this a waste of effort. If you need groff help, though, just ask. > 4) Up to this point, we are using a cleaned up linuxdoc DTD, but > with a new improved conversion engine. The improved > conversion engine will make enhancements to the DTD > much easier to implement. This is fairly > important because the Handbook is over 350 pages and the > prospect of converting it to another DTD is not something > i'm looking forward to doing. I think it ultimately will > happen, but not this week. Does it all have to happen at once? I currently have my "how to add a second disk" half finished, and the prospect of finishing it completely with the current DTD scares me. It would be nice to be able to mix the linuxdoc DTD and (for example) DocBook in the sources. That would make transition much easier, too. > 5) If we bring in docbook tables, we may as well bring in > Docbook. It wouldn't be immediately used, but it would > be at least surveying the land and ultimately paving > the way. Docbook is around 130k and the ISO entity sets > are another 90k. Sounds like the thing to do. Greg From owner-freebsd-doc Thu Jun 6 08:55:47 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id IAA11221 for doc-outgoing; Thu, 6 Jun 1996 08:55:47 -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 IAA11213 for <doc@FreeBSD.org>; Thu, 6 Jun 1996 08:55:40 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id KAA17054; Thu, 6 Jun 1996 10:53:50 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Thu, 6 Jun 1996 10:53:50 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Greg Lehey <grog@lemis.de> cc: FreeBSD Documenters <doc@FreeBSD.org> Subject: Re: Linuxdoc In-Reply-To: <199606061517.RAA03718@allegro.lemis.de> Message-ID: <Pine.NEB.3.93.960606104256.422A-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk On Thu, 6 Jun 1996, Greg Lehey wrote: > > I think this will be relatively painless to do at the DTD > > level and I already have some primitive cals table -> html > > conversion stuff for instant. I could probably hack the > > cals -> LaTeX, but would definately need help with cals -> > > groff. > > I think the things you say later on make this a waste of effort. If How so? If we ultimately end up with Docbook, formatting of tables will already be done. > > important because the Handbook is over 350 pages and the > > prospect of converting it to another DTD is not something > > i'm looking forward to doing. I think it ultimately will > > happen, but not this week. > > Does it all have to happen at once? Hmm... Not necessairly, but incremental changes would have to be applied horizontally across the whole document---while having some sections written up in docbook and others in linuxdoc may be possible, it would be orders of magnitude more difficult than making changes all at once. I think it would be most efficient to carve out a chunk of time and grind it all through more or less at once. I need to spend some more time studying the docbook dtd. I think instant could do most of the conversion, but I'm not sure what the magnitude of the manual cleanup will be. The task of actually taking advantage of the docbook features will take a long time but can be done on an "as time allows" schedule. > I currently have my "how to add a > second disk" half finished, and the prospect of finishing it > completely with the current DTD scares me. It would be nice to be > able to mix the linuxdoc DTD and (for example) DocBook in the > sources. That would make transition much easier, too. Mix and match is only possible if you hawe two well designed, modular DTDs. Unfortunately one of the DTDs in question doesn't quite fit that model (and you can guess which one it is!) -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Thu Jun 6 11:08:20 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id LAA22748 for doc-outgoing; Thu, 6 Jun 1996 11:08:20 -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 LAA22727 for <doc@FreeBSD.org>; Thu, 6 Jun 1996 11:08:09 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id NAA17436; Thu, 6 Jun 1996 13:04:21 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Thu, 6 Jun 1996 13:04:20 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Greg Lehey <grog@lemis.de> cc: FreeBSD Documenters <doc@FreeBSD.org> Subject: Re: Linuxdoc In-Reply-To: <199606061652.SAA03920@allegro.lemis.de> Message-ID: <Pine.NEB.3.93.960606123633.422D-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk On Thu, 6 Jun 1996, Greg Lehey wrote: > > Hmm... Not necessairly, but incremental changes would have to be > > applied horizontally across the whole document---while having > > some sections written up in docbook and others in linuxdoc may be > > possible, it would be orders of magnitude more difficult than > > making changes all at once. > > We need to discuss that statement. I don't see that it's true. Sure, > each file should have only one kind of format, but the individual > files could have different formats. At the moment, we have one of at While the handbook is seprated into many files, only one component in the system knows that, the SGML entity manager. When the parser encounters an entity reference, it just hands it off to the entity manager which returns the data. The parser does not no and does not care where the data came from. It could have been a distinct file, it may be just part of a file. It could be a stream read from a network socket. Only the entity manager knows. Now, it is possible to embed a subdocument with a different doctype inside a document but that isn't practical for our purposes because there is an inpenetrable wall between the two. In particular, cross references don't work across doctype boundaries. In fact, the sgml parser currently in FreeBSD implements subdoc handling be simply forking and calling itself to handle the subdoc. Possible, yes. Practical, no. > > Mix and match is only possible if you hawe two well designed, > > modular DTDs. > > I must be missing something here. If I am, please fill me in. All the elements of a document can usually be lumped together into various categories, sectioning elements, list elements, paragraph type element, tables, etc. If you have two DTDs that are designed in a modular fashion, it isn't difficult to create a hybrid DTD. In fact, this is a good thing because otherwize you end up with DTDs with a lot of redundancy, or a single DTD that is horrendously complex. With modular DTDs, you can pick and choose what you want. You may want the same table and list elements in most all documents, but the general structure for books, memos, articles, man pages are all quite different. With modular DTD parts, you write a manpage outer structure, and just plug in the tables and lists. One way to approach transfer from linuxdoc to docbook is to import a bit of the docbook DTD, say lists, and convert all the lists into that format. Next, bring in docbook sectioning elements, and so on until what was the linuxdoc DTD is now a proper subset of docbook and behold, you can simply call it a docbook document and ditch the old dtd. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Thu Jun 6 11:27:05 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id LAA23722 for doc-outgoing; Thu, 6 Jun 1996 11:27:05 -0700 (PDT) Received: from diablo.ppp.de (diablo.ppp.de [193.141.101.34]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id LAA23716 for <doc@FreeBSD.org>; Thu, 6 Jun 1996 11:27:01 -0700 (PDT) Received: from allegro.lemis.de by diablo.ppp.de with smtp (Smail3.1.28.1 #1) id m0uRisy-000QXsC; Thu, 6 Jun 96 19:30 MET DST From: grog@lemis.de (Greg Lehey) Organisation: LEMIS, Schellnhausen 2, 36325 Feldatal, Germany Phone: +49-6637-919123 Fax: +49-6637-919122 Received: (grog@localhost) by allegro.lemis.de (8.6.9/8.6.9) id SAA03920; Thu, 6 Jun 1996 18:52:51 +0200 Message-Id: <199606061652.SAA03920@allegro.lemis.de> Subject: Re: Linuxdoc To: jfieber@indiana.edu (John Fieber) Date: Thu, 6 Jun 1996 18:52:51 +0200 (MET DST) Cc: doc@FreeBSD.org (FreeBSD Documenters) In-Reply-To: <Pine.NEB.3.93.960606104256.422A-100000@Fieber-John.campusview.indiana.edu> from "John Fieber" at Jun 6, 96 10:53:50 am X-Mailer: ELM [version 2.4 PL23] MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk John Fieber writes: > > On Thu, 6 Jun 1996, Greg Lehey wrote: > >>> I think this will be relatively painless to do at the DTD >>> level and I already have some primitive cals table -> html >>> conversion stuff for instant. I could probably hack the >>> cals -> LaTeX, but would definately need help with cals -> >>> groff. >> >> I think the things you say later on make this a waste of effort. If > > How so? If we ultimately end up with Docbook, formatting of > tables will already be done. See the next point. >>> important because the Handbook is over 350 pages and the >>> prospect of converting it to another DTD is not something >>> i'm looking forward to doing. I think it ultimately will >>> happen, but not this week. >> >> Does it all have to happen at once? > > Hmm... Not necessairly, but incremental changes would have to be > applied horizontally across the whole document---while having > some sections written up in docbook and others in linuxdoc may be > possible, it would be orders of magnitude more difficult than > making changes all at once. We need to discuss that statement. I don't see that it's true. Sure, each file should have only one kind of format, but the individual files could have different formats. At the moment, we have one of at least three possible transformations: .sgml->.html, .sgml->.tex, .sgml->.mm (or whatever). What we need to do is to agree on a different file name extension for the DocBook or the latexdoc stuff (say, change .sgml to .ldoc for the latexdoc stuff), and then we have three additional transformations .ldoc->.html, .ldoc->.tex, .ldoc->.mm. This is rather like what I'm doing in the latest version of my book, in which I have .ms, .man and .tex files. > I think it would be most efficient to carve out a chunk of time and > grind it all through more or less at once. I need to spend some more > time studying the docbook dtd. I think instant could do most of the > conversion, but I'm not sure what the magnitude of the manual > cleanup will be. The task of actually taking advantage of the > docbook features will take a long time but can be done on an "as > time allows" schedule. The thought of doing that horrifies me. If you want, go ahead, but I'm sure that the other way would make more sense. In fact, with a bit of thought, it might be possible to allow files of different formats to coexist, as long as there is a defined way of converting them to HTML. >> I currently have my "how to add a second disk" half finished, and >> the prospect of finishing it completely with the current DTD scares >> me. It would be nice to be able to mix the linuxdoc DTD and (for >> example) DocBook in the sources. That would make transition much >> easier, too. > Mix and match is only possible if you hawe two well designed, > modular DTDs. I must be missing something here. If I am, please fill me in. > Unfortunately one of the DTDs in question doesn't quite fit that > model (and you can guess which one it is!) I can think of at least one :-) Greg From owner-freebsd-doc Thu Jun 6 12:43:29 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id MAA29655 for doc-outgoing; Thu, 6 Jun 1996 12:43:29 -0700 (PDT) Received: from becker2.u.washington.edu (spaz@becker2.u.washington.edu [140.142.12.68]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id MAA29648 for <doc@freebsd.org>; Thu, 6 Jun 1996 12:43:27 -0700 (PDT) Received: from localhost by becker2.u.washington.edu (5.65+UW96.04/UW-NDC Revision: 2.33 ) id AA17390; Thu, 6 Jun 96 12:42:27 -0700 Date: Thu, 6 Jun 1996 12:42:25 -0700 (PDT) From: John Utz <spaz@u.washington.edu> To: John Fieber <jfieber@indiana.edu> Cc: Greg Lehey <grog@lemis.de>, FreeBSD Documenters <doc@freebsd.org> Subject: Re: Linuxdoc In-Reply-To: <Pine.NEB.3.93.960606104256.422A-100000@Fieber-John.campusview.indiana.edu> Message-Id: <Pine.OSF.3.92a.960606123548.16233A-100000@becker2.u.washington.edu> Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk Hi; where do we find the DocBook stuff? I have an outline of a rather extensive discussion wrt ethenet under freebsd. This includes serving windoze via samba etc... my time has been constrained by finals. My enthusiasm has been contrained by the constant churning with the docformat stuff. The Docbook stuff seems worthy of taking a peek at... reading this i realize i sound snippy about the doc format stuff. This is not the case. I welcome the discussion if it results in the adoption of a consistent, easy to use interface. tnx! ******************************************************************************* John Utz spaz@u.washington.edu idiocy is the impulse function in the convolution of life From owner-freebsd-doc Thu Jun 6 12:49:00 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id MAA00225 for doc-outgoing; Thu, 6 Jun 1996 12:49:00 -0700 (PDT) Received: from time.cdrom.com (time.cdrom.com [204.216.27.226]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id MAA00218 for <doc@FreeBSD.org>; Thu, 6 Jun 1996 12:48:58 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by time.cdrom.com (8.7.5/8.6.9) with SMTP id MAA17221; Thu, 6 Jun 1996 12:47:21 -0700 (PDT) To: grog@lemis.de (Greg Lehey) cc: doc@FreeBSD.org (FreeBSD Documenters) Subject: Re: Linuxdoc In-reply-to: Your message of "Thu, 06 Jun 1996 14:32:47 +0200." <199606061232.OAA02995@allegro.lemis.de> Date: Thu, 06 Jun 1996 12:47:20 -0700 Message-ID: <17219.834090440@time.cdrom.com> From: "Jordan K. Hubbard" <jkh@time.cdrom.com> Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk > Well, this was news to me, and I'm one of the ORA authors you > mentioned. Lenny Muellner only recently discouraged me from using > SGML. I forwarded this message and got this reply: Sorry, this is simply what I was told by one of the ORA booth staffers at a recent USENIX. I guess I was misinformed. Jordan From owner-freebsd-doc Fri Jun 7 05:31:45 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id FAA11504 for doc-outgoing; Fri, 7 Jun 1996 05:31:45 -0700 (PDT) Received: from mailbox.neosoft.com (mailbox.neosoft.com [206.109.1.16]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id FAA11498 for <doc@freebsd.org>; Fri, 7 Jun 1996 05:31:43 -0700 (PDT) Received: from bonkers.taronga.com (root@bonkers.neosoft.com [206.109.2.48]) by mailbox.neosoft.com (8.7.5/8.7.3) with SMTP id HAA24148 for <doc@freebsd.org>; Fri, 7 Jun 1996 07:31:34 -0500 (CDT) Received: (from peter@localhost) by bonkers.taronga.com (8.6.11/8.6.9) id HAA19807; Fri, 7 Jun 1996 07:32:01 -0500 Date: Fri, 7 Jun 1996 07:32:01 -0500 From: peter@taronga.com (Peter da Silva) Message-Id: <199606071232.HAA19807@bonkers.taronga.com> To: doc@freebsd.org Subject: Re: Linuxdoc Newsgroups: taronga.freebsd.doc In-Reply-To: <199606061652.SAA03920@allegro.lemis.de> References: <Pine.NEB.3.93.960606104256.422A-100000@Fieber-John.campusview.indiana.edu> Organization: none Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk >We need to discuss that statement. I don't see that it's true. Sure, >each file should have only one kind of format, but the individual >files could have different formats. At the moment, we have one of at >least three possible transformations: .sgml->.html, .sgml->.tex, >.sgml->.mm (or whatever). What we need to do is to agree on a >different file name extension for the DocBook or the latexdoc stuff >(say, change .sgml to .ldoc for the latexdoc stuff), and then we have >three additional transformations .ldoc->.html, .ldoc->.tex, >.ldoc->.mm. This is rather like what I'm doing in the latest version >of my book, in which I have .ms, .man and .tex files. I recommend that none of the file formats be named ".sgml". That's sort of like naming your C files ".src" or ".txt", right? All three (latexdoc, docbook, and html) are SGML DTDs. To support this, on the Amiga there were a family of file formats called IFF. Some programs decided to call their SMUS (simple musical score) or ILBM (interleaved bitmap) files ".iff" because the PC versions of their programs didn't like 4-character suffixes. As a result you ended up with a bunch of files all called ".iff". This wasn't as bad as all that, because the programmers who did that also tended to ship programs that didn't work well on the Amiga for similar reasons, but until they all went out of business the confusion was annoying. So, how about naming the files at the semantic level rather than the structural... From owner-freebsd-doc Sat Jun 8 03:46:30 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id DAA18442 for doc-outgoing; Sat, 8 Jun 1996 03:46:30 -0700 (PDT) Received: from diablo.ppp.de (diablo.ppp.de [193.141.101.34]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id DAA18404 for <doc@FreeBSD.org>; Sat, 8 Jun 1996 03:46:24 -0700 (PDT) Received: from allegro.lemis.de by diablo.ppp.de with smtp (Smail3.1.28.1 #1) id m0uSLXA-000Qa2C; Sat, 8 Jun 96 12:46 MET DST From: grog@lemis.de (Greg Lehey) Organisation: LEMIS, Schellnhausen 2, 36325 Feldatal, Germany Phone: +49-6637-919123 Fax: +49-6637-919122 Received: (grog@localhost) by allegro.lemis.de (8.6.9/8.6.9) id MAA00683; Sat, 8 Jun 1996 12:45:49 +0200 Message-Id: <199606081045.MAA00683@allegro.lemis.de> Subject: Re: Linuxdoc To: peter@taronga.com (Peter da Silva) Date: Sat, 8 Jun 1996 12:45:49 +0200 (MET DST) Cc: doc@FreeBSD.org In-Reply-To: <199606071232.HAA19807@bonkers.taronga.com> from "Peter da Silva" at Jun 7, 96 07:32:01 am X-Mailer: ELM [version 2.4 PL23] MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk Peter da Silva writes: > >> We need to discuss that statement. I don't see that it's true. Sure, >> each file should have only one kind of format, but the individual >> files could have different formats. At the moment, we have one of at >> least three possible transformations: .sgml->.html, .sgml->.tex, >> .sgml->.mm (or whatever). What we need to do is to agree on a >> different file name extension for the DocBook or the latexdoc stuff >> (say, change .sgml to .ldoc for the latexdoc stuff), and then we have >> three additional transformations .ldoc->.html, .ldoc->.tex, >> .ldoc->.mm. This is rather like what I'm doing in the latest version >> of my book, in which I have .ms, .man and .tex files. > > I recommend that none of the file formats be named ".sgml". That's sort > of like naming your C files ".src" or ".txt", right? All three (latexdoc, > docbook, and html) are SGML DTDs. > > To support this, on the Amiga there were a family of file formats called > IFF. Some programs decided to call their SMUS (simple musical score) or > ILBM (interleaved bitmap) files ".iff" because the PC versions of their > programs didn't like 4-character suffixes. As a result you ended up with > a bunch of files all called ".iff". > > This wasn't as bad as all that, because the programmers who did that also > tended to ship programs that didn't work well on the Amiga for similar > reasons, but until they all went out of business the confusion was annoying. > > So, how about naming the files at the semantic level rather than the > structural... Good idea. I wasn't trying to lay down the law. Greg From owner-freebsd-doc Sat Jun 8 03:46:48 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id DAA18556 for doc-outgoing; Sat, 8 Jun 1996 03:46:48 -0700 (PDT) Received: from diablo.ppp.de (diablo.ppp.de [193.141.101.34]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id DAA18527 for <doc@FreeBSD.org>; Sat, 8 Jun 1996 03:46:42 -0700 (PDT) Received: from allegro.lemis.de by diablo.ppp.de with smtp (Smail3.1.28.1 #1) id m0uSLX9-000QZwC; Sat, 8 Jun 96 12:46 MET DST From: grog@lemis.de (Greg Lehey) Organisation: LEMIS, Schellnhausen 2, 36325 Feldatal, Germany Phone: +49-6637-919123 Fax: +49-6637-919122 Received: (grog@localhost) by allegro.lemis.de (8.6.9/8.6.9) id MAA00631; Sat, 8 Jun 1996 12:30:47 +0200 Message-Id: <199606081030.MAA00631@allegro.lemis.de> Subject: Re: How do I write this SGML stuff? To: chuckr@Glue.umd.edu (Chuck Robey) Date: Sat, 8 Jun 1996 12:30:47 +0200 (MET DST) Cc: doc@FreeBSD.org (FreeBSD Documenters) In-Reply-To: <Pine.OSF.3.91.960605174948.32250B-100000@skipper.eng.umd.edu> from "Chuck Robey" at Jun 5, 96 05:51:21 pm X-Mailer: ELM [version 2.4 PL23] MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk Chuck Robey writes: > > On Wed, 5 Jun 1996, Ollivier Robert wrote: > >> It seems that Chuck Robey said: >>> that trivially in either troff or LaTeX, but I can't find any in the >>> handbook, and there's no explanation anywhere I can find. I could even >>> turn on underlining, only one kind of emphasis. The idea of having to go >>> thru thousands of lines looking for one example, it makes it too hard to >> >> To be honest, if you know LaTeX, you know the Linuxdoc DTD. Instead of \em, >> you just use <em/.../ or <em>...</em>.That was part of this reason I >> recommended using the Linuxdoc and started using it for the FAQ two years >> ago. >> >> At the time, there was no real tool to generate text, HTML, LaTeX from a a >> common source document. The Linuxdoc is far from perfect but at the time it >> seemed one of the best solution... :-) > > It's doing the mapping from a dtd to a document that has me confused. > I'm learning LaTeX, but not making much headway with sgml. Maybe I have > to go out and buy Yet Another Book. Are we wed to LaTeX? I find it a very turgid formatter. I tried years ago, and came to the conclusion that I'd rather use plain TeX. When I wrote my book for O'Reilly, they wanted me to write it in troff, and I wanted to write it in TeX. In the end, I gave in, and to my surprise I found troff a *whole* lot better than TeX or derivatives. I'm not trying to convert people, but I do think we should have a choice. Greg From owner-freebsd-doc Sat Jun 8 04:18:47 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id EAA26039 for doc-outgoing; Sat, 8 Jun 1996 04:18:47 -0700 (PDT) Received: from diablo.ppp.de (diablo.ppp.de [193.141.101.34]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id EAA26018 for <doc@FreeBSD.org>; Sat, 8 Jun 1996 04:18:43 -0700 (PDT) Received: from allegro.lemis.de by diablo.ppp.de with smtp (Smail3.1.28.1 #1) id m0uSM2D-000QZvC; Sat, 8 Jun 96 13:18 MET DST From: grog@lemis.de (Greg Lehey) Organisation: LEMIS, Schellnhausen 2, 36325 Feldatal, Germany Phone: +49-6637-919123 Fax: +49-6637-919122 Received: (grog@localhost) by allegro.lemis.de (8.6.9/8.6.9) id MAA00706; Sat, 8 Jun 1996 12:47:09 +0200 Message-Id: <199606081047.MAA00706@allegro.lemis.de> Subject: Re: Linuxdoc - Reply To: jfieber@indiana.edu (John Fieber) Date: Sat, 8 Jun 1996 12:47:08 +0200 (MET DST) Cc: doc@FreeBSD.org (FreeBSD Documenters) In-Reply-To: <Pine.NEB.3.93.960605113741.422f-100000@Fieber-John.campusview.indiana.edu> from "John Fieber" at Jun 5, 96 11:39:03 am X-Mailer: ELM [version 2.4 PL23] MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit Sender: owner-doc@FreeBSD.org X-Loop: FreeBSD.org Precedence: bulk John Fieber writes: > > On Wed, 5 Jun 1996, Darren Davis wrote: > >> I still vote for moving all the documentation and man pages to HTML (or >> SGMLand convert to HTML) and having them hypertext linked. This puts all >> documentation in a single form and in a single place! > > Well, I'll confess to a secret desire to convert man pages to > SGML too, but I'm not quite ready to make waves of that > magnitude. :) Ouch. As if we didn't have enough important things to do. I'd say that we should only approach that sort of thing when we have good, automated tools. New man pages will continue to trickle in, and they'll mainly be in *roff. Greg From owner-freebsd-doc Sat Jun 8 09:27:53 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id JAA12423 for doc-outgoing; Sat, 8 Jun 1996 09:27:53 -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 JAA12411 for <doc@FreeBSD.ORG>; Sat, 8 Jun 1996 09:27:49 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id LAA05818; Sat, 8 Jun 1996 11:27:40 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Sat, 8 Jun 1996 11:27:40 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Peter da Silva <peter@taronga.com> cc: doc@FreeBSD.ORG Subject: Re: Linuxdoc In-Reply-To: <199606071232.HAA19807@bonkers.taronga.com> Message-ID: <Pine.NEB.3.93.960608111116.303J-100000@Fieber-John.campusview.indiana.edu> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@FreeBSD.ORG X-Loop: FreeBSD.org Precedence: bulk On Fri, 7 Jun 1996, Peter da Silva wrote: > I recommend that none of the file formats be named ".sgml". That's sort > of like naming your C files ".src" or ".txt", right? All three (latexdoc, > docbook, and html) are SGML DTDs. This is a most reasonable way to do things. Although (like iff files) proper SGML documents are self identifying to proper sgml tools, make is pretty stupid and must rely on naming conventions. I won't make the change just yet, rather I'll hold off until I have a new conversion mechanism ready to import. And on that front, I've been hacking on instant to make it possible to write translation specifications in a way that won't drive you to jump off a cliff. Progress is looking good. I've taken out (almost) all of the shortref garbage from the linuxdoc DTD that was there to make up for missing functionality in sgmlsasp. Its just about where instant could be a plug-in replacement for sgmlsasp in a manner completely transparent to anyone using sgmlfmt. There are still some more hacking I'd like to do before importing it though. Once that is imported, we can either work on making the linuxdoc dtd more useful, or migrating to another DTD such as docbook. The holdup thus far has been the rigidity of the conversion mechanism which made any dtd changes extremely difficult. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Sat Jun 8 09:31:40 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id JAA12864 for doc-outgoing; Sat, 8 Jun 1996 09:31:40 -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 JAA12858 for <doc@freebsd.org>; Sat, 8 Jun 1996 09:31:36 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id LAA05833; Sat, 8 Jun 1996 11:31:29 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Sat, 8 Jun 1996 11:31:28 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Greg Lehey <grog@lemis.de> cc: Chuck Robey <chuckr@Glue.umd.edu>, FreeBSD Documenters <doc@freebsd.org> Subject: Re: How do I write this SGML stuff? In-Reply-To: <199606081030.MAA00631@allegro.lemis.de> Message-ID: <Pine.NEB.3.93.960608112852.303K-100000@Fieber-John.campusview.indiana.edu> 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, Greg Lehey wrote: > Are we wed to LaTeX? Certainly not! groff is standard equipment in FreeBSD, (La)TeX is not and most likely never will be. Can anyone recommend any good books on troff? I checked one out from the local library and it was abysmal. (sound familiar Chuck?) -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Sat Jun 8 10:34:32 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id KAA19269 for doc-outgoing; Sat, 8 Jun 1996 10:34:32 -0700 (PDT) Received: from jolt.eng.umd.edu (jolt.eng.umd.edu [129.2.102.5]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id KAA19243 for <doc@FreeBSD.org>; Sat, 8 Jun 1996 10:34:28 -0700 (PDT) Received: from ginger.eng.umd.edu (ginger.eng.umd.edu [129.2.98.204]) by jolt.eng.umd.edu (8.7.5/8.7.3) with ESMTP id NAA23950; Sat, 8 Jun 1996 13:34:26 -0400 (EDT) Received: (from chuckr@localhost) by ginger.eng.umd.edu (8.7.5/8.7.3) id NAA23918; Sat, 8 Jun 1996 13:34:25 -0400 (EDT) Date: Sat, 8 Jun 1996 13:34:25 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@ginger.eng.umd.edu To: Greg Lehey <grog@lemis.de> cc: FreeBSD Documenters <doc@FreeBSD.org> Subject: Re: How do I write this SGML stuff? In-Reply-To: <199606081030.MAA00631@allegro.lemis.de> Message-ID: <Pine.OSF.3.91.960608132901.32620B-100000@ginger.eng.umd.edu> 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, Greg Lehey wrote: > > > > It's doing the mapping from a dtd to a document that has me confused. > > I'm learning LaTeX, but not making much headway with sgml. Maybe I have > > to go out and buy Yet Another Book. > > Are we wed to LaTeX? I find it a very turgid formatter. I tried > years ago, and came to the conclusion that I'd rather use plain TeX. > When I wrote my book for O'Reilly, they wanted me to write it in > troff, and I wanted to write it in TeX. In the end, I gave in, and to > my surprise I found troff a *whole* lot better than TeX or > derivatives. I'm not trying to convert people, but I do think we > should have a choice. 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). I've been talking to John Fieber about 'instant', and getting an updated view of John Clark's sgml tools. I'm very unhappy with our present 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. John's working on getting some conversion specs going for instant, and I'm awaiting some sample "transpec" files from him, demonstating 'instant'. I'm also going out to the big local bookstore today, to drop more money on an sgml book. Groan. ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- From owner-freebsd-doc Sat Jun 8 10:47:06 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id KAA20422 for doc-outgoing; Sat, 8 Jun 1996 10:47:06 -0700 (PDT) Received: from distortion.eng.umd.edu (distortion.eng.umd.edu [129.2.98.6]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id KAA20413 for <doc@freebsd.org>; Sat, 8 Jun 1996 10:47:03 -0700 (PDT) Received: from ginger.eng.umd.edu (ginger.eng.umd.edu [129.2.98.204]) by distortion.eng.umd.edu (8.7.5/8.7.3) with ESMTP id NAA08995; Sat, 8 Jun 1996 13:47:00 -0400 (EDT) Received: (from chuckr@localhost) by ginger.eng.umd.edu (8.7.5/8.7.3) id NAA01013; Sat, 8 Jun 1996 13:46:59 -0400 (EDT) Date: Sat, 8 Jun 1996 13:46:59 -0400 (EDT) From: Chuck Robey <chuckr@Glue.umd.edu> X-Sender: chuckr@ginger.eng.umd.edu To: John Fieber <jfieber@indiana.edu> cc: Greg Lehey <grog@lemis.de>, FreeBSD Documenters <doc@freebsd.org> Subject: Re: How do I write this SGML stuff? In-Reply-To: <Pine.NEB.3.93.960608112852.303K-100000@Fieber-John.campusview.indiana.edu> Message-ID: <Pine.OSF.3.91.960608133916.32620D-100000@ginger.eng.umd.edu> 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, John Fieber wrote: > On Sat, 8 Jun 1996, Greg Lehey wrote: > > > Are we wed to LaTeX? Altho (after some reading) TeX and LaTeX aren't that bad, especially LaTeX. > Certainly not! > > groff is standard equipment in FreeBSD, (La)TeX is not and most > likely never will be. > > Can anyone recommend any good books on troff? I checked one out > from the local library and it was abysmal. (sound familiar > Chuck?) Haha, yeah, replace "troff" with "sgml" and you have my situation. OK, I'll trade you, here's a pretty good one for troff (I don't know if it's still in print, and I collect troff articles from other sources): Unix Text Processing, by Dale Dougherty abd Tim O'Reilly. Confusing about the publisher, because the book cover says "Hayden Books", inside leaf says "Howard W. Sams", but copyright page says "O'Reilly & Associates". Anyhow, I have the 6th printing from 1989, and I like this one pretty well, since it covers all the different troff tools (tbl, eqn, etc) and both the ms and mm macros. Even cruises by the use of things like awk and vi, but briefly. ----------------------------+----------------------------------------------- Chuck Robey | Interests include any kind of voice or data chuckr@eng.umd.edu | communications topic, C programming, and Unix. 9120 Edmonston Ct #302 | Greenbelt, MD 20770 | I run Journey2 and n3lxx, both FreeBSD (301) 220-2114 | version 2.2 current -- and great FUN! ----------------------------+----------------------------------------------- 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 <doc@freebsd.org>; 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 <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: Chuck Robey <chuckr@Glue.umd.edu> cc: Greg Lehey <grog@lemis.de>, FreeBSD Documenters <doc@freebsd.org> Subject: Re: How do I write this SGML stuff? In-Reply-To: <Pine.OSF.3.91.960608132901.32620B-100000@ginger.eng.umd.edu> Message-ID: <Pine.NEB.3.93.960608193213.303U-100000@Fieber-John.campusview.indiana.edu> 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, <SECT>, grab the text out of the <HEADING> 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 ================ From owner-freebsd-doc Sat Jun 8 18:09:20 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id SAA16636 for doc-outgoing; Sat, 8 Jun 1996 18:09:20 -0700 (PDT) Received: from time.cdrom.com (time.cdrom.com [204.216.27.226]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id SAA16628 for <doc@freebsd.org>; Sat, 8 Jun 1996 18:09:18 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by time.cdrom.com (8.7.5/8.6.9) with SMTP id SAA02284; Sat, 8 Jun 1996 18:08:41 -0700 (PDT) To: John Fieber <jfieber@indiana.edu> cc: Chuck Robey <chuckr@Glue.umd.edu>, Greg Lehey <grog@lemis.de>, FreeBSD Documenters <doc@freebsd.org> Subject: Re: How do I write this SGML stuff? In-reply-to: Your message of "Sat, 08 Jun 1996 19:59:08 CDT." <Pine.NEB.3.93.960608193213.303U-100000@Fieber-John.campusview.indiana.edu> Date: Sat, 08 Jun 1996 18:08:41 -0700 Message-ID: <2282.834282521@time.cdrom.com> From: "Jordan K. Hubbard" <jkh@time.cdrom.com> Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk > 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. Sounds great, Dad, when do we get there? :-) Jordan From owner-freebsd-doc Sat Jun 8 18:26:15 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id SAA19036 for doc-outgoing; Sat, 8 Jun 1996 18:26:15 -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 SAA19027 for <doc@freebsd.org>; Sat, 8 Jun 1996 18:26:13 -0700 (PDT) Received: from localhost (jfieber@localhost) by Fieber-John.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id UAA07588; Sat, 8 Jun 1996 20:25:54 -0500 (EST) X-Authentication-Warning: Fieber-John.campusview.indiana.edu: jfieber owned process doing -bs Date: Sat, 8 Jun 1996 20:25:54 -0500 (EST) From: John Fieber <jfieber@indiana.edu> X-Sender: jfieber@Fieber-John.campusview.indiana.edu To: "Jordan K. Hubbard" <jkh@time.cdrom.com> cc: Chuck Robey <chuckr@Glue.umd.edu>, Greg Lehey <grog@lemis.de>, FreeBSD Documenters <doc@freebsd.org> Subject: Re: How do I write this SGML stuff? In-Reply-To: <2282.834282521@time.cdrom.com> Message-ID: <Pine.NEB.3.93.960608201620.303V-100000@Fieber-John.campusview.indiana.edu> 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, Jordan K. Hubbard wrote: > Sounds great, Dad, when do we get there? :-) When Congress passes legislation to extend the length of the day to 36 hours. :-) Seriously, I think getting a more powerful conversion mechanism in place could happen in the next several weeks. That will allow me to continue working on my Docbook to HTML translator which is reasonably far along already. I'll definately need a lot of help with the a Docbook to groff conversion though. I just got the syllabus for a summer class I'm taking starting next week and was pleasntly surprised to discover that a whopping 45% of the grade is for "Developing an SGML DTD for course syllabi", so it looks like my brain will be in SGML mode for awhile. With that simple of an assignment, I should have extra brain cycles for the FreeBSD doc machinery. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================ From owner-freebsd-doc Sat Jun 8 22:32:33 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id WAA20381 for doc-outgoing; Sat, 8 Jun 1996 22:32:33 -0700 (PDT) Received: from gatekeeper.fsl.noaa.gov (gatekeeper.fsl.noaa.gov [137.75.131.181]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id WAA20372 for <doc@freebsd.org>; Sat, 8 Jun 1996 22:32:31 -0700 (PDT) Received: from emu.fsl.noaa.gov (kelly@emu.fsl.noaa.gov [137.75.60.32]) by gatekeeper.fsl.noaa.gov (8.7.5/8.7.3) with ESMTP id FAA01433; Sun, 9 Jun 1996 05:32:22 GMT Message-Id: <199606090532.FAA01433@gatekeeper.fsl.noaa.gov> Received: by emu.fsl.noaa.gov (1.40.112.3/16.2) id AA131898336; Sat, 8 Jun 1996 23:32:16 -0600 Date: Sat, 8 Jun 1996 23:32:16 -0600 From: Sean Kelly <kelly@fsl.noaa.gov> To: jfieber@indiana.edu Cc: jkh@time.cdrom.com, chuckr@Glue.umd.edu, grog@lemis.de, doc@freebsd.org In-Reply-To: <Pine.NEB.3.93.960608201620.303V-100000@Fieber-John.campusview.indiana.edu> (message from John Fieber on Sat, 8 Jun 1996 20:25:54 -0500 (EST)) Subject: Re: How do I write this SGML stuff? Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk >>>>> "John" == John Fieber <jfieber@indiana.edu> writes: John> I just got the syllabus for a summer class I'm taking John> starting next week and was pleasntly surprised to discover John> that a whopping 45% of the grade is for "Developing an SGML John> DTD for course syllabi", So THAT'S your secret for devoting SO much time to FreeBSD. Make it part of your classwork! I *knew* I shouldn't have graduated ... :-( -- Sean Kelly NOAA Forecast Systems Laboratory kelly@fsl.noaa.gov Boulder Colorado USA http://www-sdd.fsl.noaa.gov/~kelly/