From owner-freebsd-doc Mon Mar 27 13:17:59 1995 Return-Path: doc-owner Received: (from majordom@localhost) by freefall.cdrom.com (8.6.10/8.6.6) id NAA08036 for doc-outgoing; Mon, 27 Mar 1995 13:17:59 -0800 Received: from fslg8.fsl.noaa.gov (fslg8.fsl.noaa.gov [137.75.131.171]) by freefall.cdrom.com (8.6.10/8.6.6) with SMTP id NAA08028 for ; Mon, 27 Mar 1995 13:17:51 -0800 Received: by fslg8.fsl.noaa.gov (5.57/Ultrix3.0-C) id AA18147; Mon, 27 Mar 95 21:17:35 GMT Received: by junco.fsl.noaa.gov (1.38.193.4/SMI-4.1 (1.38.193.4)) id AA09095; Mon, 27 Mar 1995 14:17:38 -0700 Date: Mon, 27 Mar 1995 14:17:38 -0700 From: kelly@fsl.noaa.gov (Sean Kelly) Message-Id: <9503272117.AA09095@junco.fsl.noaa.gov> To: ghelmer@alpha.dsu.edu Cc: freebsd-doc@freefall.cdrom.com In-Reply-To: (message from Guy Helmer on Sat, 25 Mar 1995 20:34:21 -0600 (CST)) Subject: Re: Dialup how-to Sender: doc-owner@freebsd.org Precedence: bulk >>>>> "Guy" == Guy Helmer writes: Guy> Anyway, a rough start can be viewed at Guy> "http://www.dsu.edu/~ghelmer/FreeBSD/dialup.html". Please Guy> check it over and mail me comments or suggestions Guy> (good/bad/toss it!). It looks great! The document has a good conversational style that facilitates understanding. And it's really quite thorough. I'm not sure how deep an edit/commentary you wanted, but before I could take a look, I ran into a few questions of my own for the doc group at large: is there a FreeBSD doc style sheet? If not, there needs to be lest we all start writing in wildly different styles. Of course, if this dialup document is meant to stand on its own, then nevermind! So, with that, here's my commentary: In general, every heading should have text following it, instead of an immediate subheading. It should be more than just mere metadiscourse: ``This section describes the prerequisites.'' You can make that contain overview of what's in the section so that readers will know if they can skip it. 2 Prerequisites In this section, we describe what you need to set up with your system before you can enable dialup logins. This section tells you how to ... 2.1 FreeBSD Versions Also, if this is to be included in a large multiauthor FreeBSD manual, you should replace the first person with the third while still maintaining the conversational style. In 2.1, FreeBSD version, you might want to mention that what follows applies to 2.x as well. Although that's implicit from the paragraph, 2.x users will feel more comfortable that the document applies if they actually see 2.x in the text. In 2.2, rather than make users buy a serial comms book, why not go ahead and give brief definitions? If this is part of a FreeBSD manual, you could have links to a glossary section. In 2.3, second paragraph, first sentence, replace `on the end' with `each end'. In the last sentence, replace `wire' with `wired'. For the pathologically inept, you might also want to mention that you don't need a serial cable for an internal modem. In the fourth paragraph, replace `refernce' with `reference'. In the same sentence, omit `to look up the commands.' Just end the sentence at `handy'. In the last paragraph, last sentence, add `active' after `If the system has many ...' In 4, first paragraph, second sentence, omit hyphen from `multi-port'. In the fifth and six paragraphs, you might want to mention what the paths are for 2.x; or just forget about earlier versions and only describe how things exist in 2.x. In the eighth paragraph, omit `like the BB2016' which we've seen too many times already from the last sentence. In 6, third paragraph, last sentence, insert `get' or `receive' in `... on a low-speed connection should better interactive response ...' In 6.2, mention that you need to send a HUP to init to get it to reread /etc/ttys. In 6.3, on stty commands for FreeBSD 1.1, does that even work? Don't serial ports go back to their default settings once they're closed (the stty will open, set crtscts, then close the port)? Overall, the order seems a bit off: shouldn't it be Intro Prerequisites Setting up your modem (Modem settings) Configuring your kernel (Kernel configuration) Serial device special files (Device special files) How logins work (Overview) Configuring for dialup logins (Config files) Troubleshooting Acknowledgements You might want to include a step-by-step overview (using an ordered list) at the beginning the document so that more experienced users can quickly edit the needed files and get going. Each step can link to what you've written now so that beginners can get the needed details: To enable dialup logins on your system, do the following: 1 Hook your up modem 2 Configure your kernel 3 Make device special files 4 Set your modem's communication parameters 5 Pick locked-speed or matching-speed configuration 6 Add an entry in /etc/ttys 7 kill -1 1 8 Test it out! Also, make commands that the user types (like /sbin/dmesg|grep sio) stand out on a line by themselves. This makes it easier to paste into an xterm window. Finally, if this is to be part of a larger user manual, factor out all the stuff on kernel config, device special files, cables, FreeBSD version, terminology, etc. and focus on what the user came here to read: enabling dialup logins. The rest of that stuff should be available as links, but not part of the document that one would read straight through. This modularity helps people who want to link to your document as well. For example, if I'm writing a section on setting up a PPP server, I can plant a link to yours when I need to tell my reader that s/he needs to first enable dial up logins. I can reuse the troubleshooting and kernel config sections as well through links. Please feel free to ignore as much as my commentary as you feel doesn't apply. And thanks for the writing! --k From owner-freebsd-doc Tue Mar 28 12:03:06 1995 Return-Path: doc-owner Received: (from majordom@localhost) by freefall.cdrom.com (8.6.10/8.6.6) id MAA25727 for doc-outgoing; Tue, 28 Mar 1995 12:03:06 -0800 Received: from alpha.dsu.edu (ghelmer@alpha.dsu.edu [138.247.32.12]) by freefall.cdrom.com (8.6.10/8.6.6) with ESMTP id MAA25721 for ; Tue, 28 Mar 1995 12:03:02 -0800 Received: (from ghelmer@localhost) by alpha.dsu.edu (8.6.11/8.6.11) id OAA12402; Tue, 28 Mar 1995 14:01:52 -0600 Date: Tue, 28 Mar 1995 14:01:50 -0600 (CST) From: Guy Helmer To: Sean Kelly cc: freebsd-doc@freefall.cdrom.com Subject: Doc project guidance, was Re: Dialup how-to In-Reply-To: <9503272117.AA09095@junco.fsl.noaa.gov> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: doc-owner@freebsd.org Precedence: bulk On Mon, 27 Mar 1995, Sean Kelly wrote: > >>>>> "Guy" == Guy Helmer writes: > > Guy> Anyway, a rough start can be viewed at > Guy> "http://www.dsu.edu/~ghelmer/FreeBSD/dialup.html". Please > Guy> check it over and mail me comments or suggestions > Guy> (good/bad/toss it!). > > It looks great! The document has a good conversational style that > facilitates understanding. And it's really quite thorough. > > I'm not sure how deep an edit/commentary you wanted, but before I > could take a look, I ran into a few questions of my own for the doc > group at large: is there a FreeBSD doc style sheet? If not, there > needs to be lest we all start writing in wildly different styles. I think we've been writing in our own styles -- I don't know that a common style has been considered. It was hard enough deciding on a common source format (linuxdoc DTD) :-) BTW, I appreciated the depth of your commentary. It brings up a number of issues on which I would like to have some guidance. > Of course, if this dialup document is meant to stand on its own, then > nevermind! No, I hope that if it is acceptable, it would be included in the FreeBSD Doc How-To pages. > So, with that, here's my commentary: > [... I've edited out the parts specific to improvements in my dialup > doc ...] > > Also, if this is to be included in a large multiauthor FreeBSD manual, > you should replace the first person with the third while still > maintaining the conversational style. Done, and this is probably important for all our docs. > ahead and give brief definitions? If this is part of a FreeBSD > manual, you could have links to a glossary section. Hmm - shall we develop a "Glossary" page for the FreeBSD How-To docs? > You might want to include a step-by-step overview (using an ordered > list) at the beginning the document so that more experienced users can > quickly edit the needed files and get going. Each step can link to > what you've written now so that beginners can get the needed details: Perhaps this is another good idea for all how-to docs. > Also, make commands that the user types (like /sbin/dmesg|grep sio) > stand out on a line by themselves. This makes it easier to paste into > an xterm window. Ditto. > Finally, if this is to be part of a larger user manual, factor out all > the stuff on kernel config, device special files, cables, FreeBSD > version, terminology, etc. and focus on what the user came here to > read: enabling dialup logins. The rest of that stuff should be > available as links, but not part of the document that one would read > straight through. This modularity helps people who want to link to > your document as well. For example, if I'm writing a section on > setting up a PPP server, I can plant a link to yours when I need to > tell my reader that s/he needs to first enable dial up logins. I can > reuse the troubleshooting and kernel config sections as well through > links. OK, so perhaps we need: 1) Kernel How-To: config, build, and install 2) Device Special Files Reference: MAKEDEV; file permissions 3) Glossary 4) Index There was quite a bit of overlap between my SLIP Server how-to and this dialup how-to in the kernel area. I'm inclined to leave the dialup how-to as is until the the kernel how-to and device special files reference are ready. If anyone has comments or would like to help/take on some of these things, please let me know. Otherwise, I'll start tackling them myself as time permits. > Please feel free to ignore as much as my commentary as you feel > doesn't apply. And thanks for the writing! Thanks for your comments! > --k Guy Helmer, Dakota State University Computing Services - ghelmer@alpha.dsu.edu From owner-freebsd-doc Tue Mar 28 12:46:08 1995 Return-Path: doc-owner Received: (from majordom@localhost) by freefall.cdrom.com (8.6.10/8.6.6) id MAA27374 for doc-outgoing; Tue, 28 Mar 1995 12:46:08 -0800 Received: from fslg8.fsl.noaa.gov (fslg8.fsl.noaa.gov [137.75.131.171]) by freefall.cdrom.com (8.6.10/8.6.6) with SMTP id MAA27368 for ; Tue, 28 Mar 1995 12:46:06 -0800 Received: by fslg8.fsl.noaa.gov (5.57/Ultrix3.0-C) id AA26145; Tue, 28 Mar 95 20:45:57 GMT Received: by junco.fsl.noaa.gov (1.38.193.4/SMI-4.1 (1.38.193.4)) id AA25220; Tue, 28 Mar 1995 13:45:58 -0700 Date: Tue, 28 Mar 1995 13:45:58 -0700 From: kelly@fsl.noaa.gov (Sean Kelly) Message-Id: <9503282045.AA25220@junco.fsl.noaa.gov> To: ghelmer@alpha.dsu.edu Cc: freebsd-doc@freefall.cdrom.com In-Reply-To: (message from Guy Helmer on Tue, 28 Mar 1995 14:01:50 -0600 (CST)) Subject: Re: Doc project guidance, was Re: Dialup how-to Sender: doc-owner@freebsd.org Precedence: bulk >>>>> "Guy" == Guy Helmer writes: Guy> I think we've been writing in our own styles -- I don't know Guy> that a common style has been considered. It was hard enough Guy> deciding on a common source format (linuxdoc DTD) :-) I'm supposedly on the doc team (according to an email message from Jordan some month(s) ago), but I had no idea linuxdoc was to be the common source format. Heck, I didn't even realize there was a freebsd-doc list until a few weeks ago! We need up writers' resource repository, perhaps on the web, including the style sheet, linuxdoc (sources or perhaps packaged up for pkg_add), plus working versions of our docs for testing, browsing, etc. This might be a good task for the docmaster! :-) --k From owner-freebsd-doc Tue Mar 28 13:27:10 1995 Return-Path: doc-owner Received: (from majordom@localhost) by freefall.cdrom.com (8.6.10/8.6.6) id NAA28519 for doc-outgoing; Tue, 28 Mar 1995 13:27:10 -0800 Received: from grendel.csc.smith.edu (grendel.csc.smith.edu [131.229.222.23]) by freefall.cdrom.com (8.6.10/8.6.6) with ESMTP id NAA28513 for ; Tue, 28 Mar 1995 13:27:04 -0800 Received: from localhost (jfieber@localhost) by grendel.csc.smith.edu (8.6.5/8.6.5) id QAA23241; Tue, 28 Mar 1995 16:27:41 -0500 From: jfieber@cs.smith.edu (John Fieber) Message-Id: <199503282127.QAA23241@grendel.csc.smith.edu> Subject: Re: Doc project guidance, was Re: Dialup how-to To: kelly@fsl.noaa.gov (Sean Kelly) Date: Tue, 28 Mar 1995 16:27:41 -0500 (EST) Cc: doc@freebsd.org In-Reply-To: <9503282045.AA25220@junco.fsl.noaa.gov> from "Sean Kelly" at Mar 28, 95 01:45:58 pm Content-Type: text Content-Length: 1675 Sender: doc-owner@freebsd.org Precedence: bulk Sean Kelly writes: > I'm supposedly on the doc team (according to an email message from > Jordan some month(s) ago), but I had no idea linuxdoc was to be the > common source format. Heck, I didn't even realize there was a > freebsd-doc list until a few weeks ago! Welcome! Late is better than never! > We need up writers' resource repository, perhaps on the web, including > the style sheet, linuxdoc (sources or perhaps packaged up for > pkg_add), plus working versions of our docs for testing, browsing, > etc. Take a look at http://www.freebsd.org/How/faq-new. It is a start at such a resource but has become a bit stale. :( I can put a link to the linuxdoc toolkit and sgmls in that page. Ultimately, the FAQ and tutorials are bound for the current source tree (/usr/src/share/FAQ in particular). The idea is that the documents in the SGML directory are the "masters" that the documents in the other directories will be generated from. The conversion to latex works well. The conversion to HTML has some rough edges but works. The conversion to ASCII has some rough edges that a groff wizard may be able to fix (and I am *not* a groff wizard!). The FAQ/tutorial pages in the WWW server come (almost) directly from the main source tree. The trouble with this scheme is that the conversions depend on tools that are not even in the ports collection. Anybody with contributions, either in the form of new tutorials, or old tutorials converted to SGML should contact me about getting them in the tree. -john === jfieber@cs.smith.edu ================================================ =================================== Come up and be a kite! --K. Bush === From owner-freebsd-doc Fri Mar 31 18:37:09 1995 Return-Path: doc-owner Received: (from majordom@localhost) by freefall.cdrom.com (8.6.10/8.6.6) id SAA15973 for doc-outgoing; Fri, 31 Mar 1995 18:37:09 -0800 Received: (from jmacd@localhost) by freefall.cdrom.com (8.6.10/8.6.6) id SAA15964 for doc; Fri, 31 Mar 1995 18:37:08 -0800 Date: Fri, 31 Mar 1995 18:37:08 -0800 From: Joshua Peck Macdonald Message-Id: <199504010237.SAA15964@freefall.cdrom.com> To: doc Subject: ptx man page? Sender: doc-owner@freebsd.org Precedence: bulk how come there is no man page for /usr/bin/ptx? -josh