www.delorie.com/howto/submit.html   search  
Submit a HOWTO

To submit a HOWTO, you must email it to me in a special format. After checking it out, my system will send you a confirmation URL. Cut and paste that URL into your web browser, and your HOWTO will be installed!

If you later want to update the HOWTO, simply mail in a replacement. As long as the category, filename, and email address all match, the old will be replaced with the new. Send me email if you want a HOWTO removed or renamed.

Note: Your email address will be published with your HOWTO, and you must provide a valid one (else your howto cannot be installed). This is to make people think twice about being jerks and submitting stupid or inappropriate howtos.

The HOWTO submission format is as in this example:

To: howto@delorie.com
Subject: (doesn't matter)

%%howto-version: 1.0
%%title: Your Title Here
%%url: http://blah.com/blah-blah.html
%%category: djgpp
%%filename: dosemu-install
%%author: Your Name Here

One paragraph summary of what the howto is about

Body of HOWTO

%%end-howto

The first section is just the regular mail headers. Your mail program may not even place them in with the text of the mail - they may be fill-in fields. The important thing is that the message must be mailed to howto@delorie.com (don't send anything else there). It doesn't matter what you put for a subject, it will be ignored.

The second section is part of the mail message itself. It's important that you format this section correctly, or else your mail will be rejected. Note that each line starts with two percents, a field name, a colon, one or more spaces or tabs, and the value of the field. There must be no spaces around the percents or before the colon, and you must use lower case. The howto-version field must be first, but the other fields may be in any order.

howto-version (mandatory)
You must include this line exactly as shown. The program that reads howto submissions will ignore any mail that doesn't have this (spam, misdirected mail, etc). This also allows the mail program to decipher so-called "rich media" emails (mime, html, etc) that some new-fangled mailers have been known to do.

title (mandatory)
The title of your HOWTO. This will be used to construct the visible text of the links to your HOWTO, and will be the title placed on the final web page as well. Your title may only contain letters, numbers, spaces, underscores, dots, and hyphens. Your title should be brief yet descriptive, preferably containing suitable keywords.

url (optional)
If you maintain an official copy of your howto elsewhere, please put a direct link to that version here. Please don't use this for anything else; if the user follows this link they should see basically the same content as you are submitting, possibly more up to date.

category (mandatory)
One of the following (lower case, exact spelling): djgpp allegro rhide cygwin

filename (mandatory)
You may recommend a file name to store your HOWTO as. The filename may only contain lower case letters, digits, and hyphens. The name should reflect the title and may not already be in use. The name must be at least three but no more than thirty characters in length.

author (optional)
Your full name. We figure out your email address from the mail you send us (we send the confirmation to it), but we don't try to deduce your full name from that. If you omit your full name, your email address will be used as a substitute. Your name may only contain letters, digits, hyphens, and spaces. Please list your personal name first followed by your family name.

OK, next you must skip a line and write a one paragraph (four 80-column lines or less) summary about what this howto is all about. This will be displayed in addition to the title in cases where there is sufficient room to allow the extra text. Usually your title will be all the user sees. This paragraph will also be placed at the top of your howto's page. No HTML is allowed, nor will URLs be tagged as such.

OK, next you must skip a line and fill in your HOWTO. Don't use HTML - it will not do what you expect. Do not include a title or header; one will be provided for you. You may include URLs in your text; they will be marked as hypertext links (just type the url, don't use <a>). There is a limit of 1000 80-column lines per HOWTO (about 16 printed pages).

The last line in your howto must be the %%end-howto line. This doesn't have to be the last line in your mail. In fact, it's there to make sure the program that handles these mails knows how to remove any automatic signature from the mail. You must include this line exactly as is - two percents and the words "end-howto" with no spaces, alone on a line.


  webmaster   donations   bookstore     delorie software   privacy  
  Copyright 2003   by DJ Delorie     Updated Oct 2003