All submissions and questions should be directed to andrew-johnson@home.com

Articles should be written using the noweb literate programming syntax, a brief explanation of which can be found right here.

The easiest way to get a feel for things is to download a typeset version of the newsletter along with the literate sources for that issue.

Your article will be plain text with the appropriate markup syntax to begin and end code and documentation chunks (as specified in the above link). The article will be passed through noweave's LaTeX backend and then typeset using LaTeX. Documentation chunks are passed through as is, leaving you free to use LaTeX markup within your documentation.

If you know LaTeX, all I ask is that you do not use any extra macro packages in your article. If you need a certain capability not offered by vanilla LaTeX, discuss it with me and we can make sure we have compatible macro packages (and that they don't conflict with the noweb package's .sty).

If you don't know LaTeX don't worry, you don't need to. You can just write your documentation paragraphs in plain text and indicate any special formatting concerns in ALL CAPS in parentheses (so I can easily find them). Alternatively, you may use HTML tags to indicate formatting and I'll try to substitute the appropriate LaTeX markup (but I retain discretionary power to change things to conform to a consistent style among articles).

You may include graphics, either using LaTeX' picture environment, or as encapsulated postscript (.eps). In the latter case, you send the figure as a separate file and put the following (with appropriate changes) in your article document where you want the figure to appear:

\begin{figure}
\epsfbox{filename.eps}
\caption{Blah blah blah.}
\end{figure}

Here are a few basic guidelines for structuring your article:

• Please try to keep lines of source code to a maximum length of 54 characters (otherwise the two column format will be broken). In most cases, long lines can be reasonably broken across two lines without hurting readability (this is Perl remember).
• Try to keep code chunks to a reasonable length---if your code chunk is more than a handful of lines (say about 12 lines), please consider breaking it into two or more chunks. This helps with overall formatting and code chunks are presented in easy to swallow capsules.
• Try to begin with a reasonable top-level design in the root chunk. The root chunk (aside from some possible initialization code) should mostly read like a table of contents of the major components of the program. Lower level chunks may do the same if they are still too long or complex to present in a handful of lines.
• In code: Do not start and/or end blocks in different chunks! Think about it and it should be obvious why not---it breaks up the logical structure of the code. For example, this is a bad example:

  
  <<chunk>>=
  <<somechunk>>
  <<nutherchunk>>
  @
  
  <<somechunk>>=
  for my $blah (@blahs){
      blah blah;
      blah blah;
  @
  
  <<nutherchunk>>=
      blah blah;
      blah blah;
  }
  @
  
  

  Far better to use two chunks (if necessary) within a block:

  
  <<chunk>>=
  for my $blah (@blahs){
      <<somechunk>>
      <<nutherchunk>>
  }
  @
  
  <<somechunk>>=
  blah blah;
  blah blah;
  @
  
  <<nutherchunk>>=
  blah blah;
  blah blah;
  @
  
  

• Don't be afraid to talk (or write as it were). Obviously we don't need a paragraph of text that merely gives an English version of the code chunk that follows, but we do need explanations of algorithms, why you made certain design decisions, why such and such is a workaround or dirty hack (I'd really like to do X here, but we can't do that directly here so I'm using Y and Z to achieve X...).