This file last updated: Fri Jan  7 07:14:02 PST 1994

           WIZARD'S GRABBAG SUBMISSION GUIDELINES

How Do I Get Published?

Sometimes readers ask, "What criteria do you use for selecting 
contributions for publication in `Wizard's Grabbag'?"  First and 
foremost, we publish items that will be of general interest to 
our readers.  We can't use items that work just on one computer 
system or narrow range of UNIX system implementations, such as 
AIX 3.1 only.  

We look for novel ideas and good implementations of them, 
especially ones we haven't already used.  Also, we may publish a 
contribution because of its educational value, even though the 
sample program is not that significant.  

Examine our annual indices published in the December issues to 
see if your topic has already been covered.  (If necessary, we'll 
be glad to send you on-line copies of indices for specified years 
if you need them).  Sometimes we may repeat a theme if the 
approach provides new functionality or is especially interesting.  

We also encourage your feedback for previously published 
contributions.  Bug reports, significant enhancements, even new 
contributions inspired by ones we've presented will be considered 
for timely publication in an upcoming issue.  

We don't have a lot of time to debug code to get it to work, so 
you should test it thoroughly on as many different UNIX 
implementations as you have access to.  For instance, System V 
and BSD (or SunOS) probably cover most systems currently in 
widespread usage.  Try to exercise the program strenuously, even 
under extreme conditions--for instance, anticipate all kinds of 
bizarre user input.  Be sure to check the so-called "boundary 
conditions," for instance, where input values change from 
positive to zero to negative.  

Yes, we have been somewhat biased toward System V in the past, but 
we're encouraging readers to submit BSD, SunOS, or XENIX 
contributions, too.  Ideally, your contribution should be 
portable to all major UNIX implementations; however, we understand 
that it's not always feasible to achieve in practice.  

Last, but not least, take the time to read the column.  Look at 
back issues and familiarize yourself with our style, scope, and 
audience level.  


Submitting the Contribution

Mail Bourne or Korn shell scripts, C or Perl programs, or tips to 
ease the burden of system administrators, programmers, and users 
to: "Wizard's Grabbag," Open Computing Magazine, 1900 O'Farrell 
Street, San Mateo, CA 94403.  Or submit via UUCP e-mail to: 

uunet!uworld!grabbag

or use the domain address:

grabbag@uworld.com

Please provide your full name, surface mailing address, and 
voice/fax phone numbers, and, if you use e-mail, your return 
mail-routing address (using either domain format or bang format 
relative from uunet) as well.  Please be sure to send me any 
change in your e-mail/surface mail/phone number so that we can 
contact you in the future.  (Several times we've wanted to use a 
contribution submitted over a year ago and have been unable to 
contact the contributor.)  

We prefer that you submit via e-mail, but hardcopy is acceptable 
for short items.  If you have a long contribution, we might 
request that you send me your program on a 1.2Mbyte 5 1/4-inch or 
3 1/2-inch 1.44Mbyte DOS-format floppy.  We should be able to read 
a "tar" archive.  However, don't send me the floppy until we 
request it.  Alternately, for U.S.  contributors, we could set up 
a temporary UUCP link for transferring your submission.  

General UNIX-related questions should be submitted to Ray Swartz, 
who writes the "Answers to UNIX" column.  Send them to 
uunet!uworld!ans2unix or ans2unix@uworld.com.  


Portability Considerations

Briefly describe the hardware and software environment, 
especially the UNIX system version(s), on which the contributed 
code was tested.  

When feasible, write code that is portable across the popular 
versions of the UNIX system (System V.X, BSD 4.X, SCO) and 
POSIX.1 compatible.  Bourne shell scripts are preferred (most 
portable), but Korn shell programs will be considered.  Use 
universally available utilities, for example, use **awk** or 
**sed** (available on all systems) instead of **cut** (System V).  
If feasible, use **getopts(1)** or **getopt(3C)** as appropriate 
to process command-line options and their arguments.  

We encourage readers to submit Perl programs.  Although, systems 
generally aren't shipped with Perl, this public-domain program 
has been ported to almost every UNIX implementation.  Unless you 
have a compelling reason, use default Perl values when ever 
possible to maintain default behavior and help shorten the 
program.  For instance, use $[ = 0 (default) instead of $[ = 1, 
for example, to have array subscripts begin with 0 (zero) instead 
of 1 (one, as they do with **awk**).  

Use the standard I/O library for structured modular C code.  
Check source code for non-portable constructions with **lint**.  
Eliminate hardware dependencies, such as terminal control 
sequences.  (Use **termcap** or **terminfo**.)  Isolate 
non-portable code to one region or a separate module.  


Code Format

Keep listings compact, under 100 lines of code is best, but we do 
publish longer programs if we feel they would be of significant 
interest to our readers.  We are limited to a maximum of 150 lines 
of listings per column, so, if your program is that long, we can 
only feature your contribution.  

Also each line of code must be less than 72 characters long 
(count each tab character used for indentation as four spaces).  
If lines must be over 72 characters then please make sure you 
"break" your code in an appropriate place across physical lines.  

While formatting your code please make sure you use indentation 
consistently.  The best approach for my purposes is to use tabs 
that are aligned every four spaces, achieved by using ts=4 (and 
sw=4 if you use ai) with the vi editor.  After my changes we'll 
convert all tabs in the file to four spaces to save line width.  
After such conversion the code needs to fit on a 72-character 
line.  

Occasionally a program may have so many levels of indentation 
that a shorter tab stop might be necessary.  In this case try 
three, and if that doesn't fit, use two.  

Don't use multiple-line comments in your program to explain your 
code because we explain the program operation in the accompanying 
text.  It's best to have a blank line, then perhaps a one-line 
comment, followed by the code section.  Of course, comments at 
the end of a line are fine as long as the line length isn't 
exceeded.  It's best that the start of comment character, such as 
# or /*, align with similar constructs on neighboring lines.  The 
"quicktime" Perl program, published in my December 1993 column, 
provides a good example.  

The overall length of your code can be reduced by using some of 
the techniques we've employed in past columns.  If it doesn't 
obscure the code then shell script constructs like: 

if [ ! -s $NAMF ]
then
	...
fi

can be reduced to:

if [ ! -s $NAMF ]; then
	...
fi

to save one line or even

[ ! -s $NAMF ] && ...

or 

[ -s $NAMF ] || ...

to save more.

We assume that the shell understands the "[" shorthand for the
test command.

If you have subsequent lines containing related code that is 
short you could join them using semicolon separators.  Here again 
you'll need to use judgement.  You don't want to obscure the 
code's functionality.  

A line here and a line there does add up to savings.  

We generally use K&R-style indentation format for C, awk, and 
Perl programs.  See __The C Programming Language__ by Brian 
Kernighan and Dennis Ritchie.  

It's helpful for testing purposes if you can submit an 
on-line copy of your program code without line numbers.  A 
shell archive (shar) or **tar**-format archive would be most 
convenient for supplying several programs or modules.  


Accompanying Text

You need to provide text to support your program contribution.  
First, you should provide some background for why you're 
submitting the program.  What does it do, what is it good for, 
not good for, etc., as appropriate.  

Generally, command-line examples should be placed in the 
listings.  However, short command lines (without sample output) 
can be incorporated into the text portion of your contribution, 
but lines longer than a column width (around 30 monospace-typeface 
characters) will be wrapped-around so they will look better if 
located with the listings.  

Since the magazine tries to appeal to all audience levels we like 
to publish some explanation for how the more obscure aspects of 
the code works for our less experienced readers.  If you don't 
write an explanation, we'll attempt it.  However, it would be 
useful if you could at least explain less obvious constructs.  If 
you describe the operation of the code on a line-by-line basis, 
be aware that the line numbering may change before publication as 
we generally edit the code.  It's still helpful to provide 
comments in the code.  Here again please consult recent columns 
for guidance.  


Legalese

If you submit a contribution to Wizard's Grabbag, we understand 
that you accept the following conditions: 

You grant McGraw-Hill, Inc.  the non-exclusive right to publish 
and distribute your contribution worldwide, in any medium and in 
all languages.  We reserve the right to edit your contribution 
for clarity, brevity, and to enhance portability, and publish it 
at any time.  If we publish your contribution, we will send you 
$50 within 60 days after publication.  We require social security 
numbers for U.S.  citizens.  

We will attempt to acknowledge receipt of contributions.  Because 
it's not always possible to reply to e-mail successfully, it's 
important that you include other ways to contact you.  We accept 
no responsibility for loss or damage to contributions.  Printed 
submissions should be copies.  

Your submission must not violate or infringe any copyright or 
other proprietary right of others, nor contain anything 
injurious.  

We make no guarantees as to the materials published in Wizard's 
Grabbag.  Any use of materials published in Wizard's Grabbag is at 
the sole risk of the user.  


Questions?

Please send me any specific questions you may have for items not 
covered by these guidelines or if you need further clarification 
on some points discussed herein.  These guidelines are 
continually evolving and your input is valuable for that 
evolvement.  

Thanks for your interest in "Wizard's Grabbag."

Rebecca "Becca" Thomas
Wizard's Grabbag editor
Open Computing Magazine
E-mail: uunet!uworld!grabbag
        grabbag@uworld.com

-30-