Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Posting-Version: version B 2.10.2 9/18/84; site Glacier.ARPA
Path: utzoo!watmath!clyde!burl!ulysses!mhuxr!mhuxn!ihnp4!nsc!Glacier!reid
From: reid@Glacier.ARPA (Brian Reid)
Newsgroups: net.cooks
Subject: How to make the net cookbook
Message-ID: <13185@Glacier.ARPA>
Date: Tue, 15-Oct-85 14:33:42 EDT
Article-I.D.: Glacier.13185
Posted: Tue Oct 15 14:33:42 1985
Date-Received: Thu, 17-Oct-85 02:17:50 EDT
Reply-To: reid@Glacier.UUCP (Brian Reid)
Organization: Stanford University, Computer Systems Lab
Lines: 71
Summary: let's make this a showpiece of technology, too!


The net cookbook is a great idea. Here is how I propose to do it:

  (1) Cause net.cooks.cookbook to be created. You'll shortly see why
      it is needed. I will start the crank turning in net.news.group
      after I see what people think of this idea.

  (2) Have some troff expert prepare a "skeleton" troff file that will
      work with both troff and nroff. This troff file will be the
      prototype for recipes; it will have an ingredient list, some
      numbered paragraphs of text, and examples of simple troff hackery.
      (I prefer to use a formatter that I think is much better than troff,
      but it would be foolish to use anything except troff/nroff on a Unix
      network cookbook). Oh, yes, the troff skeleton should also include
      an example of how to format one's signature file or attribution,
      and people should be encouraged to put this at the end of each
      recipe. [Note to the experts: it has been my experience that the 
      only troff/nroff macros that truly work everywhere are the -man
      macros, so let's try to base this on -man rather than -mm or -me
      or -ms or something else. Besides: that will enable sites whose
      administrators have a sense of humor to permit "man cheesecake"]

  (3) Post the skeleton troff file to net.cooks at regular intervals; perhaps
      every month or so (use the same Subject every time so that people can
      skip over it if they have it already).

  (4) Encourage people to start posting recipes to net.cooks.cookbook, using
      this troff/nroff skeleton file as an example. The "Subject" line of
      each recipe will be the title of the recipe.

  (5) [Here is my contribution]. I'm a pretty good awk/sed/shell hacker. I
      will write a shell script that, when run, goes out to the
      net.cooks.cookbook directory, takes all the articles that it finds
      there, strips the headers off them, and makes a single troff document
      out of them. With different options, it will make a refer(1) file,
      a troff file, or (by running itself through nroff) a text file. It
      will also make an index of authors, of titles, and ingredients.
      This will work if and only if people follow the rules and use the
      standardized troff skeleton to format their recipes.

As this gets cranking to steady-state, the net.cooks.cookbook directory will
contain about a month's worth of recipes (depending on how people run expire
at their sites). Some sites will choose to run archives, some will not.
Unless somebody gets to it before I do, I will also post some (extremely
simple) software that lets people make their own individual or site-specific
archive that is outside of the domain of netnews and therefore not subject
to being expired.

Once this gets going, I will propose a mechanism for reviewing recipes, so
that the reviews can be included with the recipes in the formatted version
of the cookbook. Naturally this will all be automatic. My current thinking
is that the right way to review a recipe is to post a note to net.cooks
(not net.cooks.cookbook) whose subject is "REVIEW: " followed by the title
of the recipe. Since these reviews sometimes get unnecessarily vitriolic
(e.g. the key lime pie reviews), the software that assembles a cookbook out
of the current state of the database should certainly have options enabling
it to be run with or without the reviews.

SO: let's have people who consider themselves troff/nroff experts post some
sample skeletons of sample formats. We can collectively discuss these
samples, evaluating them according to (a) whether they include the right
information (b) whether they include it in a way that will make automatic
parsing (for the index and table of contents) easy, (c) whether they look
good when formatted on a typesetter, (d) whether they look ok when formatted
online with nroff, etc. After seeing and trying a few of the formats, I
expect we will reach some kind of a consensus. We'll need to appoint one
person to make the final decision of which skeleton to use, and then after
that we won't need any kind of centralization or authority.
-- 
	Brian Reid	decwrl!glacier!reid
	Stanford	reid@SU-Glacier.ARPA