From 2c7a0fbc5ec17c47e8cf24143fc366f4a6af1a7e Mon Sep 17 00:00:00 2001 From: Devin Reade Date: Fri, 7 Sep 2012 21:36:42 -0600 Subject: [PATCH] Added FAQ source and generator code. Other than moving some of the (now) unneeded generator components to a 'historical' subdirectory and adding a GNUmakefile appropriate to the new build, no changes have as yet been made. --- faq/FAQ.gno.src | 2549 +++++++++++++++++++++++++++++++++++ faq/GNUmakefile | 24 + faq/historical/Makefile | 129 ++ faq/historical/README | 10 + faq/historical/faq-config | 46 + faq/historical/faq.funcs | 60 + faq/historical/log.preamble | 7 + faq/mkfaq | 391 ++++++ 8 files changed, 3216 insertions(+) create mode 100644 faq/FAQ.gno.src create mode 100644 faq/GNUmakefile create mode 100644 faq/historical/Makefile create mode 100644 faq/historical/README create mode 100644 faq/historical/faq-config create mode 100755 faq/historical/faq.funcs create mode 100644 faq/historical/log.preamble create mode 100755 faq/mkfaq diff --git a/faq/FAQ.gno.src b/faq/FAQ.gno.src new file mode 100644 index 0000000..0321939 --- /dev/null +++ b/faq/FAQ.gno.src @@ -0,0 +1,2549 @@ +Frequently Asked Questions (FAQ) List for GNO. + +Nothing appearing prior to the '%Start%' line below will appear in the +FAQ generated by 'mkfaq'. + +Key layout information of this document: + 1. Question (and answer) numbers need not be in sequence, they + only need to be distinct. They will be renumbered. + + 2. Sections headers must be preceded by "%Section%". The + 'underlining' used on the following line will be replaced + with one of a suitable length. Section names will be used + in a table of contents. + + 3. Don't assume that you can use html, nroff, or other formatting + commands. Text-only versions of this document are distributed. + + 4. Don't explicitly refer to the modification date or version + of this file -- it is updated automatically. + +%RCS-ID%$Id: FAQ.gno.src,v 1.18 1998/05/06 05:12:23 gdr Exp $% + +These specify where this FAQ can be found: + +%FAQ-http-addr%http://www.gno.org/~gno/FAQ.html% +%FAQ-ftp-addr%ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc/faq/CURRENT% +%FAQ-log-http-addr%http://www.gno.org/~gno/FAQ-log.html% +%FAQ-log-ftp-addr%ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc/faq/LOG% + +Everything after this point is world-visible: + +%Header-start% +This is the Frequently Asked Questions (FAQ) posting of the +comp.sys.apple2.gno newsgroup. This document can be freely copied so +long as + 1. it is not sold (although it may be included in commercial + distributions of Apple II archives such as the Golden Orchard + CD series); and + 2. any sections reposted elsewhere from it are credited back to + this FAQ with the FAQ's copyright info and official FTP and + WWW location left in place. +Explicit permission is granted to carry this FAQ on electronic forums +dealing with Apple II computers such as BBSs and service providers +such as Genie and Delphi. + +This FAQ is available via ftp and on the WWW at + + %FAQ-FTP% + %FAQ-HTTP% + +A summary of recent updates may be found at + + %LOG-FTP% + %LOG-HTTP% + +This FAQ may also be found in archives of comp.answers and news.answers, +such as those at rtfm.mit.edu. + +The question numbers in this FAQ are auto-generated. Therefore, when +referring to questions in this FAQ, please either give the version number +of the FAQ or (preferably) give some context that identifies to which +question you refer. + +The FAQ was originally maintained by C. Matthew Curtin, +. It contains contributions (intentional +or otherwise) from many users of GNO. + +The FAQ is currently maintained by Devin Reade, . +Questions, comments, suggestions, and submissions to this FAQ are welcome +and should be emailed to Devin Reade or posted to comp.sys.apple2.gno. + +This FAQ is undergoing active development. Consequently, some questions +may have annotations starting with three asterisks ("***"). These are +questions that are in the process of having their answers written or +modified. + +In the event that this FAQ appears to be abandoned, someone else is +welcome to take it over as the official maintainer or to use this FAQ +as the basis for a new one, provided that you credit the previous +maintainers. The criteria for abandonment are: + 1. The FAQ has not been updated nor posted to comp.sys.apple2.gno + for a period of at least six months; + 2. Attempts to contact the current maintainer (Devin Reade) + have failed. You must try for a period not less than 30 + days, and you must try contacting the maintainer through + email, and postings to comp.sys.apple2.gno and the Delphi + (delphi.com) Apple II Programmers' Forum. +In addition, please ensure that there is a general consensus on +comp.sys.apple2.gno that the FAQ is indeed abandoned before you attempt +to take it over. I have not included this as a criterion since a +"general consensus" is difficult to quantify in any practical sense. + +%Header-end% + +%TOC% + +%Section% General: +================= + +Q#101: What is GNO? + +A#101: GNO is a UNIX-like multitasking environment for the Apple IIGS. + GNO provides: + + 1. Pre-emptive multitasking. + 2. A shell that takes full advantage of the multitasking provided + (i.e., job control), and 'regular expressions', and a simple + programming language. + 3. A powerful programming environment. All the calls needed to + control processes, support Inter-Process Communication (IPC), + and other tools necessary to support multitasking are + available to the programmer. + 4. The first completely consistent method for accessing serial + and console I/O on the Apple II. This makes such things as + attaching terminals to your GS, multiline BBSes, remote + dial-ups, UUCP or SLIP that doesn't take over your computer, + as well as countless other applications a possibility. + +Q#108: What is the status of GNO? + +A#108: GNO was developed by Procyon Enterprises (Jawaid Bazyar, prop.). + Until August 1997, GNO was a commercial product. In August 1997, + Jawaid changed GNO's status to that of freeware. Procyon still + retains the copyright on the kernel, gsh, and other components + which were written by or for Procyon. + + GNO IS NOT PUBLIC DOMAIN. + +Q#104: What is the current version of GNO? + +A#104: The currently released version is v2.0.4. The version currently + under development is v2.0.6. v2.0.5 never had a general release, + and is not available. + + For those programmers using ORCA/C v2.1.x, there was a update made + available (for both GNO v2.0.4 and GNO v2.0.6 users) on 22 Dec 97. + It consists of updated headers, libraries, and manual pages. It + is available at the following site: + + ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base206 + +Q#103: What are GNO's minimum system requirements? + +A#103: The GNO documentation specifies that the minimum requirement + is an Apple IIGS with 1.25 MB of memory and a 3.5" disk drive. + Realistically (especially with all the third-party add-ons), + a hard drive (or other large mass storage device) should be + considered a necessity. An accelerator and additional memory + is recommended. + + There is not an official "minimum disk space" requirement + as yet. When this information becomes available, it will + be added to this FAQ. + +Q#102: Where can I get GNO? + +A#102: The base GNO distribution may be obtained via anonymous ftp + from the following sites. See also Q#107: + + ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base204 + ftp://ftp.hypermall.com/pub/gno + + The documentation for GNO v2.0.4 is now available via ftp and + http at the following sites. MS-Word versions are also available + via ftp: + + http://www.gno.org/~gno + ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc + ftp://ftp.hypermall.com/pub/gno/docs + + For those who aren't able to make decent printed copies of the + documentation on their own, Procyon still offers the printed + documentation for sale. (Do *NOT* ask Devin Reade for the + printed documentation. He does not work for Procyon and does + not sell it.) At last check, this is the Kernel Reference Manual, + the GSH Reference Manual, selected manual pages, and the release + and installation notes. This contents list is unofficial and + subject to correction by Procyon. + + Procyon Enterprises Inc maintains a web page at: + + http://www.hypermall.com/companies/procyon + + or you can contact them by snail-mail at: + + Procyon, Inc. + P.O. Box 620334 + Littleton, CO 80162-0334 + 303/933-4649 + +Q#105: What support is available for GNO? + +A#105: For the most part, the only support available is that given + by GNO developers in the Apple II community. In other words, + what you get is what you get. Often a polite question posted + to comp.sys.apple2.gno will result in a helpful response. + + Procyon still offers limited support for people who purchased + GNO prior to August 1997. No support is available from Procyon + for those who obtained GNO after it changed to freeware status. + + There is a group of programmers (known as the gno-devel list) + working toward getting v2.0.6 out the door. Information regarding + this work will be posted to comp.sys.apple2.gno as it becomes + available. Have patience; we all have day jobs and this is + a hobby. + +Q#107: Where can I get the files/archives recommended in this FAQ? + +A#107: The "core" files of the GNO distribution (such as the GNO + kernel and gsh(1)) are available through anonymous ftp as + described in Q#102. + + Non-commercial files, unless otherwise specified, should be + available from major Apple ftp sites. There is often a GNO- + specific directory, but compatible programs, patches, etc, + may appear anywhere under the Apple II hierarchy. The GNO + distribution also contains many files in this category; + ensure you have newest versions by checking the ftp sites. + + The three main Apple II sites are + ftp://apple2.caltech.edu/Zocalo/pub/apple2 + ftp://ground.isca.uiowa.edu/apple2 + ftp://ftp.gno.org/pub/apple2 + The latter (also known as trenco.gno.org) is the master site for + GNO development, as of August 1997. GNO-specific files can be + found in the /pub/apple2/gs.specific/gno directory on ftp.gno.org. + + Other sites are listed in the comp.sys.apple2 FAQ, which is + available from the above two sites and + http://www.visi.com/~nathan/a2/faq/csa2.html + +Q#106: Why is this FAQ written in such a drab format? + +A#106: Because it was considered critical that there is a easily + readable text-only version available. Combined with the fact + that the maintainer didn't want to spend a lot of time with + source translators, this placed a restriction on the type + of formatting available. + +%Section% Compatibility: +======================= + +Q#801: With what standard version of UNIX is GNO compatible? + +A#801: GNO contains components that originate with a variety of + flavors of UNIX. These include 4.3BSD, XINU, and SYSV. + It is mostly BSD. As of GNO v2.0.6, GNO has become closer + to 4.4BSD. Work is in progress to make it as compliant as + possible to POSIX 1003.1 and POSIX 1003.2. + +Q#806: Can I run ORCA/Shell from GNO (or vice-versa)? + +A#806: No. GNO with a shell (such as gsh) is intended to be a replacement + for ORCA/Shell. Similarly, one cannot run GNO from ORCA/Shell. + However, you can still use the various ORCA languages and (the + majority of) utilities from GNO. See the sections on "Programs" + and "Compiling", below. + +Q#802: Is GNO compatible with the SecondSight VGA card? + +A#802: Yes. GNO is completely compatible with the SecondSight card. + However, GNO's console driver currently does not support the + SecondSight card's VGA specific text modes. A SecondSight aware + console driver is planned as a future enhancement. + +Q#803: Are desktop applications compatible with GNO? + +A#803: In most cases, yes. However, GNO doesn't currently allow more than + one desktop program to run concurrently. It does allow you to + run multiple text applications with or without a desktop application, + to the limits of your available memory. + + There is a program (also available from Procyon), called Switch-It!, + that allows one two switch between running desktop programs. + It is not multitasking (in that only the currently displayed + desktop program is actually running), nor does it _require_ + GNO. It is, however, complementary to and compatible with GNO. + Other (text based) processes running in the background continue to + do so when Switch-It! is active. + +Q#804: Can I use prizm (the ORCA desktop environment) with GNO? + +A#804: In a nutshell, no. The exact reasons are not generally known, + but the author (Mike Westerfield) does not ever expect to have + a compatible version available. + +Q#805: What new features are expected to be in the next version (2.0.6)? + +A#805: This list is unofficial and subject to change. With that in mind: + + - Complete kernel support for TCP/IP. + - Lots of little bug fixes that should improve stability. + - An updated and expanded libc. + - An OrcaLib compatible with the ORCA/C v2.1 OrcaLib. + - Updates to various shell programs. + +%Section% Documentation: +======================= + +Q#201: What documentation comes with GNO? + +A#201: GNO/ME Overview + Kernel Reference Manual + Shell (gsh) User's Manual + Manual Pages (some printed, all online) + + Online versions of these documents are also available. See Q#102. + +Q#202: What additional documentation is recommended for GNO? + +A#202: The GNO Overview has quite a complete reading list for users and + programmers, and it is too long to go into detail here. However, + in general, the references are broken down into the following + categories: + - UNIX reference books. + - C reference books. + - Editor reference books. + - Apple IIgs Programming References + + The following list, should also be considered "must have" for + any serious programming: + + - The ORCA/C and/or ORCA/M manuals, as appropriate. + - Toolbox volumes 1, 2, 3 + - Programmers' Reference for System 6.0/6.0.1 + - GS/OS Reference + - Firmware Reference + - Apple Technical Notes + - Apple File Type Notes + - A manual on 65816 assembly programming, if you are + using assembly. One very good manual is: + Lichty, Ron and Eyes, David. _Programming_the_IIgs_ + _in_Assembly_Language_, Brady, 1989. + ISBN 0-13-729559-6 + You will likely have to get it second hand, as it is no + longer in print. + + The following books are recommended: + + - Hardware Reference + - Apple Numerics Manual + - Device Driver Reference + - IEEE Std 1003.1-1988 (or later) -- The POSIX standard + for computer environments. + - ANSI/ISO 9899 Standard (defines ANSI/C). + This is an expensive document, but you get a cheap copy + by purchasing Schildt, Herbert _The_Annotated_ANSI_ + _C_Standard_, McGraw-Hill, ISBN 0-07-881952-0. The book + is set up so that the standard is printed on the "left" + pages and the annotations are on the "right" pages. + MAKE SURE YOU USE ONLY THE LEFT PAGES; the annotations + have just enough errors in them to be dangerous. Some + of the "left" pages (from the Standard) are also missing. + +Q#203: What are all the numbers in parenthesis following program names? + +A#203: When you see something like "ls(1)" in the documentation, it + refers to something called "ls" which is documented in Chapter 1 + of the manual pages. Similarly, "select(2)" is refering to + something called "select" which is documented in Chapter 2. To + find out what the various chapters are for, type in the command + man 4 intro + substituting "4" for whichever chapter you wish to learn about. + +Q#206: I've just finished writing a new program (or library or whatever). + What documentation should I include? + +A#206: Including the following documentation components will not only + help anyone who is maintaining a GNO site, but they will also + make your contribution look more professional. Remember, if + someone can't tell what your program is supposed to do, they + are less likely to try it out. + + You should have: + + - A manual page (see also Q#204). Unless your program requires + a large reference manual ( > 5-10 pages of written text), the + manual page should be the primary document. + + Ensure the man page is assigned to the correct section. One + common mistake is to mix up Section 1 (User Commands) with + Section 8 (System Administration). + + - A describe(1) database entry. Try to use the ".desc" suffix + on the file name. (For example, if you wrote the "foo" program, + you should have a text file "foo.desc" containing the database + entry.) If you have WWW access, please update the online + describe database maintained by Soenke Behrens -- see Q#304. + + The describe entry is very suitable as a brief README file + when uploading your program to ftp sites, or when posting to + comp.binaries.apple2. + + Describe entries should only be written for programs, not + libraries or individual routines. + + - An rVersion resource fork. If you don't want to write a rez + source file, then use setvers(1). + + There is a new format out which includes rVersion as a subset. + It is called rProgramInfo (or rProgInfo), and was formalized + by Eric Shepherd. Information on this is available at the + usual ftp sites in the archive rProgInfo.shk. See also the + templates file listed later in this answer. + + - "Standard" help and version flags. If possible, invoking your + program with the "-V" (capital vee) flag should print the + version number and exit. Invoking it with the "-h" flag should + print a usage (help) message and exit. Use of the "-?" flag + is discouraged because it is a meta-character in many shells. + + It may not be practical to support these two flags, such as + if you are porting a program that already uses them for other + purposes, or if you are writing a daemon. + + To make things easier, templates for manual pages, rVersion + source files, and describe database entries are available at + the usual sites. Look for an archive with a name similar + to + templates[version_number].shk + +Q#204: I'm writing a manual page. What format should I use? + +A#204: While man can handle both manually-edited preformatted pages and + pages that are aroff source (created by AppleWorks-GS or a + compatible editor), the recommended format is to use nroff source + with tmac "an" extensions. + + The reason for this is that only nroff source can be reformatted + "on the fly" to suit different terminal characteristics. See also + Q#205. + +Q#207: What should be in a manual page? + +A#207: Whatever is necessary. However, there are some standard sections + for manual pages, based on which section (chapter) the manual + page is in. Templates with the suggested manual page formats + are available in the file + templates[version_number].shk + at the usual ftp sites. + + For programs in particular (typically Chapters 1, 6, and 8), here + are some sections that should be in the man page. The order of + the first three are mandatory due to how some automated tools + work. The sequence on the remainder are suggested: + NAME - name and one line description + SYNOPSIS - list of options and arguments + DESCRIPTION - a detailed description + OPTIONS - explanation of the flags + ENVIRONMENT - relevant environment variables and their + semantics, if appropriate + FILES - related files, if appropriate + BUGS - known bugs, if appropriate + AUTHOR - your name and contact info, typically + an email address. Include your smail + address at your own risk. + LEGALITIES - Commercial, freeware, shareware, public + domain, copyleft, ... ? + ATTRIBUTIONS - Give credit when due. For example, if + your binary was linked with the ORCA + libraries, you should be including the + Run-Time Licence from Appendix C of the + ORCA/C manual. + SEE ALSO - related manual pages or other documents + +Q#205: Man(3) is too slow when formatting pages. Can I speed it up? + +A#205: Actually, it's not man(3), but nroff(3) which is slow. Nroff + is in desperate need of an update, not only for speed but for + functionality. + + In the interim, however, you can get a faster response from man + at the cost of using more disk space by preformatting your man + pages. See catman(8). + +Q#208: What are the standard manual page chapters? + +A#208: Chapter 1: Commands and Applications + Chapter 2: System Calls + Chapter 3: Library Routines + Chapter 4: Devices + Chapter 5: File Formats + Chapter 6: Games + Chapter 7: Miscellaneous + Chapter 8: System Administration + + For GNO, there should be no need to use Chapter n [New Commands], + or Chapter l (ell) [Local Commands], unless (in the latter case) + the manual page is for something that is not to be released to + the GNO community. + + Chapter 3F is reserved for Fortran Routines, of which there + are none at this time (due to the lack of a publicly available + Fortran compiler). + +%Section% Programs: +================== + +Q#301: What other programs come with GNO? + +A#301: Lots of free utilities that bring some of the power of UNIX systems + to the IIGS. In addition to getting the utility executable files, + you get the source for many of these. These programs have been + provided by various authors. + +Q#302: Are there any ftp sites for GNO utilities? + +A#302: Yes. Many Apple II ftp sites have GNO-specific directories, although + GNO stuff can also be found in other directories on these sites. + + The three primary general-purpose sites are: + ftp://apple2.caltech.edu/Zocalo/pub/apple2/shellprogs + ftp://ground.isca.uiowa.edu/apple2/apple16/gno + ftp://ftp.gno.org/pub/apple2 + + Trenco (trenco.gno.org or ftp.gno.org) is the master site for GNO + development as of August 1997. See Q#107. + + See the comp.sys.apple2 FAQ for other Apple II ftp sites. + +Q#303: I cannot ftp to caltech or ground. How can I get the GNO utilities? + +A#303: Perhaps you could use the FTP-by-mail service. Send mail to + ftpmail@decwrl.dec.com with the subject line of "help" and no body + for information. + + Another alternative is to use the WWW to access those sites. + WWW access information is available in the comp.sys.apple2 FAQ + (see Q#107). + +Q#304: What is the most recent version of program XXXXXX? + +A#304: The best way to find out what programs are available for GNO, + including version numbers, authors, and other information is + to use the describe(1) database. The program, database, and + maintenance utilities are available at the usual ftp sites. + + Soenke Behrens also maintains an online + describe database. This tends to be the most up-to-date version, + and is available at + + http://www.arrowweb.com/sbehrens/describe.htm + +Q#305: Which editor should I use? + +A#305: Whichever one you want. Many editors work under GNO. Some + of the more popular ones are emacs (MicroEMACS), vi (Stevie), + ORCA/Editor, Edit-16, and Rose. + + Many of these editors cannot be suspended from the shell. Some + have the "eating keystrokes" problem (see Q#701). + +Q#306: What command line flags does gsh(1) accept? + +A#306: There are two. The first is "-c arg", which is supposed to allow + one to specify a script on the command line. This seems to be + broken, though. + + The second one is "-f", which tells gsh not to parse its gshrc + file, nor do other initialization tasks. Think of it as "fast + startup". Unfortunately, empirical tests seem to indicate that + gsh is no faster with this flag than without. + +%Section% System Installation: +============================= + +Q#1401: For what are the various directories used? + +A#1401: The following is the suggested layout and use of various directories. + Any given site will likely have more, but these are the "standard" + ones. Note that these don't necessarily have to be on different + physical partitions due to the GNO namespace facility (see Q#1002). + This FAQ assumes the following directory structure: + + /HFSinclude GNO standard C header files (required if and + only if /usr/include is not on an HFS + partition) + /bin basic standard programs + /dev device drivers + /etc configuration files + /lang languages + /lang/orca ORCA languages + /lang/orca/languages compilers + /lang/orca/libraries standard ORCA libraries (not used + for GNO; see /lib instead) + /lang/orca/libraries/orcacdefs standard ORCA/C header files + /lang/orca/release.notes READMEs, release notes, etc + /lang/orca/shell ORCA editor and ORCA/Shell config files + /lang/orca/utilities ORCA/Shell compatible programs + /lang/orca/utilities/help These are the ORCA utility help files, + which show brief usage information. + The preformatted manual pages that + come with some utils should _not_ go + here. + /lang/orca/man/man1 manual pages for ORCA/Shell compatible + programs (nroff, troff, or aroff source) + /lang/orca/man/cat1 manual pages for ORCA/Shell compatible + programs (preformatted). These should not + be confused with the "help" files in + /lang/orca/utilities/help. + /lib standard GNO libraries + /lib/RInclude resource compiler include files + /lib/orcacdefs holds defaults.h; otherwise empty + /tmp scratch directory (for temporary files) + /usr UNIX system resources + /usr/X X (graphical interface) -related files + /usr/X/bin X programs + /usr/X/lib X libraries and configuration files + /usr/X/man X manual pages + /usr/bin additional standard programs + /usr/games games + /usr/games/lib game configuration files + /usr/include GNO standard C header files + /usr/lib optional libraries + /usr/lib/sendmail.d sendmail configuration files + /usr/lib/tmac nroff/troff macro files + /usr/local custom and local files + /usr/local/bin custom programs + /usr/local/etc custom configuration files + /usr/local/include custom C header files + /usr/local/lib custom libraries and configuration files + /usr/local/man manual pages for custom files + /usr/man standard manual pages + /usr/man/cat[1-8] standard manual pages (preformatted) + /usr/man/man[1-8] standard manual pages (nroff, troff, aroff) + /usr/sbin system maintenance programs + /var heavy write-use (variable) filesystem + /var/adm system administratin and log files + /var/mail user mailboxes + /var/spool spool directories for various daemons + /var/spool/lpq line printer spool directory + /var/spool/news news daemon spool directory + +Q#1402: What should be in my gshrc file? + +A#1402: Whatever you find necessary, keeping in mind that the gshrc file + is parsed whenever an instantiation of gsh is started. This implies + that a long gshrc file can slow down your system. + + Here is one example of a minimal gshrc file. For formatting reasons + in the FAQ, long lines have been split with a trailing '\' on + the line to be continued. Gsh doesn't understand this syntax, so + be sure to enter them as a single line. + + # set prefixes for ORCA languages (see also Q#1303) + prefix 13 /lib + prefix 14 /tmp + prefix 15 /lang/orca/shell + prefix 16 /lang/orca/languages + prefix 17 /lang/orca/utilities + + # match lower prefixes. gsh _should_ update these + # automatically, but doesn't. + prefix 2 13 + prefix 3 14 + prefix 4 15 + prefix 5 16 + prefix 6 17 + + # set search path -- gsh parses it backwards! + set path="/usr/games /lang/orca/utilities /usr/X/bin /usr/bin\ + /bin /usr/local/bin" + export path + rehash + + # search path for man pages + setenv MANPATH /man:/usr/man:/usr/local/man:/local/man:\ + /usr/X/man:/lang/orca/man + + # settings for occ(1): + # create *.o files instead of *.a files + setenv CCEMULATE 1 + # set the if and only if you are using ORCA/C 2.0.x. + setenv CCOLD 1 + +Q#1403: Where should I install custom additions to GNO? + +A#1403: Anything you add to your GNO installation beyond what is in the + base installation should go into the /usr/local hierarchy. + This will facilitate future updates, in that you will only have + to replace those directories used by the GNO base distribution, + and your customized files will not be overwritten. + + There are some exceptions to this. For example, /etc/passwd, + /etc/namespace, and a few other files that have to be customized + do not and will not reside in the /usr/local hierarchy. However, + these will be kept to a minimum and will be explicitly mentioned + in future release notes. + + If your installed man(1) cannot cannot handle manual pages in + more than one directory hierarchy, then you need to upgrade your + man to version 3.0 or later. + + GNO v2.0.4 CAVEAT + ^^^^^^^^^^^^^^^^^ + + When GNO v2.0.4 (and earlier versions) was released, there + was no attempt made to have users put add-ons in the /usr/local + hierarchy. Therefore, if you're currently running GNO v2.0.4 + it is likely that you have a lot of custom items in /bin, + /usr/bin, /usr/man, and related directories. This is complicated + by the fact that various packages that are considered "standard" + (such as the Multiuser Update) were not part of the base GNO + v2.0.4 distribution. + + If you are in this situation, then I suggest that you not + worry at this time about moving existing programs to the + /usr/local hierarchy. Instead, defer this to when GNO v2.0.6 + is released. In the interim, there is nothing stopping you + from using the /usr/local hierarchy for anything new that you + download ... + +%Section% Installing GNO with ORCA: +================================== + +Q#1301: Do I need separate installations of ORCA/C for use with GNO and + ORCA/Shell? + +A#1301: At least partly, yes, although it is possible to reduce duplication + to a minimum. + + GNO requires modifications to some header files and libraries, + as well as the additions of others that don't come with ORCA/C. + + The remaining questions in this section of the FAQ explain how + to set up such a split installation. This will allow you run + both GNO and ORCA/Shell (but not concurrently). The latter is + necessary when submitting bug reports to the Byte Works. Mike + Westerfield (quite rightly) does not generally accept bug reports + about programs that fail under GNO but run correctly under + ORCA/Shell. + + CAVEAT: For the methods explained in this section to work, you must + be using occ v1.14 when doing compilations with ORCA/C + v2.0.x. This is because occ v1.14 will allow older versions + of ORCA/C to #include the 13/orcacdefs/defaults.h file which + is automatically included by ORCA/C v2.1.x. + + If you are using ORCA/C v2.0.x but not occ, you will have + to use the #pragma path directive in all of your sources. + Failure to do so may result in compilation errors or + unexplained crashes. + + Any version of occ may be used when compiling with ORCA/C + v2.1.x. + + These methods are not quite error-free. See Q#611 for + details. + + The information in this section has been used to set up combinations + of GNO v2.0.4 and GNO v2.0.6 with ORCA/C v2.0.3 and ORCA/C v2.1.x. + +Q#1302: How do I set up ORCA/C so that I can use it with GNO? + +A#1302: === See the CAVEAT in Q#1301 === + + There are a few aspects to this, so it has been split into various + questions in this section of the FAQ. You should read each of + those questions when so directed, below. The following instructions + assume that you have already installed your ORCA languages; various + files and directories will be moved from their original locations. + + If you haven't already done so, change the auxtype of + (original_orca_directory)/shell/Editor to hex DC00 (see Q#701). + + Next, create the directory /lang/orca. This will be the new + location of your ORCA distribution. You should move all the + files and directories from you original ORCA location to /lang/orca. + You will therefore have directories like /lang/orca/shell, + /lang/orca/languages, and so forth. + + The next step is to set up the appropriate GS/OS prefix numbers. + This procedure is documented in Q#1303 (don't forget to update + both your 15/login and ~/gshrc files). + + Next, set up your defaults.h file as described in Q#1305. As per + the caveat in Q#1301, this file will be parsed regardless of which + version of ORCA/C you're using. + + Now, if you're running GNO v2.0.4, you have to modify some header + files. See Q#1306. + + Next you have to set up your libraries. This information is specific + to your GNO-ORCA/C version combination. See questions Q#1307, Q#1308, + Q#1309, or Q#1310 as appropriate. Note that the library /lib/libgno + is obsolete in both GNO v2.0.4 and v2.0.6. If your /lib directory + resides on an HFS partition, you will need to rename some of your + libraries (see also Q#603). + + If you're using an older version of ORCA/C, you should prototype + your headers (this is already done for newer versions of ORCA/C). + Using prototyped headers and #pragma lint -1 can catch a lot of + bugs, both in user code and in the compiler. Be very careful that + you use the correct prototypes. + + For programs in your 17 directory that don't work with GNO (such + as prizm), I recommend putting something like the following in + your ~/gshrc: + + alias prizm echo "prizm not available under GNO" + + Remember to put 17 in your PATH environment variable. See the + Gsh Reference Manual if you don't know how to do this. + + Finally, if you're using ORCA/C v2.0.x, ensure you have occ v1.14 + installed (other versions -- earlier or later -- will not suffice). + Also edit both 15/login and ~/gshrc to define the CCOLD environment + variable. Do NOT define the CCOLD environment variable if you are + using ORCA/C v2.1.x; you will slow down your compilations. + +Q#1303: GNO with ORCA: What should I use for compilation directories and + prefixes? + +A#1303: === See the CAVEAT in Q#1301 === + + In order to minimize file duplication for running GNO and ORCA/Shell + (but not concurrently -- see Q#806), you should set your prefixes up + as follows. For GNO, these "volumes" may be defined in /etc/namespace + (see Q#1002). For ORCA/Shell, these pathnames may be relative to + one or more volumes. + + SHARED (used by both GNO and ORCA/Shell) + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + 15 /lang/orca/shell configuration files + 16 /lang/orca/languages compilers + - /lang/orca/include ORCA headers + 17 /lang/orca/utilities ORCA-compatible utilities + - /lang/orca/utilities/help ORCA-compatible utility + descriptions + 14 /tmp scratch (work) directory + + GNO (not used by ORCA/Shell) + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + 13 /lib main GNO libraries + - /usr/lib secondary GNO libraries + - /usr/local/lib secondary GNO libraries + + ORCA (not used by GNO) + ^^^^^^^^^^^^^^^^^^^^^^ + 13 /lang/orca/libraries ORCA libraries + + + The prefixes shown should be set up in your ~/gshrc file (for GNO), + or your 15/login file (for ORCA/Shell). + +Q#1304: GNO with ORCA: Where should my C header files go? + +A#1304: === See the CAVEAT in Q#1301 === + + While it is possible to have all of your header files in one + directory hierarchy (this is how it was done in the stock v2.0.4 + distribution), it is STRONGLY advised that you keep separate + directory hierarchies. They are: + + /usr/include + /HFSinclude + /lang/orca/libraries/orcacdefs + /lib/orcacdefs + /usr/local/include + + The /usr/include directory should contain all the header files + that ship with GNO. This will include some subdirectories like + sys, machine, and net. + + In GNO v2.0.6 there are a few files that don't conform to ProDOS + naming conventions. These files should be placed in the /HFSinclude + hierarchy. + + ORCA/C comes with its own set of header files. Some of these + are used by GNO while others are ignored (because header files + of the same names exist in one of the other directory hierarchies). + All of these header files should be left in the + /lang/orca/libraries/orcacdefs directory (see Q#1302). + + /lib/orcacdefs corresponds to 13/orcacdefs under GNO. It should + contain only one file, defaults.h. See Q#1305. + + /usr/local/include, like everything else in the /usr/local hierarchy, + is not used by the GNO base install. This hierarchy is reserved + for site-specific packages that you decide to add. In particular, + /usr/local/include should be used for any header files that you + decide to add to your system, and which are not part of the + base installation. + +Q#1305: GNO with ORCA: What goes in the 13/orcacdefs/defaults.h file? + +A#1305: === See the CAVEAT in Q#1301 === + + There are two versions of this file, one for GNO and one for + ORCA/Shell. For GNO, the /lib/orcacdefs/defaults.h file should + contain: + + #define __appleiigs__ + #define __GNO__ + #pragma path "/usr/include" + #pragma path "/HFSinclude" /* needed for GNO v2.0.6 */ + #pragma path "/lang/orca/libraries/orcacdefs" + + (See Q#611 regarding a problem with using the "path" pragma.) + + For ORCA/Shell, the /lang/orca/libraries/orcacdefs/defaults.h + file should contain: + + #define __appleiigs__ + +Q#1306: GNO with ORCA: What header file modifications are necessary? + +A#1306: === See the CAVEAT in Q#1301 === + + If you're using GNO v2.0.6, no modifications should be necessary + provided you've placed all the GNO header files into /usr/include + and /HFSinclude as appropriate. This applies to both ORCA/C v2.0.3 + and ORCA/C v2.1.x. + + There are various header files included with the GNO v2.0.1 + distribution. These should all be copied into the /usr/include + directory hierarchy as discussed in Q#1304. (Versions 2.0.2, + 2.0.3, and 2.0.4 were incremental changes, not complete + distributions, and therefore did not include header files.) + + If you are using the Multiuser package, then you should also + copy over the and files from that package. + + The files in the following lists are used instead of their ORCA/C + counterparts, except where noted by "+++"; those so marked need + to be modified as described. + + Note the last section in this question is a list of suggested + changes to the GNO v2.0.4 header files. These changes you should + make yourself. + + GNO v2.0.4 with ORCA/C v2.0.3 + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + errno.h This one has many GNO error codes added. + fcntl.h Differs in the prototypes of open(2), read(2), + write(2), and definition of OPEN_MAX. + signal.h Completely different for GNO. + stdio.h Differs in the prototypes of fread(3) and + fwrite(3). The FILE structure uses an + older name for one of its members, but it + doesn't matter. A prototype for fdopen(3) + and the fileno() macro was added. + +++ stdlib.h You should delete this one and copy the + ORCA/C v2.0.3 stdlib.h from + /lang/orca/libraries/orcacdefs to + /usr/include. See the "common" changes + below for more information on this file. + string.h Many new functions were added in the GNO one. + +++ types.h You should delete this one and copy the + ORCA/C v2.0.3 types.h from + /lang/orca/libraries/orcacdefs to + /usr/include. See the "common" changes + below for more information on this file. + + GNO v2.0.4 with ORCA/C v2.1.x + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + errno.h This one has many GNO error codes added. + fcntl.h Differs in the prototypes of open(2), read(2), + write(2), and definition of OPEN_MAX. + signal.h Completely different for GNO. + +++ stdio.h You should delete this file, then copy the + one from your ORCA/C distribution into + the /usr/include directory. See the "common" + changes below for more information on this + file. Note that there was a critical change + to the FILE structure as of ORCA/C v2.1.1b2; + ensure your header file matches your OrcaLib. + +++ stdlib.h You should delete this one and copy the + ORCA/C v2.1.x stdlib.h from + /lang/orca/libraries/orcacdefs to + /usr/include. See the "common" changes + below for more information on this file. + +++ string.h You should rename this file to something + else (like "string.old"), then copy the + one from your ORCA/C distribution into + the /usr/include directory. Finally, you + should copy the prototypes for the following + functions from the old GNO file into the new + one copied from the ORCA/C distribution: + bcopy bzero + index rindex + strdup strupr + strlwr strset + strnset strrev + strpblnks strrpblnks + strpad strrpad + stricmp strncmp + +++ types.h You should delete this one and copy the + ORCA/C v2.1.x types.h from + /lang/orca/libraries/orcacdefs to + /usr/include. See the "common" changes + below for more information on this file. + + GNO v2.0.4 common changes + ^^^^^^^^^^^^^^^^^^^^^^^^^ + + The following is a list of suggested changes to the GNO v2.0.4 + header files. You have to make these changes yourself; they are + not part of the distributed header files. + + For any files below that don't appear in /usr/include, you should + copy the file from /lang/orca/libraries/orcacdefs into /usr/include, + then edit the copy in /usr/include. Do not modify files in + /lang/orca/libraries/orcacdefs. + + dirent.h (possibly sys/dirent.h): + Ensure that in struct dirent, the d_namelen field + appears before the d_name field, as described in the + GNO v2.0.4 release notes. + + gno/gno.h: + Rename send(2) to procsend(2) and receive(2) to procreceive(2). + + stdio.h: + Add the following: + + #define fileno(f) ((f)->_file) + #define P_tmpdir "/tmp" + FILE * fdopen(int, const char *); + char * tempnam(char *, char *); + char * mktemp(char *); + int mkstemp(char *); + FILE * popen(const char *, const char *); + int pclose(FILE *); + + Add the following if you're using ORCA/C v2.1.x: + + #define setbuffer(stream,buf,size) ((buf==NULL) ? \ + (void)__setvbuf(stream,NULL,_IONBF,0L) : \ + (void)__setvbuf(stream,buf,_IOFBF,\ + (size_t)size)) + #define setlinebuf(stream) (__setvbuf(stream,NULL,\ + _IOLBF,0L)) + int __fseek(FILE *, long, int); + int __setvbuf(FILE *, char *, int, size_t); + + stdlib.h: + Add the following declarations: + + int initenv(void); + void popenv(void); + int pushenv(void); + int putenv(const char *); + int setenv(const char *, const char *, int); + void unsetenv(const char *); + + sys/ports.h: + Change the prototypes of pdelete(2) and preset(2) to: + + int pdelete(int, int (*)(void)); + int preset(int, int (*)(void)); + + sys/stat.h: + Add the following prototype: + + int umask(int); + + This header file contains the following guard macro: + + #ifndef __BSD_TYPES__ + #include + #endif + + it should be changed to: + + #ifndef __SYS_TYPES__ + #include + #endif + + sys/times.h: + The last line should be modified so that the text following + the #endif is in a comment, otherwise it is not legal C + source code: + #endif /* _SYS_TIMES_H_ */ + + sys/types.h: + Change the typedef of sig_t to: + typedef void (*sig_t)(void); + + The typedef for use_t has an extraneous '_' character. Of + course, if you hit this and aren't compiling the kernel + you're doing something wrong since the _IN_KERNEL macro + should not normally be defined: + typedef unsigned char use_t; + + sys/wait.h: + Add the following declaration: + int wait(union wait *); + + time.h: + Add the following declarations: + + void tzset(void); + #ifndef _SVR4 + struct tz * timezone(void); + #endif + + types.h: + Before the definition of TRUE, add in the following: + + #undef TRUE + #undef true + #undef FALSE + #undef false + + unistd.h: + As explained in the lenviron documentation, rename the + execve() system call to _execve() (if you have installed + /usr/lib/lenviron as described in Q#1307 or Q#1308). Insert + or uncomment prototypes for execl(), execlp(), execv(), + execve(), and execvp(). The execve() prototype should be: + + int execve(const char *,char * const *,char * const *); + + Insert the following prototypes. They are not yet defined + in any standard, however they are common routines and are + provided in libc for GNO v2.0.6: + + char * dirname (const char *); + char * basename (const char *); + +Q#1307: GNO with ORCA: What libraries are used for the combination of + GNO v2.0.4 and ORCA/C v2.0.x? + +A#1307: You must have the following libraries in the sequence given: + + /lib/lcrypt (GNO v2.0.1) + /lib/lregexp (GNO v2.0.1) + /lib/lstring (GNO v2.0.1) + /lib/ltermcap (GNO v2.0.1) + /lib/libc (GNO v2.0.4) [rename to "nlibc" for HFS] + /lib/OrcaLib (GNO v2.0.1) + /lib/PasLib (ORCA/Pascal v2.0.x, required if and only if + you use ORCA Pascal) + /lib/SysFloat (ORCA/C v2.0.x) + /lib/SysLib (ORCA/C v2.0.x) + + The following libraries are recommended. The sequence here is not + important as they will be read in the order specified on the occ(1) + command line: + + /usr/lib/lflex + This provides a main() routine suitable for a + flex(1) generated parser. + /usr/lib/lgnoasm + Provides asm replacements for some libgno symbols. + These include "CommandLine", "timezone", "tmpnam". + /usr/lib/lenviron + [This library is obsoleted as of GNO v2.0.6 -- + these routines have been incorporated into libc.] + + This has a replacement for getenv/setenv, exec*, + and other routines that ease the porting of UNIX + programs. Note that the prototype and implementation + of execve(2) changes from that defined in the GNO + docs. + /usr/lib/lgetline + GNU line input editing. + /usr/lib/lgetopt + A GNU replacement for the getopt(3) package. + /usr/lib/lttylock + Provides locktty(3) and unlocktty(3) routines. + /usr/lib/lstack + [This library is obsoleted as of GNO v2.0.6 -- + these routines have been incorporated into libc.] + + Stack checking routines. These are useful for + verifying how much stack space your final program + uses so that it may be reduced to a minimum. The + currently available archive contains an object file + which may be converted to a library file by + makelib(1). + /usr/lib/gnulib + A GNU replacement for the alloca(3) routine and + the getopt(3) package. This partially overlaps + the lgetopt library. + +Q#1308: GNO with ORCA: What libraries are used for the combination of + GNO v2.0.4 and ORCA/C v2.1.x? + +A#1308: You must have the following libraries in the sequence given: + + /lib/lcrypt (GNO v2.0.1) + /lib/lregexp (GNO v2.0.1) + /lib/lstring (GNO v2.0.1) + /lib/ltermcap (GNO v2.0.1) + /lib/libc (GNO v2.0.4) [rename to "nlibc" for HFS] + /lib/OrcaLib (ORCA/C v2.1.x) + /lib/PasLib (ORCA/Pascal v2.1.x, required if and only if + you use ORCA Pascal) + /lib/SysFloat (ORCA/C v2.1.x) + /lib/SysLib (ORCA/C v2.1.x) + + Note the OrcaLib should be the one shipped with ORCA/C v2.1.x. + You can use it provided that you apply the va_end fix described + in Q#601. + + You should also install the list of recommended libraries listed + in the latter part of Q#1307. + + Some people believe the ORCA/C v2.1.x library won't work properly + with pipes. This has neither been demonstrated nor disproved. + If you find hard evidence either way, please contact Devin Reade + at the address at the top of this FAQ. + + If you need pipes, you can try the libraries that shipped with GNO + v2.0.1, but you will not get any of the Byte Works bug fixes. Also, + it has been reported that the GNO modifications introduced stdio + bugs that weren't in the original version (no details available). + + Note that you _must_ keep the versions of OrcaLib, SysFloat, and + SysLib consistent; you cannot use some from OrcaC v2.0.x and others + from OrcaC v2.1.x. You may run into problems from unexpected + behavior to memory trashing. + +Q#1309: GNO with ORCA: What libraries are used for the combination of + GNO v2.0.6 and ORCA/C v2.0.x? + +A#1309: This combination is no longer supported. You will have to + upgrade to ORCA/C v2.1.x. + +Q#1310: GNO with ORCA: What libraries are used for the combination of + GNO v2.0.6 and ORCA/C v2.1.x? + +A#1310: You must have the following libraries in the sequence given. You + should not add any other libraries to this directory as it will + slow down linking for all programs. + + /lib/libc (GNO v2.0.6) [rename to "nlibc" for HFS] + /lib/lsaneglue (GNO v2.0.6) [renaem to "nlsaneglue" for HFS] + /lib/OrcaLib (GNO v2.0.6) + /lib/PasLib (ORCA/Pascal v2.1.x, required if and only if + you use ORCA Pascal) + /lib/SysFloat (GNO v2.0.6) + /lib/SysLib (ORCA/C v2.1.x) + + The following libraries are recommended. The sequence here is not + important as they will be read in the order specified on the occ(1) + command line: + + /usr/lib/lflex + This provides a main() routine suitable for a + flex(1) generated parser. + /usr/lib/lgetline + GNU line input editing. + /usr/lib/lgetopt + A GNU replacement for the getopt(3) package. + /lib/lstring + Non standard string routines. (*** Obsolete?) + /lib/ltermcap + Terminal capabilities library. Moved from /lib. + /usr/lib/lttylock + Provides locktty(3) and unlocktty(3) routines. + /usr/lib/gnulib + A GNU replacement for the alloca(3) routine and + the getopt(3) package. This partially overlaps + the lgetopt library. + + The following libraries either are obsolete or have been merged with + libc and should NOT be used: + + /lib/lcrypt + /usr/lib/lgnoasm + /usr/lib/lenviron + /usr/lib/lregexp + /usr/lib/lstack + +%Section% System Configuration: +============================== + +Q#1003: What patches should I have applied for GNO? + +A#1003: GUPP (Grand Unified Patch Program by Nathan Mates) is recommended + for fixing memory-trashing bugs present in GNO kernel versions + v2.0.4 and v2.0.6-beta. GUPP also does other patches that may be + applicable to programs running under GNO. GUPP will not touch + kernels earlier than v2.0.4 even though those bugs probably exist + in earlier versions of the kernel. + + GUPP is available from the ground and caltech sites, and also + at ftp://ftp.visi.com/users/nathan/a2software/gupp.shk. See also + Q#704. + +Q#1001: How do I change the information that's printed before the login + prompt? + +A#1001: Check in the /etc/gettytab file. There's a line near the top that + contains the login string. It is preceded by an "im:", which is + an acronym for "initial message". + +Q#1002: How do I map /usr, /local, /var, and other partitions to GS/OS + volume or directory names? + +A#1002: The kernel provides this functionality through the namespace + facility, which is configured in /etc/namespace. See the Kernel + Reference Manual for details. See also the Kernel Bugs section + of question #704 regarding the format of the file. + +Q#1004: How do I set up cron? + +A#1004: There are man pages for this that were distributed with the v2.0.4 + GNO update, but they don't quite match the implementation provided + with the Multi-user 2.0 package. + + To activate cron, you must uncomment its entry in the /etc/inittab + file. See the init(8) man page for the format of this file. + + Cron is controlled through the /etc/crontab file. Unlike its UNIX + counterparts, the GNO cron does *not* support setting of environment + variables in the crontab file. These would be lines of the form: + SHELL=/bin/sh + MAILTO=gdr + + Any line which begins with a hash (#) character is considered + to be a comment and is ignored. + + All other lines in this file are expected to have five space- + delimited date/time fields, followed by a user name field, followed + by a command. The first five fields are: + minute (0-59) + hour (0-23) + day of month (1-31) + month (0-11) + day of week (0-6) (appears to be ignored) + Multiple values may be specified either separated by commas, + or as a range separated with a hyphen. + + Following the five date/time fields is a username field. + Although it has to be present, it does not appear to be used + by the current cron implementation. + + The last field is the command to be executed at the specified + time. Unlike UNIX cron implementations, these commands _are_not_ + executed from a subshell, so meta characters and file redirection + cannot be used. + + You cannot split cron commands into separate lines of the crontab + file. Any '%'s in the command are replaced by newlines. Unlike + UNIX crons, the text appearing after a '%' character _is_not_ + piped to the input of the command. + + BUG WARNING: Do not use more than 10 multiple values in each + of the date-time fields; if there are more than + 10, cron's memory structures are reported to get + corrupted. + +Q#1006: Why won't my entry in the inittab file work correctly? + +A#1006: There are two common sources of problems. The first is due + to improper syntax in the inittab file. See the inittab(5) and + initd(8) manual pages for the correct syntax. + + The second common problem is not due to the inittab file, but + rather because the command you are trying to invoke is being + invoked incorrectly. The way to check if this is the case is + to run the command interactively and see what diagnostic messages + appear. You should also check the system log files for messages + (see syslogd(8)). + +%Section% Networking: +==================== + +Q#401: Does GNO provide TCP/IP and/or SLIP support? + +A#401: Most of the required kernel support is available in GNO v2.0.4, + but it is not complete and there is nothing to take advantage + of it. However, the remaining kernel support has been added + to the upcoming version. This, however, does not include the + TCP stack, which is considered to be a separate product from + GNO. + + At this time, the kernel has only been modified to recognize + GS/TCP. + +Q#414: Is GS/TCP available? Where can I get it? + +A#414: GS/TCP is not yet available to the general public. Information + on it's status and an overview of the project is available from + the GS/TCP web page: + + http://www.geeks.org/~taubert/gstcp/index.html + +Q#415: Does Marinetti work with GNO? + +A#415: Recently, Richard Bennett has released Marinetti, a beta-level + TCP/IP stack for the IIgs that does not require GNO. + + Experimentation with the Marinetti/GNO combination has been + sketchy so far. However, here are some initial observations, + in no particular order: + + - Running individual programs that rely on Marinetti seem + to work the same way under GNO as they do without GNO. + (However, see the following observations.) + + - Processes are unable to block while waiting for input. + Therefore, they must do a "busy wait". While this does + not normally matter on the GS, it is considered to be + Rude Behavior under GNO since it steals clock cycles that + could be used by other processes. + + - It would be inadvisable to have Marinetti block a process + that is waiting on input, since GNO is in a mutex state when + accessing the ToolBox. Therefore, if Marinetti were to block + a process, then all of GNO would be blocked. + + - Development on the Marinetti/GNO combination is still in the + planning stage. + + - The optimal method for programs running under the GNO/Marinetti + combination seems to be the the same way that GNO interacts + with GS/TCP; through the kernel. If programs limit themselves + to using the kernel interface (which uses BSD sockets) then + the kernel could potentially use either GS/TCP or Marinetti, + whichever is active. The kernel could worry about blocking + processes, ensuring an appropriate use of resources. The + kernel interfaces (user libraries) could perhaps be written + to use Marinetti directly in the case where GNO is not running. + This would allow a GNO-aware program to work either with + or without GNO. + + Programs that use the Marinetti IPC mechanism directly will + probably still work under GNO, but can be expected to have + problems multitasking. + + By the way, the above paragraph is pure rambling and supposition + by the FAQ maintainer. The GNO kernel currently knows nothing + about Marinetti. + + - Richard has expressed a willingness to work with the GNO + development team to ensure that the two products can coexist. + + For the latest status on Marinetti, see the Marinetti home page: + + http://www.zip.com.au/~kashum/marinetti + + If you have additional information regarding the Marinetti/GNO + combination, please email the maintainer of this FAQ. + +Q#402: What TCP/IP network utilities are available? + +A#402: Several utilities have been written and should be made available + with the release of GS/TCP. They include: + ftp, telnet, irc, ping, finger, rcp + +Q#403: Is there a WWW browser for GNO and GS/TCP? + +A#403: A text oriented browser has been ported by Derek Taubert and + requires the GS/TCP package. Derek has also done some work on + a Graphics based WWW browser. Neither package has as yet been + released. + + There are no known WWW browsers available yet that are based + on Marinetti. This is subject to change, and you should see + the Marinetti web page for the latest details. See Q#415. + +Q#411: Can I use a serial card or internal modem with GNO? + +A#411: Currently the GNO serial drivers only support the two built-in + serial ports. This does not imply that you cannot use a + serial card in a remote machine (such as a IIe) that is connecting + to your IIgs running GNO. + +Q#413: What should I use for my modem port control panel settings. + +A#413: These settings will usually work. See the Notes, below. + + Device Connected: Modem + Line Length: Unlimited + Delete first LF after CR: No + Add LF after CR: No + Echo: No + Buffering: Yes + Baud: 19200 (1) + Data/Stop Bits: 8/1 (2) + Parity: None (2) + DCD Handshake: Yes + DSR/DTR Handshake: Yes + XON/XOFF Handshake: No + + Notes: 1. The baud should be set to whatever is appropriate + to your system. Unless you are using a modem or + serial line that is slower than 14400 bps, this will + almost always be "19200". + + 2. Set data/stop bits and parity as appropriate for your + site. 8N1 is the most common setting. + +Q#404: How can I initialize my serial ports at GNO "boot" time? + +A#404: The easiest way to do this is through initd(8). Add the following + lines to your /etc/initab file: + + # this will initialize the modem port on startup + md:b:once:i:/usr/sbin/runover .ttya /bin/stty 38400 + + You should of course change "38400" to whatever speed is appropriate + for your site. + +Q#405: How do I hook up a terminal to the IIgs' printer/modem port? + +A#405: This answer describes hooking up a terminal to the printer port. + Hooking one up to the modem port will be similar except that + .ttya should be used instead of .ttyb. + + On the hardware side, you will need a mini DIN 8 to DB25 printer + cable. This should be connected from the IIgs' printer port + to the port on the terminal that would normally be hooked to + a modem. + + Next, you have to run a getty(8) over the printer port. Add + this line to your /etc/inittab file: + + pp:23478:rest::/usr/sbin/getty 8bit.xxxx .ttyb + + where xxxx is the speed. Remove '78' from '23478' if you want + to run it only in multiuser mode. See also Q#404 regarding + initialization of the serial port. + + In order for the change to take effect, you either have to quit + and restart GNO, or type '/bin/init q' (without the quotes). + +Q#406: How do I enable GNO to activate dialup access. + +A#406: This question is not about using your IIgs to dial _out_ to another + machine. It means that you're allowing _other_ machines to + dial _in_ to your IIgs running GNO. + + The first thing you should consider is whether you _really_ want + to do this. GNO doesn't have any user/group file permissions, + so as soon as someone is logged into your IIgs, they will have + read/write access to _all_ of your files. Because of this, the + only layer of protection you have is dialup/getty and the security + of the password file (including how well _all_ passwords are + chosen). There has been no known investigation into the security + of the GNO dialup/getty. + + That said, the way to enable dialup access is through the dialup(8) + program. It is invoked as + dialup tty [speed [init_string]] + + Normally this would be done at GNO "boot" time through the initd(8) + facility. Add the following to your /etc/inittab file: + + # This enables the modem for remote dialup (_into_ the IIgs) + # when in multiuser mode (run level 2 or 3). + t2:23:rest::/usr/sbin/dialup .ttya 38400 ate1qs0=1s11=50\\r + + Ensure you substitute the "38400" with a speed appropriate to your + hardware. Note that "14400" is not considered to be a valid speed. + If you are using a 14400 kb/s modem, you should use "19200" as the + speed setting. + + See also Q#404 regarding initialization of the serial port. + + You should also replace the initialization string with one suitable + for your modem (consult your modem manual). The one shown above + contains the following HAYES commands: + at (start command) + e1 local echo on + s0=1 auto answer on + s11=50 set touch tone duration to 50ms + \\r escaped carriage return (ends command) + +Q#407: What do I use for a ProTERM termcap entry? + +A#407: This termcap entry is suitable for use with any UNIX machine + (that uses termcap rather than terminfo) being accessed from + ProTERM: + +# +# ProTerm Special +# +pt|pse|proterm-special|Proterm Special Emulation:\ + :ae=^N:am:al=^V:bl=^T^A^E@:bs:bw:cl=^L:cm=^^%r%+ %+ :co#80:ce=^Y:\ + :cd=^W:dc=^D:dl=^Z:do=^J:eo:eA=^P:ho=^X:ic=^F:il=^N:i3=^L:\ + :is=^L^N:kd=^J:kl=^H:kr=^U:ku=^K:le=^H:li#24:ll=^^ 8:mb=^O:md=^O:\ + :me=^N:mh=^O:mr=^O:nd=^U:nl=\n+^A:pt:rs=^N:se=^N:so=^O:ta=^I:\ + :ue=^N:up=^K:us=^O:xn:ns:as=^P:bc=^H:r1=^N:r2=^N:r3=^N:\ + :ms:mi:sf=^J:sr=^K:as=^P:i1=^N:i3=^N:NP:dn=^J: + +Q#408: Is there a mail/news package available for GNO? + +A#408: There is a rudimentary one called MuGS by Brian Tao. It requires + a shell account (presumably on a UNIX box) for part of the + software. The base MuGS package handles news articles that + are spooled on the UNIX machine's local disk. There is an NNTP + (Net News Transfer Protocol) patch by Devin Reade that allows + MuGS to work with an NNTP server. MuGS is available as described + in its describe(1) entry (see Q#304). + + Because of a lack of TCP/IP there is no software for GNO v2.0.4 + that allows a IIgs to connect to the 'net via NNTP or SMTP. + + Jeff Markham provided the following suggestion: + + I've been using the gmail system, and I've come up with + something that seems to work ok with gmail and sendmail. + + Create the following two files. The first is /bin/send: + [gdr: The second and third lines should be a single line + without the escaped newline. It has been printed + here as is for clarity: + + #!/bin/gsh + /bin/foreach x /var/spool/sendmail/out/* \ + < /bin/send.dat > .null + + The second is /bin/send.dat: + + tail +2 $x | /usr/sbin/sendmail + rm $x + + That combo works well enough to send the mail on it's way. + The way I use to get around gmail's need for all config + files to be in the same folder as the exe is by using the + following /bin/mail file: + + #! /bin/gsh + rm /bin/signature /bin/gmail.cf > .null + cp $HOME/gmail/* /bin + gmail + mv /bin/gmail.o $HOME/gmail + send + + It copies all the set-up files, calls gmail, returns the + only needed file to the users account and sends any mail. + + Comments on my process are welcome. + +Q#409: How do I use copycat? + +A#409: There seem to be two versions of copycat available. One version + takes two tty names on the command line, the other takes only one. + It is unclear which version numbers correspond to which behavior; + the version that takes only one argument lists itself as v1.5.0, + however the documentation for v1.5.0 definitely lists a requirement + for two arguments. + + That said, there are a few ways to use copycat. This answer will + assume that you wish to communicate from the GNO console with a + terminal hooked to your modem port. If you are using the TMTerm + NDA, then substitute ".ttyco" in this example with ".ttyq0". + + The first thing you must do to use copycat is ensure that your + serial port is properly initialized. Use the stty(1) command + like this: + stty 38400 < .ttya + You should substitute "38400" with whatever speed was used for + setting up your link. ".ttya" is the modem port device. (For + the printer port, use ".ttyb".) + + Now all you have to do is issue the following command. The second + argument may not be required or accepted in your version of copycat: + copycat .ttya .ttyco + + You will see the prompt: + Break character is '^\' + + You are now connected with whatever is hooked up to your modem + port. To get the copycat command prompt, type the control + character (CONTROL-\). + + See the copycat documentation and man page for more details. + It explains how to do interesting things like allowing a terminal + on your printer port to use your modem without interfering with + the GNO console. + +Q#410: How do I use rz/sz? + +A#410: rz/sz are usually used in conjunction with copycat. The important + part to remember is that while copycat is used to control the + remote end of the file transfer, it must not be running _during_ + the transfer. + + The following example assumes you are sending a file from the + remote machine to the IIgs. Steps taken to go the other direction + will be similar. + + The first step is to initialize your modem port and start copycat + as explained in Q#409. In this example, "unix% " is used as the + prompt on the remote machine, and "gno% " as the prompt on the + IIgs. Extraneous blank lines have been deleted. + + gno% stty 38400 < .ttya + gno% copycat .ttya + Break character is '^\' + unix% + + Next, start the file transfer on the UNIX end. There are problems + with some versions of UNIX sz if the "-l1024" flag is not given + (others don't recognize this flag). See the rz/sz README.GNO + file and the UNIX sz man page for details. Remember to use the + "-a" flag if you want a text file transfer: + + unix% sz -a testfile.bsq + **B00000000000 14 + + Now type the copycat break character, CONTROL-\, quit from copycat, + and start rz on the GNO side: + + copycat> quit + gno% rz < .ttya > .ttya & + + When the file transfer is finished, don't forget to log off the + remote machine. To get there, you have to restart copycat: + + gno% copycat .ttya + Break character is '^\' + unix% logout + ^\ + copycat> quit + gno% + +Q#412: Why do I get errors when trying to access the (modem/serial) port? + +A#412: This is usually caused by serial port configuration problems. + Common symptoms may be: + % copycat .ttyco .ttya + Error opening tty .ttya, aborting. + or + % /usr/sbin/getty 8bit.38400 .ttya + getty: .ttya: I/O error + + The first thing to check is that the following GNO serial port + drivers exist: + /dev/modem + /dev/printer + + Next, ensure the following two lines are in your /etc/tty.config + file, and that they are uncommented: + modem 2 .ttya + printer 1 .ttyb + + Finally, ensure that SIM (the Serial Interrupt Manager) is present + and active. This is an init in your system.setup directory: + */system/system.setup/sim + + Remember to reboot your system if you've made any changes in + or to comply with the above requirements. + +%Section% Porting UNIX Programs to the GNO Environment: +====================================================== + +Q#901: What programs/utilities should I have to port UNIX source code to GNO? + +A#901: Strictly speaking, all you need is a C compiler (since UNIX source + tends to be in C). However, there are a few programs that + can be considered "essentials" for doing ports. All of these + are mentioned in the section on "Compiling": + + ORCA/C, occ, dmake + +Q#902: What are the common problems encountered when porting UNIX source + to GNO? + +A#902: The first thing to watch for is known compiler and library bugs. + Soenke Behrens maintains the current ORCA/C bug report list. + You should keep the contents of this list in mind when examining + the target source code. The ORCA/C bug report list may be found at + + http://www.arrowweb.com/sbehrens/obugs.htm + + This list has been considerably shorted since the release of + ORCA/C v2.1.0. If you have an earlier version of ORCA/C, you + should seriously consider an upgrade. + + The following items should be watched for, in no particular order. + Since UNIX source is usually in C, that language is assumed for + the rest of this section, where relevant: + + sizeof(int) + The size of the type "int" is implementation-defined. + While most modern C compilers use 32 bits, ORCA/C still + uses 16 bits since this is the "natural" integer size of + the 65816. This also results in more effective code + generation. + + While the size of an int shouldn't make a difference to + any well-written code, there is some available source code + that assumes that ints are 32 bits. You should watch for + this in any code that does bit manipulations. You should + also watch for code that freely converts between integers + and pointers. GNU (Free Software Foundation) software + is often bad for this. + + recursion + When possible, recursion should be avoided when programming + on the Apple IIgs. This is because recursion invariably + causes stack growth and the stack can only exist in bank + zero. This means that the maximum space available for + the stack is 64k. In practise, it is much smaller. + + This problem is exacerbated under GNO where all processes + must share the available stack space (each process has its + own stack, though). + + Any program that uses recursion can be rewritten to use + iteration instead. You should try to do this when possible. + If you _do_ use recursion, don't allocate a huge stack; + this will keep other programs from executing. Also, you + should leave in stack checking and stack repair (if + programming with ORCA/C) to ensure that your recursion + does not crash the machine if it goes too far. + + reference to absolute file descriptors + True UNIX machines invariably use the file descriptors 0, 1, + and 2 for standard input, standard output, and standard error, + respectively. Under GNO, the file descriptors used are 1, + 2, and 3. + + This causes a problem when source code is written to use + these descriptors directly. You should search your code + for references to these descriptors, typically in calls + to open, close, read, write, dup, dup2, and fcntl. + + Instead of replacing these digits with other digits though, + you should use the macros STDIN_FILENO, STDOUT_FILENO, and + STDERR_FILENO defined in . This will ensure + that your source is kept portable. + + fork + Because of problems that are discussed in the fork(2) man + page and the kernel reference, the fork system call under + GNO is different than other versions of UNIX. Besides + having a different prototype, the parent and child process + share the same address space. In this respect, GNO is less + a multitasking environment than it is a multithreading + environment. + + Search for calls to fork; you will have to rewrite these + sections of code. See also the man page for fork2(2); it + may be more suited to your purposes. + + Also note than when compiling routines that make a call + to fork, you should turn off ORCA/C's stack repair code. + This means that you should be using an optimization level + of at least 8. + + read/write of newline character + Most UNIX systems use LF (ASCII 0x0a) as the line delimiter. + Both Apple II and Macintosh computers use CR (ASCII 0x0d) + as the line delimiter. The C newline character is '\n'; + ASCII 0x0a. + + While the stdio routines (fprintf(3), fread(3), etc) usually + make this difference unnoticable by doing CR-->LF translation + on input and LF-->CR translation on output, no such + translation is done on files accessed through read(2) and + write(2). Specifically, the GNO open(2) does not recognize + the ORCA/C O_BINARY bit in it's second argument. + + Therefore, if the program you are porting makes calls to + read(2) and write(2), watch for the '\n' character in your + code. You may have to change this to '\r'. Don't do it + blindly, because many programs will use both stdio and + operations on the bare file descriptors. + + One suggestion is to modify your programs low-level I/O + routines to modify the I/O buffer prior to calling write(2) + and after calling read(2). + + variadic functions + Some (poorly written) UNIX programs have variadic functions + where the number of provided arguments don't match the + number of arguments expected by the called routine. Even + though this is in some cases legal ANSI/C, versions of + ORCA/C prior to v2.1 would puke magnificently when encountering + such code. Some of these cases are now handled in a more + robust fashion by ORCA/C v2.1 and later. + + If you are _defining_ (as opposed to using) variadic functions, + you must turn off stack repair code around the definitions + of those functions. + + The ORCA/C manual (and especially the release notes for + v2.1) have important and detailed information on this topic. + See the sections on the optimize and debug #pragmas. + + open, chmod, fchmod, creat, st_mode, stat, fstat, lstat + In general, the bits in the mode parameter of these + functions do not directly map between UNIX and GNO + implementations. If your application is using macros + such as S_IREAD or S_IWRITE for the mode parameters, and + those macros are taken from the system header file + , then you probably don't need to modify your + application. + + If, on the other hand, your application is using its own + constants for the mode parameter, you should convert it + to use the standard macros. Failure to do so may result + in files with strange GS/OS flags set, or file tests failing + in your program. + + /dev + One of the UNIX philosophies is that "everything is a file". + The /dev directory on UNIX systems contain device special + files. Accessing these files is the way to access the + relevant hardware. + + For GNO programs, you should not access devices in the + /dev directory. For example, opening "/dev/console" for + writing will not have the expected effect. Instead you + should open the corresponding GS/OS device, ".ttyco". + + The portable (and suggested) method of handling these cases + is not to change the value of the string (in this example) + from "/dev/console" to ".ttyco". Instead, use the macros + defined in the file . For this example, one would + use the macro _PATH_CONSOLE. + + standard path assumptions + This one is closely tied in with the "/dev" description + above. The file contains macros for various + standard paths. The macros, instead of the actual paths, + should be used to maximize portability. + + signal handlers + When a signal handler is called, the data bank register + may not have an expected value. If your program references + global scalars, it may crash. To avoid this, all functions + used as signal handlers should have their definition + preceded by + #pragma databank 1 + and followed by + #pragma databank 0 + + validity of pathnames + Most programs make assumptions about what constitutes + a valid file name. For most modern Unices, a valid + file name follows the POSIX portable filename character + set: The characters a-z and A-Z, the digits 0-9, and + '.', '_', and '-'. The '-' is not used as the first + character of a file name, and '/' is the directory + separator character. The maximum filename length is + at least 14 characters, and the maximum pathname length + is at least 255 characters. + + Now this is different from what is available under GNO. + The ProDOS FST provides only a subset of the above. The + HFS FST provides a superset, but HFS is too slow, too + buggy, and too unmaintainable for many users. + + The problem is also compounded by the fact that under + GS/OS, the ':' is a directory separator. '/' may be used + but it is mapped internally to ':'. + + Unfortunately, there is no general consensus on how to + handle pathnames under GNO. Here are some opinions, all + of which refer to user code; the GNO kernel treats pathnames + the same way that GS/OS does: + + - the ':' character should be mapped to '/'. This prohibits + the use of '/' in _file_ names. It also provides the + highest degree of "UNIX compatibility"; or + + - the '/' character should be mapped to ':'. This is more + in line with GS/OS, but can require extensive rewrites + of ported UNIX programs; or + + - use dynamic directory delimiters. The ':' character is + always considered to be a directory separator. The '/' + character is considered to be a directory separator unless + it was preceded at some point by a ':', in which case it + is part of the file name. Having a '/' appear before ':' + in a pathname is illegal. This is the closest to GS/OS, + but also has some problems with POSIX compliance. For + example, the PATH environment variable is _supposed_ to + be a list of pathnames delimited by the ':' character. + This implies that one cannot use the ':' as a directory + delimiter when defining PATH, and that directories in + PATH must not contain '/' as a regular character. + + Regardless of which method you use to do filename, pathname, + and directory separator mapping, you should verify that + the pathname is legal for your target filesystem. GS/OS + provides a mechanism to do this through the JudgeName + system call. + + Also watch out for references to the root partition. For + other UNIXs, this is the pathname "/", which is a not legal + directory under GS/OS (and therefore GNO). Hopefully the + context of your program will give you an idea how to handle + such a directory reference in a sensible manner. + + unlink + Many UNIX programs unlink (delete) files while they still + have them open. Under true UNIX systems, this means that + the file will be deleted as soon as it is closed. This is + is not done under GNO, and attempting to unlink an open file + will fail, and the file will remain on the file system after + it is closed. If your program relies on this behavior, you + will have to find a work-around. One partial solution is + to register a clean-up function via atexit(3) that deletes + your files for you. [This method is not suitable for + daemons or other long-running programs.] + +Q#903: Are there any other recommendations for porting programs? + +A#903: There probably are as many opinions as there are programmers. + However, here is a list that seems to work well. Using C as + the source language is assumed: + + - Use the occ(1) "-w" flag (#pragma lint -1) whenever possible. + You will have to modify your code if it doesn't use prototypes, + but this is more likely to catch errors and incorrect assumptions. + If you really need to be compatible with K&R compilers, you + can use the following paradigm in your code: + + #include + int main __P((int argc, char **argv)); + + int main + #ifdef __STDC__ + (int argc, char **argv) + #else + (argc, argv) + #endif + int argc; + char **argv; + { + ... + + You may have to prototype some of your system header files. + This should not be necessary with the ORCA/C v2.1 header files + (they're already prototyped), but is likely necessary with + earlier versions and some of the GNO v2.0.4 (and earlier) system + header files. See also Q#1302 and Q#1306. + + - Whenever possible, compile with the occ(1) "-G25" during + development. This will ensure that, in the event of stack + trashing and similar problems, that you get a meaningful + traceback and that your machine (usually) doesn't crash. + + If you are using the Splat! debugger, you should use "-g" instead + of "-G25". See also the notes on fork(2) in question Q#902. + + Make sure you read the both the ORCA/C manual and release notes; + there are times (such as within variadic functions) that you + cannot use stack checking or repair code. + + When you're finished development, you can replace the debugging + flag with "-O" for optimization. Don't forget to test your + optimized program before you release it! + +%Section% Compiling: +=================== + +Q#505: Which language should I use? + +A#505: Since GNO is not language-specific, it doesn't really matter. + + From a practical stand point though, either assembly or C tend + to be the languages of choice. Both have their strengths and + weaknesses. Assembly can be more efficient but in general requires + more time to program and more attention to detail. Much of the + available UNIX source code is in C. Using C can result in a quicker + development cycle and more portable code, but it often results in + a slower program. + + A big part of the decision is dependent on which language you + already know. If you are comfortable in one, stick with it + until you need to try something else. If you know neither, + then the decision becomes religious -- ie: there is no correct + answer, and the response you get will depend on whom you ask. + + Some people have also successfully used Pascal for GNO + programming, although it is not as suited to GNO as is C or + assembly. + + If you program in C, the only realistic choice for a compiler + is Byte Works' ORCA/C. As of v2.1.0, it is relatively bug free + and close to ANSI-compliant. + + If you program in assembler, Byte Works' ORCA/M is recommended. + Merlin-8/16 (by Roger Wagner) is also reputed to be suitable + (although not as common). + +Q#506: Should I purchase the ORCA Subroutine Library Source? + +A#506: The sources are not required, but they are recommended. Some + reasons are: + - they allow you to see how a function is implemented + - they allow you to investigate possible library bugs + - they are good examples of assembly programming + - they are inexpensive + +Q#501: What is occ? + +A#501: occ is a front end to ORCA/C written by Soenke Behrens. It makes + ORCA/C's invocation more "UNIX-ish" and is the recommended + interface between dmake(1) and ORCA/C. + +Q#507: What is dmake? + +A#507: dmake is a variation of the UNIX "make" facility. It is used + on large software projects for defining when and how files should + be updated (typically compiled or linked), based on dependency + lists. It's behavior is controlled through the use of a + "makefile" (sometimes "makefile.mk"), which is a text file + defining dependency graphs, rules, and actions. + + After definition of the makefile, a project can often be built + (perhaps tested and installed as well) just by typing "dmake", + assuming there are no compilation or other errors. Only the + work that is required will be done. + + For more details, see the dmake(1) man page. + +Q#504: What macros should I be using for conditional compilation? + +A#504: There are four general areas where certain "standard" macros + are used ("standard" is quoted because only those explicitly + annotated correspond to ISO/ANSI or other standards). Where + the macros aren't predefined by current compilers, they should + be defined in source, header, or makefiles when necessary: + + - Architecture: + These macros tend to be lower case with double leading- + or trailing-underscores, such as "__sun4__" or "__parisc__". + + No IIgs compilers currently predefine an architecture, + but "__appleiigs__" is recommended for Apple IIgs + specific code. + + - Operating System: + These macros tend to be upper case and may or may not + use underscores. Examples are "_AIX" and "SunOS". + + No IIgs compilers currently predefine an os macro, + but "__GNO__" is recommended for GNO-specific code. + + - Compiler: + These macros tend to be upper case and may or may not + use underscores. Examples are "__LCC__" and "__GNUC__". + + ORCA/C predefines "__ORCAC__". APW/C predefines "APW". + + - Language and other standards: + The "__STDC__" macro may be used for determining ISO/ANSI C + compliance. It is the responsibility of the compiler to + define (or not define) this macro appropriately. + + If "_POSIX_SOURCE" source is defined, the source may + be written with the assumption that all symbols defined + by POSIX Standard 1003.1 are available in the environment. + This symbol is expected to be defined by the user as + necessary. GNO isn't yet POSIX compliant, but it's getting + there. + + If "_BSD_SOURCE" is defined, all symbols are expected to + be 4.3BSD compliant. This implies "_POSIX_SOURCE". Again, + GNO isn't there yet but it's progressing. + + "KERNEL" is defined when building the GNO kernel. You will + see this macro in the GNO header files, but you should not + define it. + + "__cplusplus" is predefined by C++ compilers, of which there + are none for the IIgs. It is the responsibility of the + compiler to define (or not define) this macro appropriately. + Explanation of this macro was given since you occasionally + see it in GNO header files ... + + Other macros are defined either by the compiler or in header files, + but these are the main ones for user code conditional compilation. + See the relevant documentation (compiler manual, ISO/ANSI or POSIX + standards, GS/OS reference manual) for more details. + +Q#502: When I'm using the new header files (post-v2.0.4), sometimes ORCA/C + can't find my header files. Why? + +A#502: There are a few potential causes for this problem, some of which + are not completely understood. You should try the following + steps: + + 1. Ensure that the correct "#pragma path" values are in your + 13/orcacdefs/defaults.h file (see Q#1305). + + 2. Ensure that all of your header files are of type SRC and + auxiliary type CC. This includes headers in the directories + specified via "#pragma path" in 13/orcacdefs/defaults.h + (see Q#1305), any directories specified by the occ(1) "-I" + flag, and your current directory. + + 3. Remove any *.sym files you have and try compiling with the + occ "-i" flag. This has been reported to eliminate the + problem; presumbably there is an out-of-date cache being + used in the precompiled header file. + + If you are using dmake, you can add "-i" to your default + CFLAGS environment variable in /usr/local/lib/startup.mk. + + If you use neither dmake nor occ, you can add "#pragma ignore" + to your 13/orcacdefs/defaults.h file. + + 4. If your problem is intermittent, try calling the purge(1) + command when the problem occurs. + +%Section% Libraries and Header Files: +==================================== + +Q#601: I keep getting "va_end" as an unresolved symbol when linking. Why? + +A#601: You should only be seeing this if you are trying to use the + ORCA/C v2.1.x libraries with GNO v2.0.4. (See Q#1301 and Q#1308). + + The GNO v2.0.4 libraries were compiled with a version of ORCA/C + that still used a function version of va_end(3). ORCA/C now + correctly defines va_end(3) as a macro. + + If you attempt to use a variadic function from the GNO v2.0.4 + libraries (such as open(2)), then you will get an unresolved + va_end reference. To solve this problem, download and install + the archive "vaendPatch.shk", available from ground or caltech. + +Q#602: Why do I keep getting "getc" and "putc" as unresolved symbols + when linking? + +A#602: This is an indication that the files 13/OrcaLib, 13/SysFloat, + and 13/SysLib are not properly matched. You cannot mix these + files from different versions of ORCA/C. The OrcaLib shipped + with GNO can only be used with particular versions of the other + two libraries. You should (re)read the section in this FAQ on + "Installing GNO with ORCA". + +Q#604: How can I tell what order my libraries are in? + +A#604: Try the command 'ls -1n' or 'ls -ln'. + +Q#603: How can I sort my libraries (or other files)? + +A#603: This isn't really a GNO question, but it's included here because + of its relevance to Q#604 and the section on "Installing GNO with + ORCA". + + For ProDOS Partitions: + There are various ways to do this. One of the easiest is to + use ProSEL or another utility which sorts directory entries + (such as the ORCA/Shell compress command -- *don't* confuse + this with the GNO compress(1) command). + + If you do not have a utility that does this, you can do it + manually by moving all the files into another (scratch) + directory, then moving them back one at a time in the order + in which you wish them to appear. + + For HFS Partitions: + The files in a given directory on HFS partitions are always + sorted by name, case insensitive. You can change the sequence + in the directory only be changing the names of the files + involved. + + Specific to GNO installations, if your /lib directory resides + on an HFS volume, you should rename /lib/libc to /lib/nlibc. + +Q#607: How can I tell what is in library XXXX? + +A#607: The only way to tell for sure what is in a library is to + look at the symbol table. The most common way to do this + is to get a listing by using Byte Works' makelib(1) utility, + which comes with their various language packages (see the -D + and -F flags). + + There is also a program available, listlib(1), which is a + front end to makelib. It provides the same information as + makelib, but in an alternate format more suited to cross + referencing symbols to the files containing them. + + Of course, knowing what symbols are _in_ a library doesn't help + unless one knows _what_ the symbols are for. Every library should + have at least one header (*.h) file. This tells the compiler + the type, size, and other important information for each symbol. + + Header files, however, are intended for the compiler. A good + library should come with documentation, preferably manual pages + (see Q#206, Q#204, and Q#207). + + If documentation isn't available and the symbols appear to be + common UNIX symbols, then try reading a manual page from any + available UNIX box. It might not be right, but it may give you + a start. Next try posting a question to comp.sys.apple2.gno. + Perhaps you will be able to contact the author (not likely if there + wasn't any documentation). When all else fails, there's always + disassembly of the object files ... + +Q#605: Why isn't the common function XXXX in the libraries? + +A#605: The GNO libraries are still undergoing active development. If you + find that a standard or common routine is missing, then contact + Devin Reade who is currently the primary + maintainer of the GNO libc. + + If the function is not yet in libc you are requested to contribute + an implementation and a man page, preferably in nroff(1) source + (see Q#204). Distributing the work results in faster updates. + +Q#608: Function XXXX is declared in the GNO header files, but it's not in + the libraries. Why? + +A#608: Just because a function is declared, that doesn't necessarily mean + that it's been implemented. However, it is useful to keep those + declarations in the system header files. Not only does it minimize + namespace conflicts with user code (application programmers are + less likely to use function names that conflict with system header + files), but it ensures that the interface is defined for anyone + who wishes to contribute an implementation. Declaring those + functions early also minimizes updates to the system header files + as the function implementations are added. + + See also Q#605. + +Q#606: I want to release my library to the GNO community. Is there anything + in particular that I should do? + +A#606: Here's a checklist: + + - Any symbols which should not be available to the user should + have their private flag set. In C, this corresponds to using + the "static" storage class specifier whenever possible. + + - Ensure your library is compatible with ORCA/C's large memory + model. + + - Write documentation, preferably one or more manual pages, for + any exported symbols. If your library uses configuration files, + write manual pages for those too (they belong in chapter 5). + + - Specify in the manual pages any dependency on non-standard + libraries. Specify dependencies for all header files, whether + standard or not. + + - Consider including your source code with your library. This + allows your contribution to survive even if your hard drive + crashes, your backups are destroyed, or you leave the GNO + community. + +Q#609: How do I get the file descriptor from a stdio FILE pointer? + +A#609: Use the fileno() macro. + + This is defined in as of GNO v2.0.6. For earlier + versions you will have to add it in yourself. The proper + macro definition for the ORCA/C headers is: + + #define fileno(p) ((p)->_file) + +Q#610: My (ported) source requires . Why isn't it there? + +A#610: has been superceded by . Update your + sources. + +Q#611: Why, when I '#include ' (or some other file), does the + compiler take it out of my current directory instead of out of + the system header directories? + +A#611: This is an unfortunate side-effect of using the ORCA/C "path" + pragma to avoid duplication of system header files between your + GNO and ORCA installations. (See Q#1401, Q#1301, Q#1304, and + Q#1305.) + + The reason for the problem is that when the file is included + with the angle bracket syntax (vice double quotes), ORCA/C + will still search the current directory before those specified + by the "path" pragma. + + At this time, the only known work-around is to avoid, in your + own sources, using file names used by the system header files. + +Q#612: When using the December 1997 libraries (or later version), why are + my programs larger than they used to be? + +A#612: There are a few reasons for this. + + The first one is that when the libraries (which are mostly written + in C) are compiled, aggressive optimizations are not currently used. + This is because certain optimizations in ORCA/C are known to be + broken. This, combined with the fact that we are missing a lot + of automated test suites for the GNO (non-ORCA/C) additions to the + libraries, indicated that it would be best to ship the libraries + without much in the way of optimizations. + + The second reason is probably more significant. When Jawaid provided + a libc and ORCALib for GNO v2.0.4, he made significant changes to + the stdio portion of ORCALib so that it would work with pipes and + sockets. Unfortunately, for whatever reason, the two versions of + ORCALib (the original version from Byte Works, and the modified + version from Procyon) were never merged. Therefore, when ORCALib + was updated for ORCA/C v2.1.x, the GNO-specific changes were + effectively lost. + + When Devin took over maintenance of the GNO libraries in the spring + of 1997, he was (in order to get a stdio package that worked with + pipes) faced with the choice of either reimplementing Jawaid's + changes to stdio, or to use another implementation of stdio that + was written with pipes in mind. + + The tradeoff is one of development time versus code size (and probably + speed). The ORCA stdio implementation is in assembly, so it is + small and fast. On the other hand, GNO v2.0.6 had been in the + "it's not ready yet" stage for quite a while. The choice was made + to use the 4.4BSD stdio implementation. This is the primary reason + why programs which use stdio are now larger than they were. + + If your program does not use stdio, but is still significantly + larger, then it may be due to dependancies in libc; there are + some routines which currently depend on stdio but which need not. + These dependancies will be removed as time is available to do so. + +%Section% Kernel Internals: +========================== + +Q#1101: Can task-switching occur during an interrupt? + +A#1101: No. + +Q#1102: Can I tell GNO/ME to not task switch during a short (like a couple + of ASM instructions) sequence? + +A#1102: Turn off interrupts, or increment the busy flag around the code. + +%Section% Debugging (During Program Development): +================================================= + +Q#1201: What debuggers are available for GNO? + +A#1201: There are no GNO-specific debuggers, however there are at least two + popular ones that are compatible with GNO. + + If you are programming in C, it is highly recommended that you + purchase "Splat!", written by Michael Hackett of Some Assembly + Required. This is also available from Procyon. See also Q#1202. + + If you are programming in assembly, it is recommended that you + install GSBug. This comes bundled with ORCA/M and is also available + for download from the Apple Inc dts ftp site. GSBug has many + add-on packages used to increase its functionality. Two of these + are Niftylist and Nexus. + +Q#1202: Why is the Splat! debugger crashing when my code calls fork(2)? + +A#1202: Splat was not originally designed for GNO. When GNO does a fork(2) + or fork2(2) call, some very non-standard things are happening in + the IIgs execution environment. Splat cannot currently handle + these operations. + + A request has been submitted to the author of Splat! for an upgrade + to handle this behavior but he has not yet had time to do it; he + is also busy working on other IIgs projects. + +Q#1203: Part way through my debugging session, Splat! no longer shows my + source file. Why? + +A#1203: Your program is probably changing its current working directory. + + The C preprocessor inserts tokens that tell the compiler which + file (and on which line) it is currently processing. This + information is eventually passed to the debugger. Some of the + pathnames are, in general, relative to the directory from which + your program was compiled. + + Splat! uses these relative pathnames to locate the source files + that it is supposed to display. Unfortunately, the current version + of Splat! always searches for these files relative to the current + directory, not relative to the directory that was current at the + time which Splat! was invoked. Therefore, if your program changes + the current directory, the source files can no longer be found. + + This problem can be avoided by inserting following preprocessor + directive at the top of all your source files: + #line 1 "/fully/qualified/path/name.c" + Of course, you should use the real path names to your source files, + not the one shown above. Do not use the __FILE__ macro as it + will be expanded to only a partial pathname under some circumstances, + such as when using occ(1). + + There is a utility which automates this process, including an + option to remove the preprocessor directive. See the splatprep(1) + manual page for details. + +%Section% General Problems: +========================== + +Q#701: Some programs I run have two cursors and sometimes characters I + type don't get sent to the program. When I quit the program, the + characters show up on the command line! What's wrong? + +A#701: You need to set the auxiliary file type of the program in question + to $DC00. Use the chtyp command: + + chtyp -a \$DC00 ProgramName + + Note the '\' character; it must be there to escape the '$' character + from the shell, otherwise the $DC00 would be treated as a shell + variable. + + Also note that this fix will not work if the program's file type + is S16 and the file resides on an HFS volume. (An EXE file on + an HFS volume should be fine.) + +Q#702: Whenever I try to launch the Finder from GNO, I am told that the + Finder needs more memory. I know there is enough memory available. + What's the deal? + +A#702: This was a bug in the GNO 1.0 kernel. Unfortunately, there is no + workaround. The only option is to upgrade to a current version + of GNO. + +Q#703: My program is crashing when calling open(2). Why? + +A#703: It may be due to a prototype/library mismatch. The GNO implementation + of open(2) is a variadic function. The third "mode" parameter must + be provided if and only if the second "oflag" parameter has the + O_CREAT flag set. + + If calls to open result in a crash or stack error, you may have + either the wrong definition of open in , or you are not + getting open from 13/libc. See also Q#902, Q#602, Q#604, and Q#1306. + +Q#704: What are the known bugs? + +A#704: First off, this answer only refers to GNO-specific bugs. You + should also consult the ORCA/C bug list (see Q#902). + + As of mid-March 1998, there is an online bug tracking system + for GNO. You can get to it off of the GNO Documentation Page. + Its direct URL is: + + http://www.gno.org/~gno/bugs.html + + If you know of specific problems with GNO that are not listed + in the database, please enter them. The web interface is the + preferred method of submitting reports, but if that is not + feasible you can also send bug reports to the following address: + + gno-bugs@trenco.gno.org + + If you do not have a web browser, you can view current reports + by obtaining them through anonymous ftp at the following URL: + + ftp://ftp.gno.org/pub/gno-bugs + + You shouldn't archive these reports since they are continually + being updated; view them and throw them away. + + *** The anon ftp directory has not yet been set up. diff --git a/faq/GNUmakefile b/faq/GNUmakefile new file mode 100644 index 0000000..0f4ed8b --- /dev/null +++ b/faq/GNUmakefile @@ -0,0 +1,24 @@ +# +# Frequently Asked Questions +# + +SRCROOT = .. +WEB_HOME_BASE = faq +SUBPROJECTS = + +GEN_TEXT = $(WEB_HOME)/csa2g.FAQ.txt +GEN_HTML = $(WEB_HOME)/csa2g.FAQ.html + +TARGETS = $(GEN_TEXT) $(GEN_HTML) + +MKFAQ = ./mkfaq +FAQ_SRC = FAQ.gno.src + +include $(SRCROOT)/etc/const-priv.mk +include $(SRCROOT)/etc/const.mk +-include $(SRCROOT)/etc/const-local.mk + +include $(SRCROOT)/etc/rules.mk + +$(GEN_TEXT) $(GEN_HTML): $(FAQ_SRC) $(MKFAQ) + $(MKFAQ) diff --git a/faq/historical/Makefile b/faq/historical/Makefile new file mode 100644 index 0000000..c2392cd --- /dev/null +++ b/faq/historical/Makefile @@ -0,0 +1,129 @@ +# Devin Reade, November 1997 +# +# $Id: Makefile,v 1.4 1998/01/22 14:50:24 gdr Exp $ +# +# Main targets: +# +# release: +# Use this only when the FAQ is ready for news posting, and +# after doing a 'cvs commit'. +# test: (DEFAULT TARGET) +# Use this to generate local copies of the text and html versions +# of the FAQ. +# test-auto: +# This generates a file, "faq.out" that contains what *would* be +# posted with the 'post' target, but doesn't actually post anything. +# Before this target will build, you must have the file "gnoFAQ.1". +# You must manually copy "csa2g.FAQ.txt" to "gnoFAQ.1". This is +# so that a draft version of the FAQ is not accidentally posted +# by a cron job. +# +# test-post: +# This target will post a version of the FAQ to the configured +# test newsgroup. (Currently, ab.test.) +# clean: +# Deletes all scratch files except the released.* files (from the +# previous posting). +# clobber: +# Deletes *all* scratch files. +# + +SRC = FAQ.gno.src +CONFIG = faq-config + +AUTOFAQ = ./auto-faq/auto-faq +MKFAQ = mkfaq + +GEN_HTML = csa2g.FAQ.html +GEN_TEXT = csa2g.FAQ.txt +LOG_HTML = csa2g.LOG.html +LOG_TEXT = csa2g.LOG.txt +LOG_PENDING = unposted.log + +GEN_POST= faq.out + +# if you split the archive, change the 'release' target, below +AUTOSRC = gnoFAQ.1 + +# This is the name of the file that contains the approval header. +APPROVAL = /home/gdr/etc/GNO-FAQ.approval + +# This extracts the date and version from RCS identifiers. +GETDATE = /home/gdr/src/gno/doc/refs/getdate + +default: test + +test: $(GEN_TEXT) $(GEN_HTML) log +test-auto: $(GEN_POST) +log: $(LOG_TEXT) $(LOG_HTML) +$(GEN_TEXT) $(GEN_HTML): $(SRC) $(MKFAQ); $(MKFAQ) + +$(LOG_TEXT): $(SRC) + @echo "making $@"; \ + cat log.preamble > $@; \ + echo " extracting log information"; \ + cvs log $(SRC) | perl -n \ + -e '(/------/) && ($$found++);' \ + -e '($$found == 1) && print;' >> $@; \ + if [ -f $(LOG_PENDING) ]; then \ + echo " reusing $(LOG_PENDING)"; \ + cat $(LOG_PENDING) >> $@; \ + fi; + +$(LOG_HTML): $(LOG_TEXT) + @echo "making $@"; \ + echo 'GNO FAQ Update Log' > $@; \ + echo '' >> $@; \ + echo '

GNO FAQ Update Log

' >> $@; \
+	perl -p \
+		-e 's//>/g;' -e 's/"/"/g;' \
+		< $< >> $@; \
+	echo '
' >> $@ + +$(GEN_POST): $(AUTOSRC) + FAQ_NOSEND=1; export FAQ_NOSEND; \ + $(AUTOFAQ) GNO-faq + +release: $(GEN_TEXT) $(GEN_HTML) $(LOG_TEXT) $(LOG_HTML) + @echo "creating release files"; \ + v=`$(GETDATE) -version < $(SRC)`; \ + r=released; \ + rm -rf $$r; \ + mkdir $$r; \ + cp $(GEN_TEXT) $(AUTOSRC); \ + cp $(GEN_TEXT) $$r/faq.v$$v.txt; \ + cp $(GEN_HTML) $$r/faq.v$$v.html; \ + cp $(LOG_TEXT) $$r/log.v$$v.txt; \ + cp $(LOG_HTML) $$r/log.v$$v.html; \ + (cd $$r; tar -cf - .) | gzip --best > released.tar.gz + +# tar -cf - released*.txt released*.html| gzip --best > released.tar.gz + +test-post: $(AUTOSRC) + @g=`fgrep testgroup faq-config | \ + sed -e 's/^[^"][^"]*"//;' -e 's/".*//;'`; \ + echo "posting to test group ($$g)"; \ + if [ ! -f $(APPROVAL) ]; then \ + echo "$(APPROVAL) not found."; \ + echo "======== Are you supposed to be posting this FAQ?"; \ + exit 1; \ + fi; \ + FAQ_TEST=1; export FAQ_TEST; \ + $(AUTOFAQ) GNO-faq + + +post: $(AUTOSRC) + @echo "posting to csa2g"; \ + if [ ! -f $(APPROVAL) ]; then \ + echo "$(APPROVAL) not found."; \ + echo "======== Are you supposed to be posting this FAQ?"; \ + exit 1; \ + fi; \ + $(AUTOFAQ) GNO-faq + +clean: + rm -f $(GEN_HTML) $(GEN_TEXT) $(GEN_POST) *~ gnoFAQ.? \ + $(LOG_HTML) $(LOG_TEXT) + +clobber: clean + rm -rf released.* released diff --git a/faq/historical/README b/faq/historical/README new file mode 100644 index 0000000..822c711 --- /dev/null +++ b/faq/historical/README @@ -0,0 +1,10 @@ +The files in this directory were used when the comp.sys.apple2.gno +USENET news group was active. That newsgroup has since been retired, +so these are no longer necessary. + +In addition to these files, a program called auto-faq was used +for automated postings. As of September 2012, auto-faq is available +at + +Devin Reade +07 Sep 2012 diff --git a/faq/historical/faq-config b/faq/historical/faq-config new file mode 100644 index 0000000..f3b78ef --- /dev/null +++ b/faq/historical/faq-config @@ -0,0 +1,46 @@ +#!/bin/false +# +# Configuration for auto-faq +# +# Current newsgroups covered by this file: +# rec.radio.amateur.misc (cross-posted to news.answers) +# rec.radio.cb (cross-posted to news.answers) +# + +# global parameters +articledir="/home/gdr/src/doc/FAQs" # default directory for FAQ +chgctrl-type="rcs" # using RCS for revision control +newstech="gdr" # technical lead for FAQ postings +from="newstech" # From: field default is news-tech user +techname="Devin Reade" # full name of technical lead +testgroup="edm.test" # newsgroup for tests +testdistrib="ab" # distribution for tests +organization="Myrias Computer Technologies Corp" +localdomain="eddore.myrias.com" # local internet domain name +timezone="MST7MDT" # local timezone + +local-func-src="/home/gdr/src/doc/FAQs/faq.funcs" # customization routines + +=== GNO-faq +articlebase="gnoFAQ" # basename for FAQ +statusbase="gnoFAQ.status" # sequence file for Supersedes: headers +owner="gdr@eddore.myrias.com" # owner of FAQ text file +ownername="Devin Reade" # full name of owner +newsgroup="comp.sys.apple2.gno" # primary newsgroup for FAQ postings +extragroups="comp.answers,news.answers" + # secondary newsgroup(s) for cross-posting + # extragroups may be left empty +test-2nd-hdrs="Archive-Name:Revision:Changes:Last-modified:Version:URL" +post-2nd-hdrs="Archive-Name:Revision:Changes:Last-modified:Version:URL" +faqid="apple2-gno-faq" # identifier for message ID & archive name +archive="apple2/GNO-faq" # override archive name +distribution="world" # normal FAQ posting distribution +approval="@local_approval(A)@" # news.answers approval (optional) +interval="35" # how many days before the message expires +Keywords: FAQ, GNO, Apple-II, UNIX, ORCA +Summary: Contains information on the UNIX-like OS for the Apple IIgs. +Posting-Frequency:: monthly +X-Content-Currency: This FAQ changes regularly. When a saved or printed copy\ + is over 6 months old, please obtain a new one. Instructions in the\ + preamble indicate where to find them via NetNews, FTP, and the WWW. + diff --git a/faq/historical/faq.funcs b/faq/historical/faq.funcs new file mode 100755 index 0000000..d9906ae --- /dev/null +++ b/faq/historical/faq.funcs @@ -0,0 +1,60 @@ +push(@local_yearmap, "Jan", "Feb", "Mar", "Apr", "May", "Jun", + "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"); + +$local_version = ''; +$local_date = ''; +$local_http = ''; + +$local_approval_header_file = '/home/gdr/etc/GNO-FAQ.approval'; + +sub local_approval { + open(local_fp, "< $local_approval_header_file") || + die("couldn't open $local_approval_header_file. Are you supposed " . + "to be trying to post this FAQ?"); + $approval_line = ; + chop($approval_line); + close(local_fp); + return $approval_line; +} + +sub local_hdr_parse_rcs { + local($src, $year, $day, $time, $month); + +# $src = "\@articledir\@/FAQ.gno.src"; + $src = "/home/gdr/src/doc/FAQs/FAQ.gno.src"; + open (local_fp, "$src") || die("couldn't open $src"); + while ($_ = ) { + if (m,\$Id:\s+\S+\s+(\S+)\s+(\d+)/(\d+)/(\d+)\s+(\S+)\s*,) { + $local_version = $1; + $year = $2; + $day = $4; + $time = $5; + $month = $local_yearmap[int($3)-1]; + $local_date = "$day $month $year $time"; + } elsif (/%FAQ-http-addr%([^%]+)%/) { + $local_http = $1; + } + } + close(local_fp); +} + +sub local_hdr_version { + ($local_version eq '') && &local_hdr_parse_rcs(); + &pr_header("Version", "$local_version"); +} + +sub local_hdr_subject { + ($local_version eq '') && &local_hdr_parse_rcs(); + &pr_header("Subject", "comp.sys.apple2.gno FAQ (v$local_version)"); +} + +sub local_hdr_last_modified { + ($local_date eq '') && &local_hdr_parse_rcs(); + &pr_header("Last-modified", "$local_date"); +} + +sub local_hdr_url { + &pr_header("URL", "$local_http"); +} + +1; diff --git a/faq/historical/log.preamble b/faq/historical/log.preamble new file mode 100644 index 0000000..b5e89a1 --- /dev/null +++ b/faq/historical/log.preamble @@ -0,0 +1,7 @@ +The following are the recent changes to the FAQ. If more than one +change set appears, then there have been multiple updates since the +last time this FAQ was posted to comp.sys.apple2.gno and *.answers. + +At least one change set will always be shown, even if there have +been no changes since the previous posting. + diff --git a/faq/mkfaq b/faq/mkfaq new file mode 100755 index 0000000..8848bbe --- /dev/null +++ b/faq/mkfaq @@ -0,0 +1,391 @@ +#! /usr/bin/perl + +# +# This script is used for formatting the GNO FAQ. +# +# $Id: mkfaq,v 1.10 1998/01/22 14:53:10 gdr Exp $ +# + +$src = "FAQ.gno.src"; # the name of the FAQ source file +$dest = "csa2g.FAQ.txt"; # the name of the text output file +$html = "csa2g.FAQ.html"; # the name of the html output file + +$ContactName = "Devin Reade"; +$ContactEmail = "gdr\@eddore.myrias.com"; + +$totalSections = 0; # the number of sections in the FAQ +$totalQuestions = 0; +$currentQuestion = 0; +$tocLines = 0; # number of lines in table of contents +$lastmapping = 0; # used in &map() + +$SectionNumber = 0; # number of the current section +$MaxSections = 0; # total number of sections + +# +# open the output files +# +open (outfp, "> $dest") || die("couldn't open output file $dest"); +open (outfp2, "> $html") || die("couldn't open output file $html"); + +$faq = "GNO Frequently Asked Questions (FAQ) List"; + +printf(outfp2 + "\n" . + "\n" . + "" . $faq . "\n" . + "\n" . + "\n" . + "

" . $faq . "

\n"); +# +# First pass -- get the table of contents and figure out what the +# question number mappings are. +# +open (fp, $src) || die("couldn't open $src (1)"); +$_ = ; +do { + chop; + if ( /^%Section%\s*(.+):/ ) { + &addSection($1); + &addSectionHTML($1); + } elsif ( /^Q\#(\d+):\s+(.*)/ ) { + $originalLine = int($1); + $newLine = &map($originalLine); + $question = $2; + while () { + (/^\s*$/) && last; + $question .= $_; + } + if (defined($orgLineList[$originalLine])) { + printf(stderr "%s:%d: duplicate question number Q\#%d\n", + $src, $. -1, $originalLine); + } else { + $orgLineList[$originalLine] = 1; + } + &addTOCEntryHTML ($newLine, $question); + $junk = sprintf("Q\#%s", $newLine); + if (length($junk) < 7) { + $padding = "\t"; + } else { + $padding = " "; + } + $question = sprintf("\t%s:%s%s\n", $junk, $padding, &fmt(2,$question)); + &addTOCEntry ($question); + } elsif ( /^%RCS-ID%\S+\s+\S+\s+(\S+)\s+(\S+)\s(\S+)/ ) { + $version = $1; + $date = $2; + $time = $3; + } +} while (); +close(fp); + +# +# Second pass -- print out the results, doing mappings as necessary +# + +$SectionNumber = 0; +open (fp, $src) || die("couldn't open $src (2)"); +$in_header = 0; +$in_body = 0; +while() { + if (/^%Header-start%\s*$/) { + $in_header = 1; + printf(outfp2 + "Version: %s
\n" . + "Last Modified: %s %s
\n" . + "
\n" . + "

Preamble

\n" . + "
\n", $version, $date, $time);
+    } elsif (/^%Header-end%\s*$/) {
+	$in_header = 0;
+	printf(outfp2 "
\n
\n"); + } elsif (/^%FAQ-http-addr%(.*)%$/) { + $faq_http = $1; + } elsif (/^%FAQ-ftp-addr%(.*)%$/) { + $faq_ftp = $1; + } elsif (/^%FAQ-log-http-addr%(.*)%$/) { + $faqlog_http = $1; + } elsif (/^%FAQ-log-ftp-addr%(.*)%$/) { + $faqlog_ftp = $1; +# } elsif (/%Version%\s*$/) { +# printf(outfp "Version:\t%s\n", $version); +# } elsif (/%Last-Modified%\s*$/) { +# printf(outfp "Modified:\t%s %s\n\n", $date, $time); + } elsif (/^%TOC%\s*$/) { + &printTOC(); + } elsif (/^%Section%\s*(.+):\s*$/) { + # found a section header + $SectionNumber++; + &PrintSection($1); + $_ = ; # ditch the old underlining + $in_body = 1; + } elsif ($in_header || $in_body) { + s,\%Version\%,$version,; + s,\%Last\-Modified\%,$date $time,; + s,\%FAQ-FTP\%,$faq_ftp,; + s,\%FAQ-HTTP\%,$faq_http,; + s,\%LOG-FTP\%,$faqlog_ftp,; + s,\%LOG-HTTP\%,$faqlog_http,; + &PrintLine($_); + } +} + +# print trailing info +printf(outfp2 + "
\n" . + "%s\n" . + "<%s>\n" . + "\n" . + "\n", $ContactName, $ContactEmail, $ContactEmail); + +# clean up +close(fp); +close(outfp); +close(outfp2); + +# +# Subroutines +# + +sub map { + local ($old); + $old = @_[0]; + + if ($mappings[$old] == 0) { + $lastmapping++; + $mappings[$old] = sprintf("%d.%d", $SectionNumber, $lastmapping); + } + return $mappings[$old]; +} + +sub addTOCEntry { + local($line, $first, $num, $num2, $last); + + $line = $_[0]; + $toc[$tocLines++] = $line; + $tocLines++; +} + +sub addTOCEntryHTML { + local($line, $num, $entry); + local($first, $num2, $last); + + $num = $_[0]; + $line = $_[1]; + $line = &text2html($line); + $line =~ s/[\s\n]+/ /g; + $tag = $num; + $tag =~ s/\./_/g; + $entry = sprintf("
  • Q%s: %s\n", $tag, $num, $line); + $htmlQuestion{$num} = "$line"; + push(@htmlTOC, "$entry"); + return 0; +} + +sub addSection { + local ($underline, $len, $i); + + &addTOCEntry ("\n\t" . @_[0] . "\n"); + $underline = "\t"; + $len = length(@_[0]); + for ($i = 0; $i < $len; $i++) { + $underline .= '^'; + } + $underline .= "\n"; + $lastmapping = 0; # reset the question numbers for new section + &addTOCEntry ($underline); +} + +sub addSectionHTML { + local ($entry, $arg, $tail); + + $arg = $_[0]; + $arg = &text2html($arg); + $MaxSections++; + $SectionNumber++; + $SectionNames[$SectionNumber] = $arg; + + $tail = ''; + ($SectionNumber > 1) && ($tail = ""); + $entry = sprintf("%s\n" . + "

    Section %d: %s

    \n" . + "
      \n", $tail, $SectionNumber, $SectionNumber, $arg); + push(@htmlTOC, "$entry"); +} + + +sub printTOC { + local ($i, $l); + + # print out the text TOC + printf (outfp + "Table of Contents\n" . + "=================\n"); + for ($i=0; $i < $tocLines; $i++) { + printf (outfp "%s", $toc[$i]); + } + printf(outfp "\n"); + + # print the html TOC + printf (outfp2 "

      Table of Contents

      \n"); + print outfp2 @htmlTOC; + printf (outfp2 "

    \n\n"); # finish off the last list +} + +# +# Print the section name. For the text version, underline the name. +# Takes one argument, the section name. +# +sub PrintSection { + local($sname, $len, $i); + + $sname = @_[0]; + + # Do the text version + printf(outfp "%s\n", $sname); + $len = length($sname); + for ($i=0; $i<$len; $i++) { + printf (outfp "-"); + } + printf(outfp "\n"); + + # Do the html version + $sname = &text2html($sname); + ($SectionNumber > 1) && printf(outfp2 "\n"); + printf(outfp2 + "\n
    \n\n" . + "

    Section %d: %s

    \n\n", + $SectionNumber, $SectionNumber, $sname); +} + +# +# Print a line that's in the header or body. Takes one argument, the +# raw line. +# +sub PrintLine { + local($line, $rest); + + $line = @_[0]; + + # do a concheck and print out the text version + $qora = ''; + if ($line =~ /^([QA])\#\d+:(.*)/) { + $qora = $1; + $rest = $2; + ($rest =~ /^\t/) || + printf(stderr "%s:%d: missing leading tab\n", $src, $. -1); + } + $line =~ s/([QA])\#(\d+)/"$1#".&map($2)/ge; + printf (outfp "%s", $line); + if ($qora eq 'Q') { + do { + $line = ; + $line =~ s/([QA])\#(\d+)/"$1#".&map($2)/ge; + printf (outfp "%s", $line); + } until ($line =~ /^\s*$/); + } + + # do the html version + $line = &text2html(@_[0]); + if ($line =~ /^([QA])\#(\d+):(.*)/) { + # start of a question or answer + $qora = $1; + $num = $2; + $rest = $3; + if ($qora eq 'Q') { + printf(outfp2 + "

    Q\#%s: %s

    \n
    \n", 
+		   &mapnum(&map($num)), &map($num), $htmlQuestion{&map($num)})
+	} else {
+	    $rest =~ s,Q\#(\d+),
+	    'Q#'.&map($1).'',ge;
+	    $rest =~ s/^\t//;
+	    printf(outfp2 "%s\n", $rest);
+	}
+    } else {
+	$line =~ s,Q\#(\d+),'Q#'.&map($1).
+	    '',ge;
+	$line =~ s/^\t//;
+
+	# replace http:// and ftp:// with the link equivalents
+	$line =~ s,(http|ftp)://(\S+),''.$1.'://'.$2.'',ge;
+
+#	$line =~ s,ftp://(\S+),'http://'.$1.'',ge;
+	printf (outfp2 "%s", $line);
+    }
+
+}
+
+sub mapnum {
+    local($num);
+
+    $num = @_[0];
+    $num =~ s/\./_/g;
+    return $num
+}
+
+#
+# &fmt (tabs, text)
+#
+# This routine formats the specified text to fall within 76 columns,
+# and indents the text with the specified number of tabs (considered
+# to be 8 characters wide).
+#
+# The first line will _not_ be preceeded by any tabs, even though
+# the length will be calculated as if it is.
+#
+sub fmt {
+    local (@array, $tabs, $line, $columns, $result, $tablen, $linelen);
+    local ($word, $len, $i);
+    $tabs = int(@_[0]);
+    $line = @_[1];
+    $columns = 76;		# maximum column number to print
+    $tablen  = 8;		# spaces per tab
+
+    $line =~ s/\s+/ /g;
+
+    @array = split ("[ \t]+", $line);
+    $result = '';
+    $linelen = 0;
+    for ($i = 0; $i < $tabs; $i++) {
+	$linelen += $tablen;
+    }
+    foreach $word (@array) {
+	$len = length($word);
+	if ($columns - $linelen > $len) {
+	    # add it into the current line
+	    if ($linelen == $tablen * $tabs) {
+		$result .= $word;
+		$linelen += $len;
+	    } else {
+		$result .= ' ' . $word;
+		$linelen += $len + 1;
+	    }
+	} else {
+	    # start a new line
+	    $result .= "\n";
+	    $linelen = 0;
+	    for ($i = 0; $i < $tabs; $i++) {
+		$result .= "\t";
+		$linelen += $tablen;
+	    }
+	    $result .= $word;
+	    $linelen += $len;
+	}
+    }
+    return $result;
+}
+
+#
+# Translates HTML special character sequences into their "escaped" formats
+#
+sub text2html {
+    local($line);
+
+    $line = @_[0];
+
+    $line =~ s//>/g;
+    $line =~ s/"/"/g;
+    return $line;
+}