A Beginner's Guide to the Internet/INTERNET.ISO/text/faqs/faqspecs.faq

Internet Message Format | 1995-03-23 | 29.6 KB

From: [e-mail] (Jonathan I. Kamens)
Newsgroups: news.answers,alt.answers,comp.answers,misc.answers,rec.answers,sci.answers,soc.answers,talk.answers
Subject: *.answers submission guidelines
Date: 20 Oct 1993 01:00:11 -0400
Organization: OpenVision Technologies, Inc.
Reply-To: [e-mail]

Archive-name: news-answers/guidelines
Version: $Id: guidelines,v 1.68 1993/10/20 01:34:15 jik Exp $


In order to submit an FAQ posting to the news.answers newsgroup (and
to zero or more of the other *.answers newsgroups (alt.answers,
comp.answers, misc.answers, rec.answers, sci.answers, soc.answers,
talk.answers) along with it), you should first modify your posting to
conform to the guidelines given below, in section I.  Then, you should
submit your posting to me using the instructions given below, in
section II.

Once your posting is approved, you will post it directly to
news.answers and other newsgroups yourself; i.e., after approval, you
no longer have to go through me at all to post.  This is explained in
more detail below.


I. Submission guidelines

 A. Why the guidelines?

    There are three main reasons for the guidelines:

  1. Appropriateness

     Only periodic informational postings that are intended to be read
     by people belong in news.answers.  The guidelines are meant to
     prevent other types of postings, including discussion of periodic
     informational postings, from appearing in the group.

  2. Usefulness to people

     The newsgroup should be as useful as possible to the people who
     read it.  Requirements such as effective "Subject:" and
     "Summary:" lines (see below) further this goal.

  3. Automatic archiving

     One of the main points of news.answers is that it can be archived
     automatically in order to build up a database of periodic
     informational postings.  Requirements such as the "Archive-name:"
     line further that goal.

 B. Required header fields

    There are two "headers" in a news.answers posting.  The first is
    the normal header that any article posted to the USENET has.  The
    second header, the "auxiliary header," is separated from the first
    by one or more blank lines.  As far as the News software is
    concerned, the auxiliary header is just part of the body of the
    article; however, news.answers requires some information in it.

    The requirements for each of the two headers are discussed in
    detail below.  Required headers are marked with "(Required)",
    while optional ones are marked with "(Optional)".

  1. The normal header

   a. Newsgroups (Required)

      I need to know exactly what will appear in the Newsgroups line
      of the posting.

      In addition to news.answers, your posting should be cross-posted
      to the other *.answers newsgroups of hierarchies in which it is
      posted.  For example, a posting that is normally posted in both
      rec.music.makers.synth and comp.sys.ibm.pc.soundcard should be
      posted to both rec.answers and comp.answers in addition to
      news.answers.  Note that postings to any of the *.answers
      newsgroups MUST be posted in news.answers, regardless of what
      other *.answers newsgroups they also appear in.

      Although the order of newsgroups on the line is not important
      from the point of view of the news software, I prefer to have
      news.answers listed last, since it is the least "relevant" of
      the listed newsgroups.  The other *.answers newsgroups should be
      listed directly before news.answers.

      Example:

       Newsgroups: comp.sys.foo,comp.answers,news.answers

      Note that your Newsgroups line should NOT contain only *.answers
      groups.  FAQ postings should be cross-posted to *.answers from
      their home newsgroups, rather than being posted separately to
      *.answers.

      However, if you get approval for *.answers cross-posting in the
      middle of your "posting cycle," and you do not wish to wait
      until the next scheduled posting time to cross-post to
      *.answers, then you can post your FAQ only to *.answers.  If you
      choose to do this, please make sure to let me know you are going
      to, and please do not do it more than once.

   b. Subject (Required)

      The subject line of your posting should have some meaning
      outside of its home newsgroup(s).  For example, instead of just
      "FAQ," you might have "<x> FAQ", where "<x>" is the name of the
      newsgroup or the topic being discussed.

      Furthermore, important information should appear near the
      beginning of the subject line, so that news readers that display
      article summaries don't cut off the important information.  For
      example, instead of "Frequently Asked Questions about <x>," use
      "<x> Frequently asked Questions."

      Example:

       Subject: comp.sys.foo Frequently Asked Questions (FAQ)

   c. Followup-To (Required) and Reply-To (Optional)

      Your posting must have a "Followup-To:" line in the header that
      directs followups to somewhere other than *.answers.  You may
      choose to direct followups back to the home newsgroup(s) of the
      FAQ, or to direct followups to the author of the FAQ, in which
      case "Followup-To: poster" is sufficient.  That means that you
      actually put the word "poster" there, as specified in the RFC
      which describes the format of Usenet postings.  Do NOT put an
      E-mail address in the "Followup-To:" field.

      If you forget the "Followup-To:" and I get mailed followups to
      your FAQ, I'm going to get peeved at you.

      Furthermore, your posting must have a valid E-mail reply address
      in the header, either in the "From:" field, or if not in "From:"
      then in "Reply-To:".

      Example:

       From: [e-mail] (Joe R. Programmer)
       Followup-To: comp.sys.foo
       Reply-To: [e-mail] (FAQ Comments address)

      In this example, "guru" apparently wants mail about the FAQ to
      go to a different address than the rest of his mail.  I've shown
      the "From:" header, because the version of the FAQ that you
      forward to me should show the "From:" header just as it will
      appear when the article is actually posted.

   d. Supersedes, Expires, References (Optional)

      It is a good idea to use "Supersedes:" and "Expires:" header
      lines to make sure that each version of your FAQ stays around
      until the next time it is posted.  A useful tool for this is my
      Perl FAQ poster.  It is available from rtfm.mit.edu, via
      anonymous ftp in the file /pub/post_faq/post_faq.shar, or via
      mail server (send mail to [e-mail] with "send
      post_faq/post_faq.shar" in the body).

      Post_faq takes an article with its static headers (i.e., the
      headers that don't change each time the article is posted)
      included, adds dynamic headers to it, and posts the article.
      Another utility, Ian Kluft's AUTO-FAQ package (which is also
      written in Perl) provides more functionality, including
      automatic splitting of large FAQs into multi-part postings.  If
      you're looking for something with a high level of automation to
      assist you in your FAQ maintenance and posting, you might want
      to try AUTO-FAQ instead of post_faq.  It's available via
      anonymous ftp in ftp.amdahl.com:pub/faq/auto-faq.shar.Z.

      Furthermore, if you are posting a multi-part FAQ posting or a
      series of related FAQ postings, it is a good idea to add a
      "References:" line to all of the postings except the first one,
      making the contents of that line the Message-ID of the first
      posting in the series.  If you do this, then people who use
      threaded news readers will be able to manipulate the entire
      series as a single thread, including (for example) killing the
      entire thread if they're not interested or saving the entire
      thread to a file with one command.  The perl FAQ poster
      mentioned above supports an option for doing this.

      Example:

       Expires: Fri, 1 May 1992 00:00:00 GMT
       Supersedes: <[e-mail]>

      The date in the "Expires:" header should be far enough into the
      future that a new version of the FAQ will be posted before the
      one you're posting now expires.  I've shown both headers in the
      format my post_faq script would use.  I haven't shown a
      "References:" header, since the example posting I've been
      presenting is not part of a multi-part FAQ; if there were a
      "References:" header, it would contain a Message ID just like
      the "Supersedes:" header.

   e. Summary (Optional)

      You are encouraged to put a summary of the contents of your
      article in the Summary field of the header.  Try to describe
      what your FAQ discusses, and aim your description at someone who
      may not actually be directly interested in the topic covered by
      your FAQ.  There have been discussions about using the Summary
      fields of the FAQ postings in news.answers to construct a short
      "catalog" of the information available through news.answers, so
      think of the Summary field as a "catalog entry" for your FAQ.

      Note that header fields (except for the Newsgroups field) are
      allowed to span multiple lines, as long as the continuation
      lines after the first start with whitespace (at least one space
      or tab character).

      Example:

       Summary: This posting contains a list of Frequently Asked
               Questions (and their answers) about Foo computers.  It
               should be read by anyone who wishes to post to the
               comp.sys.foo newsgroup.

  2. The auxiliary header

     The auxiliary header looks like the main message header (i.e.
     "Field-name: field-value"), but is separated from the main
     message header by a blank line, as well as followed by a blank
     line separating it from the rest of the body of the message.

     The auxiliary header of this posting is:

      Archive-name: news-answers/guidelines
      Version: $Id: guidelines,v 1.68 1993/10/20 01:34:15 jik Exp $

   a. Archive-name (Required)

      In order to be cross-posted in news.answers, your posting must
      include an auxiliary archival header with an "Archive-name:"
      field.

      The purpose of the archive name is two-fold.  First of all, it
      specifies where the FAQ should be stored in archives of the
      news.answers newsgroup.  Second, it should give people, even
      people who do not read the home newsgroup of the FAQ, a pretty
      good idea of what's in it.  Therefore, abbreviations which will
      only be recognized by people already familiar with the topic
      covered by the FAQ should be avoided if possible.

      The archive name should be composed of one or more one-word
      (i.e., no spaces) components, separated by slashes.  Each
      component should be 14 characters or less in length, if
      possible, but this is not a strict requirement; if 14 characters
      isn't enough, then each component should be unique in the first
      14 characters (i.e., two archive names should never be identical
      after their components are all truncated to 14 characters).
      Avoid periods in the archive name, because some operating
      systems choke on them; if you must have word separators, use
      hyphens or underscores rather than periods.

      The archive namespace is hierarchical; for example, there are a
      number of lists of bookstores in the "books/stores" directory of
      the namespace, and all of their archive names start with
      "books/stores/".  Avoid using slashes in your archive name
      unless you are taking advantage of the hierarchical nature of
      the namespace, i.e., unless you have multiple related FAQ
      postings which should appear in a single directory in the
      archive namespace.

      Multi-part FAQs should be named "name/part1", "name/part2", etc.
      Alternatively, if the parts of the FAQ are split by topic rather
      than by size, then you can use short topic names rather than
      "part1", "part2", etc.

      If you post a diff for your FAQ, it should be named "name/diff".
      If you post multiple diffs for a multi-part FAQ, they should be
      named "name/diff1", "name/diff2", etc. (if you want to use just
      one diff for a multi-part FAQ, you can just use "name/diff" as
      its name).  If you post a diff to a one-part posting, then the
      original FAQ should be named "name/part1" (or "name/faq", or
      whatever else you think is appropriate, as long as I approve it)
      and the diff should be named "name/diff".

      Consider these examples:

        Topic                                   Archive name(s)
        -----------------------------------     ------------------------------
        comp.ai FAQ                             ai-faq/part1
                                                ai-faq/part2
                                                ai-faq/part3
        rec.travel.air FAQs, various topics     air-travel/bucket-shops
                                                air-travel/cheap-tickets/part1
                                                air-travel/cheap-tickets/part2
                                                air-travel/faq
                                                air-travel/jetlag-prevention
                                                air-travel/na-airport-codes
                                                air-travel/world-airport-codes
        soc.culture.esperanto FAQ               esperanto-faq

      Please pick the archive name that you would like to use for your
      posting, and include the "Archive-name:" line with that archive
      name in it, when submitting to news.answers.  If there is some
      problem with it, or if I would like to suggest an alternate
      name, I will let you know.

      Example:

       Archive-name: foo-faq

      If your posting already has an "Archive-name:" line which is not
      a valid news.answers archive name and you do not want to change
      it, or if you want the "Archive-name:" line you add to contain
      the name of a file in your own archives rather than in the
      news.answers archives, you can use a
      "News-answers-archive-name:" header line instead.

   b. Other archive names (Optional)

      The software which builds the FAQ archive on rtfm.mit.edu (see
      the "Introduction to the *.answers newsgroups" posting for more
      information about it) automatically uses the "Archive-name:"
      line to determine the file name in which to save an FAQ, when
      saving it in any of the "answers" newsgroups (news.answers,
      rec.aviation.answers, etc.).

      Furthermore, if you have a field of the form
      "Newsgroup-name-archive-name: name" in your FAQ's auxiliary
      header (see the example below), the specified archive name will
      be used to save in the specified newsgroup.  Such a
      newsgroup-specific archive name overrides any generic
      "Archive-name:" line.

      When an archive name for an FAQ cannot be determined in either
      of the ways mentioned above, the Subject line of the posting
      (with some minor modifications) is used as its file name.

      For example, if you have this in your normal header:

       Newsroups: comp.foo,comp.bar,comp.answers,news.answers
       Subject: Comp.foo FAQ

      and this in your auxiliary header:

       Archive-name: foo-faq
       Comp-bar-archive-name: bar-faq

      then the posting will be saved as "foo-faq" in comp.answers and
      news.answers (because they are both "answers" newsgroups and
      will therefore use the Archive-name line), as "bar-faq" in
      comp.bar, and as "Comp.foo_FAQ" in comp.foo.

      If you do decide to specify additional archive names in your
      posting, please obey the guidelines for archive names given
      above.

   c. Last-modified, Version (Optional)

      You can have other fields in the auxiliary header, if you want.
      Two common ones are "Last-modified:" and "Version:".

      Example:

       Last-modified: 1992/03/25
       Version: 2.5

  3. Sample FAQ headers

     Putting together the examples I've given above, your FAQ's
     headers (or, at least, the ones you submit to me) might look like
     this:

     From: [e-mail] (Joe R. Programmer)
     Newsgroups: comp.sys.foo,comp.answers,news.answers
     Subject: comp.sys.foo FAQ
     Followup-To: comp.sys.foo
     Reply-To: [e-mail] (FAQ Comments address)
     Summary: This posting contains a list of Frequently Asked
             Questions (and their answers) about Foo computers.  It
             should be read by anyone who wishes to post to the
             comp.sys.foo newsgroup.
     Expires: Fri, 1 May 1992 00:00:00 GMT
     Supersedes: <[e-mail]>

     Archive-name: foo-faq
     Last-modified: 1992/03/25
     Version: 2.5

     Note that the blank line separating the normal header from the
     auxiliary header must be completely blank, i.e., no tabs or
     spaces, and that there must also be one or more completely blank
     lines after the auxiliary header.

     Of course, you can include in the posting header any of the other
     standard USENET header fields that have not been discussed here.

 C. Posting frequency

    The frequency at which you choose to post your FAQ is left to your
    discretion.  Some FAQ maintainers find that a monthly posting,
    with an Expires header to prevent each posting from going away
    before its replacement is posted, is sufficient.  Some other
    newsgroups are so busy that a weekly posting of the FAQ is needed.
    Another possibility is to post the complete FAQ relatively
    infrequently, while posting a shorter pointer to it (e.g.,
    providing instructions for getting it from archives) more
    frequently.

    If you choose to post your FAQ more frequently than once per
    month, you might want to consider not cross-posting it to
    *.answers every time you post.  Although it may be necessary to
    post the FAQ in its home newsgroup often, it is probably not
    necessary to post it in *.answers as frequently.

    Note, however, that if you do this, you can't use Supersedes every
    time you post your FAQ, since a posting in just the FAQ's home
    newsgroup should not supersede the posting in both the home
    newsgroup and *.answers.  Therefore, unless you're willing to have
    two copies of your FAQ in your home newsgroup at all times, you
    should always cross-post to *.answers (or use the system mentioned
    above, cross-posting the full FAQ to *.answers and a more frequent
    pointer posting just in its home newsgroup).

    When submitting your FAQ, please be sure to let me know the
    frequency at which you intend to post it to its home newsgroup, as
    well as the frequency at which you intend to cross-post it to
    *.answers (if different).

 D. Mailing lists for FAQ maintainers

    Maintainers of FAQs are strongly urged to join the faq-maintainers
    mailing list, which is used for discussion about the *.answers
    newsgroups and the maintenance of USENET FAQs.

    If you don't want to be on the discussion list, you may wish to
    join the faq-maintainers-announce list, which will be used only
    for announcements, instead.  Note that subscribers to
    faq-maintainers automatically receive messages sent to
    faq-maintainers-announce.

    When submitting your FAQ, make sure to let me know whether or not
    you want to be on one of the lists.

 E. List of Periodic Informational Postings

    Unless you tell me otherwise, I will add any postings submitted to
    *.answers to the "List of Periodic Informational Postings" (LoPIP)
    articles which appear in news.answers, news.lists, and
    news.announce.newusers.

    If you do not have copies of the LoPIP postings and would like to
    get them, to see what they're like or to check if your FAQ is
    already listed, see the instructions at the end of this message.

 F. Article approval

    Once all of the other issues listed in this posting are resolved,
    you will be given approval to cross-post your FAQ to *.answers.
    You will have to indicate in the header of your posting that such
    approval has been given, or the posting will be mailed to me
    instead of posted.

    Note that I am intentionally being somewhat vague about what this
    entails.  When I approve your posting for *.answers, I will
    provide more specific instructions.


II. Submission instructions

   If you have a posting which you wish to submit to *.answers, you
   should first read the guidelines listed above and modify your
   posting to conform to them.  Then, you should submit it by posting
   it to the news.answers newsgroup, assuming that the software on the
   poster's site works properly and will forward the posting to the
   news.answers moderator, or by mailing it to the news.answers
   submission address, [e-mail].  ONLY SUBMISSIONS SHOULD
   BE MAILED TO THAT ADDRESS.  If there is some commentary or
   explanation that needs to be made, it should be mailed in a
   separate message to [e-mail], which is the
   moderator contact address for any *.answers-related business.

   Please submit the FAQ in a form as close as possible to how it
   appears when you post it normally.  This means that you should
   include a complete header, with at the very least the Subject line
   you normally use.  I very much prefer you actually posting the
   message to news.answers as you would post it normally, including
   the cross-posted newsgroups, but omitting the moderation approval
   header line that would cause the article to actually be posted
   rather than mailed to me; this way, I will get to see exactly how
   the article will look when it is actually posted in news.answers.
   Also, if your FAQ does not say somewhere near the top how often it
   is posted, then please let me know the frequency in separate
   E-mail.

   Note that if you do not indicate moderator approval in the header
   of your posting, it will NOT be posted to any newsgroup, even if
   you list other newsgroups on the Newsgroups line besides *.answers
   groups.  Therefore, you CAN and SHOULD place all Newsgroups to
   which you intend to post in the Newsgroups line, in the order you
   intend them to be in when you post.

   I will respond, by agreeing that the FAQ belongs in *.answers
   as-is, or by asking you to make minor modifications to it in order
   to make it acceptable, or by rejecting it as inappropriate for
   *.answers.  If you are asked to make modifications, please do so
   and resubmit the posting to me just as you did the first time.

   Once an FAQ has been approved for *.answers, you will post it
   directly to the group yourself, by indicating in the header of the
   message that it was approved by the *.answers moderator, as
   described above.

   If possible, try to avoid posting your FAQ at a "predictable"
   time.  For example, if you have decided to post it monthly, don't
   automatically decide to post it on the first of every month.  This
   causes a flood of FAQs in *.answers (and on the net in general) at
   certain times of months, and this flood is big enough to overwhelm
   some smaller sites and many readers of *.answers.  Therefore,
   rather than picking the "obvious" time to post, pick some other,
   random time during the month to do your posting.

III. Once your posting is approved

   The following is a list of some situations which might occur after
   your FAQ has been approved for *.answers, and what you need to do
   for each one.

   A. Transfer an FAQ to a new maintainer

      The old maintainer should inform [e-mail] of
      the change in maintainers.  The new maintainer should read this
      document (i.e., the "*.answers submission guidelines") and
      inform [e-mail] that he has done so.
      Furthermore, the new maintainer should resubmit the FAQ if he
      intends to make any header changes other than changing the From
      and/or Reply-To lines.  The new maintainer should wait for
      approval before posting.

   B. Change an FAQ's posting frequency

      Inform [e-mail] of the new frequency.

   C. Change an FAQ's header(s)

      1. Subject line

     Inform [e-mail] of the new Subject line,
     or resubmit the entire FAQ to [e-mail], and wait
     for approval before posting.

      2. Newsgroups line

     Inform [e-mail] of the new Newsgroups
     line, or resubmit the entire FAQ to [e-mail], and
     wait for approval before posting.

      3. From line, without changing maintainers

     If the new From line obviously refers to the same individual
     as the old one, you don't have to do anything.  If it's not
     obvious that the new From line refers to the same individual,
     inform [e-mail] and wait for approval
     before posting.

      4. Archive-name line

     Inform [e-mail] and wait for approval
     before posting.

      5. Followup-To line

         As long as it exists and doesn't contain any *.answers
     newsgroups in it, you don't have to do anything.

      6. Other headers

         As long as you don't change the overall structure of your
     headers (e.g., make sure you keep an auxiliary header with
     the Archive-name line in it), you don't have to do anything
     about changes to other headers.

   D. Add postings to or delete postings from an FAQ

      1. Add a new part to a multi-part FAQ

     Submit the new part to [e-mail], or inform
     [e-mail] if the new part's headers are
     consistent with the other parts (e.g., if your Subject lines
     are in the form "foo FAQ part * of *" and your archive names
     look like "foo-faq/part*", and you add a new part which looks
     just like the others except for a new part number, you don't
     have to resubmit the new part or resubmit all the other parts
     because you changed the "of *" number in their Subject
     lines).  Wait for approval before posting.

      2. Delete a part from a multi-part FAQ

     Inform [e-mail].  Wait for approval
     before posting.

      3. Terminate an FAQ (i.e., stop posting it forever)

         Inform [e-mail].

   E. Create a new FAQ

      Submit it to *.answers following the guidelines in sections I
      and II above, just like you submitted your previous FAQ(s).


IV. This posting

   Comments about, suggestions about or corrections to this posting
   are welcomed.  If you would like to ask me to change this posting
   in some way, the method I appreciate most is for you to actually
   make the desired modifications to a copy of the posting, and then
   to send me the modified posting, or a context diff between my
   posted version and your modified version (if you do the latter,
   make sure to include in your mail the "Version:" line from my
   posted version).  Submitting changes in this way makes dealing with
   them easier for me and helps to avoid misunderstandings about what
   you are suggesting.

   The following people provided feedback and helped to make this
   posting more readable and useful:

     Stan Brown <[e-mail]>
     L. Detweiler <[e-mail]>
     Aydin Edguer <[e-mail]>
     [e-mail]
     Cindy Tittle Moore <[e-mail]>
     Steven D. Ourada <[e-mail]>
     Ken Shirriff <[e-mail]>
     Dan Tilque <[e-mail]>
     Bill Wohler <[e-mail]>


V. Getting the "List of Periodic Informational Postings"

   There are five "List of Periodic Informational Postings"
   postings:

    Subject: List of Periodic Informational Postings, Part 1/6
    Subject: List of Periodic Informational Postings, Part 2/6
    Subject: List of Periodic Informational Postings, Part 3/6
    Subject: List of Periodic Informational Postings, Part 4/6
    Subject: List of Periodic Informational Postings, Part 5/6
    Subject: List of Periodic Informational Postings, Part 6/6
    Newsgroups: news.lists,news.announce.newusers,news.answers

   They are available in the indicated USENET newsgroups, or via
   anonymous ftp from rtfm.mit.edu (18.70.0.209) in the files:

    /pub/usenet/news.answers/periodic-postings/part1
    /pub/usenet/news.answers/periodic-postings/part2
    /pub/usenet/news.answers/periodic-postings/part3
    /pub/usenet/news.answers/periodic-postings/part4
    /pub/usenet/news.answers/periodic-postings/part5
    /pub/usenet/news.answers/periodic-postings/part6

   They are also available from [e-mail] by sending a
   mail message containing any or all of:

    send usenet/news.answers/periodic-postings/part1
    send usenet/news.answers/periodic-postings/part2
    send usenet/news.answers/periodic-postings/part3
    send usenet/news.answers/periodic-postings/part4
    send usenet/news.answers/periodic-postings/part5
    send usenet/news.answers/periodic-postings/part6

   If you want to find out more about the mail server, send a message
   to it containing "help".

---------------------------------------------------------------------------
.