From owner-freebsd-doc Mon Feb 10 01:32:43 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id BAA21509 for doc-outgoing; Mon, 10 Feb 1997 01:32:43 -0800 (PST) Received: from upsmot01.msn.com (upsmot01.msn.com [204.95.110.78]) by freefall.freebsd.org (8.8.5/8.8.5) with SMTP id BAA21504 for ; Mon, 10 Feb 1997 01:32:39 -0800 (PST) Received: from upmajb02.msn.com (upmajb02.msn.com [204.95.110.74]) by upsmot01.msn.com (8.6.8.1/Configuration 4) with SMTP id BAA28480 for ; Mon, 10 Feb 1997 01:32:30 -0800 Date: Mon, 10 Feb 97 09:30:01 UT From: "Steve Danyleyko" Message-Id: To: freebsd-doc@FreeBSD.ORG Subject: Unix Sender: owner-doc@FreeBSD.ORG X-Loop: FreeBSD.org Precedence: bulk I have a small win95 peer to peer network with 6 workstations. All machines are pentium cpu's with 32mb ram. I use all 32-bit win95 applications except for a DOS accounting program run in win95. (It runs very well) Is there any reason I should be looking at Unix. Can I run Unix with win95 and DOS applications? Do I require a Sun, Oracle etc. computer for this. If I change to a unix system will my win95 operating system not be used at all or do the two work together. I am not interested in machined that dual boot. Thanks for your great web site. From owner-freebsd-doc Mon Feb 10 23:37:52 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id XAA05644 for doc-outgoing; Mon, 10 Feb 1997 23:37:52 -0800 (PST) Received: from cd4375.vuepp.sanet.sk ([193.87.43.45]) by freefall.freebsd.org (8.8.5/8.8.5) with SMTP id XAA05639; Mon, 10 Feb 1997 23:37:40 -0800 (PST) Received: by cd4375.vuepp.sanet.sk id AA05195 (5.67a/IDA-1.5); Tue, 11 Feb 1997 08:36:43 +0100 From: Zgebura Stefan Message-Id: <199702110736.AA05195@cd4375.vuepp.sanet.sk> Subject: Dynamic IP adress for PPP server. To: questions@freebsd.org Date: Tue, 11 Feb 97 8:36:42 MET Cc: docs@freebsd.org X-Mailer: ELM [version 2.3 PL11] Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk I am looking for some advice or documentation about the configuration PPP server and Dynamic IP adress. I am running PPP server using pppd with fixed IP adress and I want to run client with floating IP adress. I tried to configure bootpd, but it doesn't work properly. If a configure client with fixed IP adress everything working properly. Please if you have any experience please send me some advice. Thanks. **************************************************************** Stefan Zgebura tel./fax.:042-7-5215720 VUEPP Trencianska 55 E-mail:zgebura@vuepp.sanet.sk 824 80 Bratislava SLOVAKIA **************************************************************** From owner-freebsd-doc Tue Feb 11 13:26:43 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id NAA19698 for doc-outgoing; Tue, 11 Feb 1997 13:26:43 -0800 (PST) Received: from ifi.uio.no (0@ifi.uio.no [129.240.64.2]) by freefall.freebsd.org (8.8.5/8.8.5) with SMTP id NAA19688 for ; Tue, 11 Feb 1997 13:26:15 -0800 (PST) Received: from gymir.ifi.uio.no (2602@gymir.ifi.uio.no [129.240.64.27]) by ifi.uio.no with ESMTP (8.6.11/ifi2.4) id for ; Tue, 11 Feb 1997 22:24:23 +0100 Received: (from dag-erli@localhost) by gymir.ifi.uio.no ; Tue, 11 Feb 1997 22:24:21 +0100 (MET) Date: Tue, 11 Feb 1997 22:24:21 +0100 (MET) Message-Id: <199702112124.18867.gymir.ifi.uio.no@ifi.uio.no> Mime-Version: 1.0 From: =?iso-8859-1?Q?=22Dag?= -Erling Coidan =?iso-8859-1?Q?Sm=F8rgrav=22?= To: freebsd-doc@freebsd.org Subject: Bug report: FreeBSD makes invalid partition table entries Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk My FreeBSD isntallation isn't on the net, so I couldn't use send-pr. I did, however, use the template so I hope you can use this: >Submitter-Id: current-users >Originator: Dag-Erling Smoergrav >Organization: University of Oslo >Confidential: no >Synopsis: FreeBSD partition entries are invalid >Severity: non-critical >Priority: low >Category: i386 >Release: FreeBSD 2.1-STABLE i386 >Class: sw-bug >Environment: I have not checked for this bug on other computers than mine, but I suppose it applies to all i386-based computers. >Description: There is apparently an off-by-one error in the code that creates the FreeBSD partition during installation. The length field in the partition table is correct; however the ending-cylinder/sector field is low by one cylinder. This is a little hairy because actually FDISK doesn't give a damn, the BIOS doesn't give a damn, DOS doesn't give a damn and none of my own software (I write disk utilities for a hobby :) ) gives a damn. PowerQuest PartitionMagic, however, *does* give a damn, and will report a "partition table error #101" for the relevant disk. I verified that the error was indeed FreeBSD's thus: I read the MBR into a file, and vgrepped its contents. The disk where I keep FreeBSD is an ST3144A (the first widespread 1-inch IDE drive to hit the market, back in '91-'92) with 1001 cylinders, 15 heads and 17 sectors per track. The FreeBSD partition was listed with a starting position of 1/0/1 and an ending position of 999/14/17 (the first cylinder contains my homemade multi-booter) Now the last cylinder is numbered 1000, so either the FreeBSD partition was one cylinder short, or the entry was wrong. Since PQMagic had reported an error, I checked the length field, which was 255,000 (1000*15*17). Now according to the start and stop fields this should be 254,745 (999*15*17). I set it to that value, wrote the MBR back and booted FreeBSD, which complained that the partition was smaller than the slices it held. I rebooted DOS, changed the length back to 255,000 and the ending position to 1000/14/17, wrote back and rebooted FreeBSD, which chirped happily. I also checked the disk with PQMagic which no longer reported any errors. This seems to indicate that the length field was right and the ending position wrong, and that FreeBSD only cares about the start position and the length (which explains why the off-by-one error doesn't register). >How-To-Repeat: Install FreeBSD :) >Fix: See "Description" for an explanation of how I worked around the bug. For a more permanent fix, I suppose FreeBSD's disk partitioning utility needs a brush-up. I looked through pfdisk.c (dunno if it's the right program, though) but the readability is like something I'd write while drunk and blind and with both hands tied behind my back, so I gave up trying to track down the error (let alone fixing it). From owner-freebsd-doc Thu Feb 13 04:37:06 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id EAA07996 for doc-outgoing; Thu, 13 Feb 1997 04:37:06 -0800 (PST) Received: from www.communique.no (www.communique.no [193.212.204.33]) by freefall.freebsd.org (8.8.5/8.8.5) with SMTP id EAA07987 for ; Thu, 13 Feb 1997 04:37:03 -0800 (PST) Received: from www (193.212.204.33) by www.communique.no (EMWAC SMTPRS 0.80) with SMTP id ; Thu, 13 Feb 1997 13:43:09 +0100 Message-ID: <33030C5A.534F@communique.no> Date: Thu, 13 Feb 1997 13:43:06 +0100 From: Are Bryne X-Mailer: Mozilla 2.0 (WinNT; I) MIME-Version: 1.0 To: freebsd-doc@freebsd.org Subject: Updating 'mirror' http-servers X-URL: http://www.freebsd.org/mailto.html Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk Hello, I wondered whether you could see through your http-mirrors. Several are outdated, and that means I have to consistently use www.freebsd.org to get the correct info. This applies for example to both the swedish and finnish mirrors. Otherwise, thanks a lot for your efforts and handiwork! Regards, Are Bryne From owner-freebsd-doc Thu Feb 13 07:21:35 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id HAA17087 for doc-outgoing; Thu, 13 Feb 1997 07:21:35 -0800 (PST) Received: from starfire.mn.org (root@starfire.skypoint.net [199.86.32.187]) by freefall.freebsd.org (8.8.5/8.8.5) with ESMTP id HAA17082 for ; Thu, 13 Feb 1997 07:21:31 -0800 (PST) Received: from dexter.starfire.mn.org (john@localhost.starfire.mn.org [127.0.0.1]) by starfire.mn.org (8.8.5/1.1) with SMTP id JAA20042 for ; Thu, 13 Feb 1997 09:21:23 -0600 (CST) Message-ID: <33033172.41C67EA6@starfire.mn.org> Date: Thu, 13 Feb 1997 09:21:22 -0600 From: John Lind X-Mailer: Mozilla 3.01 (X11; I; FreeBSD 2.1.0-RELEASE i386) MIME-Version: 1.0 To: freebsd-doc@FreeBSD.ORG Subject: FreeBSD handbook section 10.5.5.3 SCSI (tape) drives (from the on-line version at www.freebsd.org) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Sender: owner-doc@FreeBSD.ORG X-Loop: FreeBSD.org Precedence: bulk In the paragraph on "Hewlett-Packard HP C1553A Autoloading DDS2", it says that the boot message identifier is "", which is incomplete and incorrect. On our system, dmesg shows me "HP C1553A 9503". Also, the script for changing tapes as it appears has a syntax error in that the trailing quote on the first echo command in the usage function is missing. Other than that, the script works, and I was very happy to find it! Do we know who contributed this? I'd like to open a dialogue with him (any anyone else interested) for direct driver support for this functionality. BTW, I sent in some additional information a week or so ago about a kink to HP pages that were out of date and a replacment. I didn't get an acknowledgement and the bad link is still in place on the on-line handbook, so I hope that information did get processed somehwere. -- John Lind, Starfire Consulting Services E-mail: john@starfire.MN.ORG USnail: PO Box 17247, Mpls MN 55417 From owner-freebsd-doc Thu Feb 13 16:53:24 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id QAA23641 for doc-outgoing; Thu, 13 Feb 1997 16:53:24 -0800 (PST) Received: from ux8.cso.uiuc.edu (root@ux8.cso.uiuc.edu [128.174.5.44]) by freefall.freebsd.org (8.8.5/8.8.5) with ESMTP id QAA23635 for ; Thu, 13 Feb 1997 16:53:17 -0800 (PST) Received: from maverick (maverick.isdn.uiuc.edu [192.17.18.51]) by ux8.cso.uiuc.edu (8.8.5/8.8.5) with SMTP id SAA01432 for ; Thu, 13 Feb 1997 18:53:04 -0600 (CST) Message-Id: <3.0.32.19970213190100.009e2860@students.uiuc.edu> X-Sender: kueh@students.uiuc.edu X-Mailer: Windows Eudora Pro Version 3.0 (32) Date: Thu, 13 Feb 1997 19:01:01 -0600 To: freebsd-doc@FreeBSD.ORG From: Anthony Kueh Subject: FreeBSD handbook in Postscript? Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Sender: owner-doc@FreeBSD.ORG X-Loop: FreeBSD.org Precedence: bulk Hi, I was wondering if the FreeBSD handbook is available in a postscript format so that I can get a hard copy of it rather than trying print out HTML pages... Thanks, Tony +------------------------------------------------------------+ Anthony Kueh Department of Computer Sciences kueh@uiuc.edu Univ. of Illinois-Urbana/Champaign Nearly all men can stand adversity, but if you want to test a man's character, give him power. -- Abraham Lincoln +------------------------------------------------------------+ From owner-freebsd-doc Thu Feb 13 17:30:16 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id RAA25671 for doc-outgoing; Thu, 13 Feb 1997 17:30:16 -0800 (PST) Received: from mail.cs.tu-berlin.de (root@mail.cs.tu-berlin.de [130.149.17.13]) by freefall.freebsd.org (8.8.5/8.8.5) with ESMTP id RAA25664 for ; Thu, 13 Feb 1997 17:30:11 -0800 (PST) Received: from campa.panke.de (anonymous213.ppp.cs.tu-berlin.de [130.149.17.213]) by mail.cs.tu-berlin.de (8.8.5/8.8.5) with SMTP id CAA03777; Fri, 14 Feb 1997 02:15:11 +0100 (MET) Received: (from wosch@localhost) by campa.panke.de (8.6.12/8.6.12) id CAA00906; Fri, 14 Feb 1997 02:14:41 +0100 Date: Fri, 14 Feb 1997 02:14:41 +0100 From: Wolfram Schneider Message-Id: <199702140114.CAA00906@campa.panke.de> To: Wolfram Schneider Cc: CVS-committers@freefall.freebsd.org, doc@freebsd.org Subject: cvs commit: src/share/mk bsd.doc.mk In-Reply-To: <199702130326.TAA14812@freefall.freebsd.org> References: <199702130326.TAA14812@freefall.freebsd.org> 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 made a snapshot of the (Free-/4.4)BSD documentation in HTML, see http://www.de.freebsd.org/~wosch/doc/ Wolfram Schneider writes: >wosch 97/02/12 19:26:03 > > Modified: share/mk bsd.doc.mk > Log: > Support PRINTERDEVICE "html" using the troff translator unroff(1). > It works in most cases, but not all (e.g. nvi). From owner-freebsd-doc Thu Feb 13 18:31:04 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id SAA28906 for doc-outgoing; Thu, 13 Feb 1997 18:31:04 -0800 (PST) Received: from fallout.campusview.indiana.edu (fallout.campusview.indiana.edu [149.159.1.1]) by freefall.freebsd.org (8.8.5/8.8.5) with ESMTP id SAA28881; Thu, 13 Feb 1997 18:30:54 -0800 (PST) Received: from localhost (jfieber@localhost) by fallout.campusview.indiana.edu (8.8.5/8.8.5) with SMTP id VAA11809; Thu, 13 Feb 1997 21:29:08 -0500 (EST) Date: Thu, 13 Feb 1997 21:29:08 -0500 (EST) From: John Fieber To: Wolfram Schneider cc: doc@freebsd.org, www@freebsd.org Subject: Re: cvs commit: src/share/mk bsd.doc.mk In-Reply-To: <199702140114.CAA00906@campa.panke.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 Fri, 14 Feb 1997, Wolfram Schneider wrote: > I made a snapshot of the (Free-/4.4)BSD documentation in HTML, see > http://www.de.freebsd.org/~wosch/doc/ Would you be interested in making this a normal part of the web pages? If it is more or less a "make PRINTERDEVICE=html" it should be fairly trivial, although the cvs updates of the www build directory are a bit bizzare because there is stuff checked out from different places in the repository. -john From owner-freebsd-doc Thu Feb 13 19:23:43 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id TAA02070 for doc-outgoing; Thu, 13 Feb 1997 19:23:43 -0800 (PST) Received: from time.cdrom.com (time.cdrom.com [204.216.27.226]) by freefall.freebsd.org (8.8.5/8.8.5) with ESMTP id TAA02063 for ; Thu, 13 Feb 1997 19:23:41 -0800 (PST) Received: from time.cdrom.com (localhost [127.0.0.1]) by time.cdrom.com (8.8.5/8.6.9) with ESMTP id TAA25886 for ; Thu, 13 Feb 1997 19:23:39 -0800 (PST) To: doc@freebsd.org Subject: Date and release version of FreeBSD Handbook Date: Thu, 13 Feb 1997 19:23:39 -0800 Message-ID: <25882.855890619@time.cdrom.com> From: "Jordan K. Hubbard" Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk For some time, we've proclaimed in the first paragraph of the Handbook that it was last revised in December 1996 and contained instructions for 2.1.6. Now that it's February, soon to be March, and 2.1.6 is history about to be replaced by 2.1.7, I'd like to humbly suggest that we simply *remove* this version information and call the Handbook what it always has been - a fairly generic document for no release in particular, except for certain very specific instances (which should simply be noted in each case). That would be one less thing to forget each time and we could stop declaring that the Handbook was less often updated than it really is. Comments? Jordan From owner-freebsd-doc Fri Feb 14 04:17:04 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id EAA29257 for doc-outgoing; Fri, 14 Feb 1997 04:17:04 -0800 (PST) Received: from mail.cs.tu-berlin.de (root@mail.cs.tu-berlin.de [130.149.17.13]) by freefall.freebsd.org (8.8.5/8.8.5) with ESMTP id EAA29221; Fri, 14 Feb 1997 04:16:48 -0800 (PST) Received: from ole.cs.tu-berlin.de (wosch@ole.cs.tu-berlin.de [130.149.22.3]) by mail.cs.tu-berlin.de (8.8.5/8.8.5) with ESMTP id NAA04366; Fri, 14 Feb 1997 13:16:44 +0100 (MET) From: Wolfram Schneider Received: (from wosch@localhost) by ole.cs.tu-berlin.de (8.8.5/8.8.4) id NAA07751; Fri, 14 Feb 1997 13:16:43 +0100 (MET) Date: Fri, 14 Feb 1997 13:16:43 +0100 (MET) Message-Id: <199702141216.NAA07751@ole.cs.tu-berlin.de> To: John Fieber Cc: doc@freebsd.org, www@freebsd.org Subject: Re: cvs commit: src/share/mk bsd.doc.mk In-Reply-To: References: <199702140114.CAA00906@campa.panke.de> 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 Fri, 14 Feb 1997, Wolfram Schneider wrote: > >> I made a snapshot of the (Free-/4.4)BSD documentation in HTML, see >> http://www.de.freebsd.org/~wosch/doc/ > >Would you be interested in making this a normal part of the web >pages? If it is more or less a "make PRINTERDEVICE=html" it >should be fairly trivial, Yes, it was basically a 'make PRINTERDEVICE=html' and a 'make PRINTERDEVICE=html DESTDIR=/foo -k install' http://www.de.freebsd.org/~wosch/doc/ is 4MB big (gzip'd 1MB). Some documents should be changed so unroff split them in smaller parts and create a table of contents. E.g. http://www.de.freebsd.org/~wosch/doc/papers/malloc.html looks nice and http://www.de.freebsd.org/~wosch/doc/psd/21.ipc/paper.html is 150KB large and bad formatted ;-( >although the cvs updates of the www >build directory are a bit bizzare because there is stuff checked >out from different places in the repository. Right, the SRCDIR= ${.CURDIR}/../../../../bin/csh/USD.doc etc. is a problem, I did a $ cvs co `find share/doc -name Makefile | xargs egrep SRCDIR= | awk '{print $NF}' | sed 's/.*\.\.\///' | sort -u | grep / ` to checkout bin/csh/USD.doc etc. directories. Wolfram From owner-freebsd-doc Fri Feb 14 04:41:13 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id EAA02081 for doc-outgoing; Fri, 14 Feb 1997 04:41:13 -0800 (PST) Received: from mail.cs.tu-berlin.de (root@mail.cs.tu-berlin.de [130.149.17.13]) by freefall.freebsd.org (8.8.5/8.8.5) with ESMTP id EAA02077; Fri, 14 Feb 1997 04:41:10 -0800 (PST) Received: from ole.cs.tu-berlin.de (wosch@ole.cs.tu-berlin.de [130.149.22.3]) by mail.cs.tu-berlin.de (8.8.5/8.8.5) with ESMTP id NAA05575; Fri, 14 Feb 1997 13:40:46 +0100 (MET) From: Wolfram Schneider Received: (from wosch@localhost) by ole.cs.tu-berlin.de (8.8.5/8.8.5) id NAA08015; Fri, 14 Feb 1997 13:40:45 +0100 (MET) Date: Fri, 14 Feb 1997 13:40:45 +0100 (MET) Message-Id: <199702141240.NAA08015@ole.cs.tu-berlin.de> To: Arne Steinkamm Cc: thomas@ghpc8.ihf.rwth-aachen.de (Thomas Gellekum), tphilips@cedar.netten.net, freebsd-chat@FreeBSD.org, doc@FreeBSD.org Reply-to: doc@FreeBSD.org Subject: Re: Is there a manpage to html converter for freebsd? In-Reply-To: <199702140844.JAA12253@oldman.steinkamm.com> References: <199702140712.IAA16802@ghpc6.ihf.rwth-aachen.de> <199702140844.JAA12253@oldman.steinkamm.com> 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 Arne Steinkamm writes: >> > is there a manpage to html converter for freebsd? if so, where might i >> > find it? >The default Homepage installed during the installation of a BSD/OS >(yes, the commercial one) has such a nice thing. >It's a cgi bin written from Sanders and Polk (@bsdi.com). >There's no copyright mentioned in the file but i'm not sure >about this.. It is copyright by BSDI. A slightly older version is distributed for free with Plexus (see http://www.earth.com/). I modified the free version for FreeBSD. See http://www.de.freebsd.org/de/cgi/man.cgi This cgi script support man pages from FreeBSD (all releases), NetBSD, OpenBSD, 386BSD, Unix Seventh Edition, and XFree86 3.2. Wolfram From owner-freebsd-doc Sat Feb 15 12:23:35 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id MAA11863 for doc-outgoing; Sat, 15 Feb 1997 12:23:35 -0800 (PST) Received: from fallout.campusview.indiana.edu (fallout.campusview.indiana.edu [149.159.1.1]) by freefall.freebsd.org (8.8.5/8.8.5) with ESMTP id MAA11847 for ; Sat, 15 Feb 1997 12:23:19 -0800 (PST) Received: from localhost (jfieber@localhost) by fallout.campusview.indiana.edu (8.8.5/8.8.5) with SMTP id PAA19290; Sat, 15 Feb 1997 15:23:18 -0500 (EST) Date: Sat, 15 Feb 1997 15:23:18 -0500 (EST) From: John Fieber To: doc@freebsd.org cc: "Jordan K. Hubbard" Subject: Re: cvs commit: www/data security.sgml In-Reply-To: <11604.856026076@time.cdrom.com> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk I suggested to Jordan that his recent "FreeBSD" security document, which was added to the web server as an HTML page, should be written up as a tutorial using Docbook. He responds with: > Is docbook something I want to employ *only* for tutorials and > handbook pieces (when the handbook goes docbook, that is), and if this > had stayed up where auditors.sgml is, would the format in which I > originally wrote it be considered "correct?" This HTML-wrapped-in-SGML > stuff we have up at the top level of the web page hierarchy still sort > of confuses me, I'll admit, and I'm not sure to what degree it's wise or > allowable to use more specialized SGML features in there, or even what > "styles" are appropriate for which areas of the doc tree at the > moment. Maybe a short paragraph, sent to www for the benefit of > everyone, during these transitionary times? :-) Since the web pages have recently become a much more communal project than they were, some explanation is definately in order! Two versions are supplied. Pick the one that matches your attention span. Those opting out of the long version would be advised to skip to the end for the summary however. :) Short version: Any document that will only see the light of day in the context of a (the) web server is best written in HTML. Any document that might have a useful life in any context outside the web serve should probably not be written in HTML. The viable alternatives are linuxdoc (discouraged) and docbook (encouraged). The primary role of documents written directly in HTML is to provide an access path to these documents. Long version: An HTML file is the standard web transaction unit. For a variety of reasons, writing and maintaining documents in transaction unit chunks is a chore unless the conceptual content fits neatly in one, a very small handful of transactional units. Despite claims to the contrary, and its original intent, HTML is primairly a layout markup language with hypertext features. Maintaining layout consistency with visual markup languages is a chore, particularly if you don't have any "macro" facility to bundle up frequently used layout constructs under a single name. Layout markup languages limit the degree to which documents can *usefully* be transported into other contexts, e.g. print. As an example, a single, but large, conceptual document may be broken into many transaction units. The transaction units will contain two distinct categories of links: hypertext links serving as cross references, and navigational links that parallel the document's structure. The latter are instantiated in very different ways in print versus on-line documents, but if you use HTML, the structure links are hardwired and indistinguishable (reliably) from hypertext links. Going from this to print is a hassles, and can be completely avoided by choosing a master format more suitable to the document, and generating derivatives from that. On the other hand, the spirit of hypertext is all about doing things that cannot be done in print, so what is the problem? Why bother with these legacy "linear" document structures? It turns out that humans simply do not deal well with looking at a single transaction unit if do not have some mental construction of its structural context. So, while we can take full advantage of hypertext links between two points in on-line document, it is critical to provide cues not only where a link goes to before the user follows it, but to provide cues of the intervening "space". By adopting familar document structures, we enable the reader to use their highly tuned schemata for dealing with information. Pick up a novel, a technical manual, a newspaper, a research journal, a magazine and you immediately and unconsciously engage reading strategies that are highly optimized for each. The structure of ad-hoc hypertext can never provide the user with such cues. HTML, by focusing the authoring on the *transactional* unit rather than the *conceptual* unit, makes creating coherent, familar structures out of numerous transactional units unnecessairly difficult. Now, with that as a background, condisder the content of the FreeBSD web site and documentation. A bulk of the site is technical documentation in a traditional sense and *should* leverage the familiar technical manual structure. Since this is hard to do well directly in HTML, I suggest that any documentation be written in something more suitable such as docbook or linuxdoc. This lets the author focus on the conceptual structure of the document, and leave the transactional structure to a mechanical process. The role of authoring in HTML is essentially to provide a route *to* the documents; a directory service of sorts (but with the obligatory web glitz). Basically, if there is substantial content and you are doing it directly in HTML rather than generating HTML from a more suitable format, something is wrong. :) Dropping down to technical issues, the HTML source that makes up the web pages leverages SGML features that are not supported by current web browsers. Basically, involves defining entities for "boilerplate" text which can be included in many HTML documents. Currently various stylistic elements such as standard page headers, footers, colors, graphics and the like are defined in one location and in HTML documents using entities. Since web browsers cannot deal with arbitrary entities, the build process runs each file through an SGML normalizer which resolves all entity references (and validates the markup in the process). You can think of it as operating like the C preprocessor. The end product is HTML that fully conforms to whatever HTML spec we choose (currently HTML 3.2) that any respectable browser should render in a useful fashion. For a more rambling description with examples, look at: http://fallout.campusview.indiana.edu/~jfieber/sum1996/l577 About the state of linuxdoc and docbook. The linuxdoc DTD was derived from a dtd called QWERTZ which is essentially an SGMLized LaTeX. Most of the tags are directly derived from their corresponding LaTeX control sequences. While linuxdoc allows reasonably graceful handling of large documents (eg. the FreeBSD handbook), its typesetting heritage shows through strongly in the abundance of visual markup tags and the lack of descriptive markup beyond ultra-general things such as sectioning tags (chapter, sect, etc.). Also, the DTD is poorly implemented. It makes heavy use of tag minimization and short references which I have observed as the source of many markup errors. What linuxdoc has going for it (currently) is easy generation of servicable HTML, and groff (and consequently postscript, text and in theory, PCL and DVI). The Docbook DTD, on the other hand, was designed explicitly for software documentation. It offers rich options for descriptive markup--so rich as to be potentially overwhelming at times. The implementation of the DTD is truly exemplary, and it is actively supported by the likes of Fujitsu, Microsoft, DEC, Sun, SCO, O'Reilly, ArborText and SoftQuad. The downside is that generation of derivative formats is not as far along as linuxdoc. Decent HTML generation is possible for relatively small documents only, as I have yet to decide on how best to break up large documents into transaction units. The method used for linuxdoc works, but is fairly crude and I'd like to do a better job with Docbook. Docbook to groff is non-existant at the moment, although usable RTF can be generated using a DSSSL style sheet. As for specific FreeBSD documents, semi-automatic linuxdoc to docbook conversion is a current reality, although I have not (and don't plan to) put it in FreeBSD-current. What is holding up converting the handbook and FAQ is simply the lack of groff support and breaking up large documents. However, I don't think either of these should stand in the way of creating smaller documents using docbook. Changes to the handbook should be made to the existing copy, but I would like to see completely new additions written as tutorials to be integrated at a later date. I am also considering splitting the handbook into a couple smaller volumes. In summary, our web services are composed of: Documentation: FAQ, Handbook, tutorials authored in docbook and/or linuxdoc, converted to HTML. This should shortly be expanded to include the roff documents in the doc tree, converted to HTML. Database: Mailing list archives, web site searching, GNATS, cvs repository, ports collection. This is all more or less automatically generated from non-html sources as the documentation is. HTML: Provides small bits of content. Mostly serves as an access mechanism to the Documentation and Database services. -john From owner-freebsd-doc Sat Feb 15 13:25:54 1997 Return-Path: Received: (from root@localhost) by freefall.freebsd.org (8.8.5/8.8.5) id NAA13942 for doc-outgoing; Sat, 15 Feb 1997 13:25:54 -0800 (PST) Received: from gvr.win.tue.nl (root@gvr.win.tue.nl [131.155.210.19]) by freefall.freebsd.org (8.8.5/8.8.5) with ESMTP id NAA13933 for ; Sat, 15 Feb 1997 13:25:46 -0800 (PST) Received: (from guido@localhost) by gvr.win.tue.nl (8.8.5/8.8.2) id WAA17110 for freebsd-doc@FreeBSD.ORG; Sat, 15 Feb 1997 22:25:42 +0100 (MET) From: Guido van Rooij Message-Id: <199702152125.WAA17110@gvr.win.tue.nl> Subject: My pgp key To: freebsd-doc@FreeBSD.ORG Date: Sat, 15 Feb 1997 22:25:41 +0100 (MET) X-Mailer: ELM [version 2.4ME+ PL28 (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 Hi, Could you add the following key to the handbook as my pgp key? Thanks, -Guido -----BEGIN PGP PUBLIC KEY BLOCK----- Version: 2.6.2 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 mgDVjsHaYOx3EXF0nnDmtXurGioEmW1J =mSvM -----END PGP PUBLIC KEY BLOCK-----