.\"
.\"	Man page for `ypost'
.\"
.\"	$Header: /pub/cvsroot/yencode/doc/ypost.1,v 1.6 2002/03/21 04:58:31 bboy Exp $
.\"
.\"	Copyright (C) 2002  Don Moore <bboy@bboy.net>
.\"
.\"	Process this file with `groff -man -Tascii ypost.1'
.\"
.TH ypost 1 "March 2002" yencode "User Commands"
.SH NAME
ypost \- Post file(s) to Usenet
.SH SYNOPSIS
.B ypost
[\fB-a\fP, \fB--author=\fP\fIname\fP]
[\fB-c\fP, \fB--comment=\fP\fIcomment\fP]
[\fB-d\fP, \fB--debug\fP]
[\fB-f\fP, \fB--force\fP]
[\fB-g\fP, \fB--group=\fP\fInewsgroup\fP]
[\fB-l\fP, \fB--line=\fP\fIlength\fP]
[\fB-m\fP, \fB--multipart=\fP\fIlines\fP]
[\fB-M\fP, \fB--message-id]
[\fB-n\fP, \fB--nosort\fP]
[\fB-p\fP, \fB--paths\fP]
[\fB-P\fP, \fB--pass=\fP\fIpassword\fP]
[\fB-q\fP, \fB--quiet\fP]
[\fB-r\fP, \fB--retry=\fP\fIretries\fP]
[\fB-s\fP, \fB--subject=\fP\fIsubject\fP]
[\fB-S\fP, \fB--server=\fP\fIaddress\fP]
[\fB-t\fP, \fB--timeout=\fP\fItimeout\fP]
[\fB-U\fP, \fB--user=\fP\fIusername\fP]
[\fB--sfv=\fP\fIname\fP]
[\fB--stdout\fP]
[\fB--crc=\fP\fIname\fP]
[\fB--help\fP]
[\fB--version\fP]
\fBFILE\fP \fB...\fP

.\"
.\"  DESCRIPTION
.\"
.SH DESCRIPTION
\fBypost\fP encodes and posts the files specified on the command line to a Usenet server, which may be specified
either on the command line or in the \fBypost\fP configuration file, located in the user's home directory and
named \fI.ypostrc\fP (see \fBypostrc\fP(5)).  Options provided on the command line always take precedence over
the options specified in the user's \fI.ypostrc\fP.

By default, \fBypost\fP always posts large files as multipart archives in multiple messages, with each message
containing 5000 lines (or about 640k).

.\"
.\"  OPTIONS
.\"
.SH OPTIONS
.IP "\fB-a\fP, \fB--author\fP=\fIname\fP"
When posting messages, use the \fIname\fP specified in the Usenet \fBFrom:\fP header field.  See the \fBAUTHOR SYNTAX\fP
section below for correct syntax.
If the \fIname\fP argument is omitted, \fBypost\fP will attempt to prompt the user interactively for this information.

.IP "\fB-c\fP, \fB--comment\fP=\fIcomment\fP"
The \fBSubject:\fP header field of each message will be suffixed by the specified \fIcomment\fP, enclosed in square
brackets.
If the \fIcomment\fP argument is omitted, \fBypost\fP will attempt to prompt the user interactively for this information.

.IP "\fB-d\fP, \fB--debug\fP"
Write messages useful for debugging to stderr while program is operating.

.IP "\fB-f\fP, \fB--force\fP"
By default, \fBypost\fP will output a summary before posting messages, describing what will be posted.  This option
disables that behavior and posts the messages without confirmation.

.IP "\fB-g\fP, \fB--group\fP=\fInewsgroup\fP"
Messages will be posted to the specified \fInewsgroup\fP.

.IP "\fB-l\fP, \fB--line\fP=\fIlength\fP"
Create encoded lines of \fIlength\fP characters, instead of 128, which is the default.

.IP "\fB-m\fP, \fB--multipart\fP=\fIlines\fP"
Split files into multipart posts after \fIlines\fP rather than 5000, which is the default.  Note that this usage
differs from the \fByencode\fP program, which accepts a file size instead.

.IP "\fB-M\fP, \fB--message-id\fP"
Output the \fBMessage-ID:\fP header when posting (normally not needed).

.IP "\fB-n\fP, \fB--nosort\fP"
Do not sort the list of input files before posting.

.IP "\fB-p\fP, \fB--paths\fP"
Save relative pathnames to files in the encoded data.  For example, running \fBypost files/new/bigfile.mp3\fP
will by default store the filename as \fBbigfile.mp3\fP.  If the \fB-p\fP option is specified, the filename
will be stored as \fBfiles/new/bigfile.mp3\fP.

.IP "\fB-P\fP, \fB--pass\fP=\fIpassword\fP"
Use \fIpassword\fP to authenticate with the news server.  If \fIpassword\fP is omitted, the user will be prompted.

.IP "\fB-q\fP, \fB--quiet\fP"
Try to avoid writing output while running.  The only output that will occur is error messages.

.IP "\fB-r\fP, \fB--retry\fP=\fIretries\fP"
Specify the number of \fIretries\fP after which a post attempt will fail.

.IP "\fB-s\fP, \fB--subject\fP=\fIsubject\fP"
The \fBSubject:\fP header field of each message will be prefixed by the specified \fIsubject\fP, enclosed in square
brackets.
If the \fIsubject\fP argument is omitted, \fBypost\fP will attempt to prompt the user interactively for this information.

.IP "\fB-S\fP, \fB--server\fP=\fIaddress\fP"
Post messages through the news server located at the specified \fIaddress\fP.

.IP "\fB-t\fP, \fB--timeout\fP=\fIseconds\fP"
Cause socket operations (such as connects, reads, and writes) to time out after the specified number of \fIseconds\fP.
The default timeout is 120 seconds.

.IP "\fB--sfv\fP=\fIname\fP"
Post a yencoded SFV file containing the checksum of each input file.  If \fIname\fP is specified, then that name will
be used as a prefix for the SFV file.

.IP "\fB--stdout\fP"
Output messages to standard output instead of posting them via Usenet.  This can be used if you want to see what
\fBypost\fP's output will look like without actually posting anything to Usenet.  If the standard output is a terminal,
the encoded data will be omitted, to keep your screen from filling with garbage and messing up your terminal.

.IP "\fB--crc\fP=\fIname\fP"
Post a yencoded CRC file containing the checksum of each input file.  If \fIname\fP is specified, then that name will
be used as a prefix for the CRC file.  Note that this CRC file may or may not comply with the "standard" for what a 
\fB.crc\fP file is supposed to contain.

.IP "\fB--help\fP"
Display program help and exit.

.IP "\fB--version\fP"
Output version number and exit.


.\"
.\"  QUICKSTART
.\" 
.SH QUICKSTART
First create a \fB.ypostrc\fP file in your home directory ("\fB~/.ypostrc\fP") containing your news server information.
This file will keep you from having to enter the server information on the command line every time you run the program.
Make sure the file is not readable by other users ("\fBchmod 0600 ~/.ypostrc\fP") if it contains a username or password.
You can run "\fBman ypostrc\fP" for the full documentation, but here's an example that should give you a good start:
.IP
.nf
# ~/.ypostrc - sample configuration

server = news.example.com                # The name of your news server
user   = user1234                        # Username (if your server requires it)
pass   = IloveUnix                       # Password (if your server requires it)
author = "juser@example.net (Joe User)"  # Use this address in the \fBFrom:\fP line
.fi
.LP
Now, let's say you have a short video you want to post, and all the files are in the directory \fB/home/bboy/video\fP:
.IP
.nf
total 6816
-rw-r--r--    1 bboy     bboy         1776 Mar 14 23:24 shortfilm.nfo
-rw-r--r--    1 bboy     bboy      3072000 Mar 14 23:13 shortfilm.r00
-rw-r--r--    1 bboy     bboy       817510 Mar 14 23:13 shortfilm.r01
-rw-r--r--    1 bboy     bboy      3072000 Mar 14 23:13 shortfilm.rar
.fi
.LP
To post these files to the newsgroup \fBalt.binaries.test.yenc\fP, and create an SFV file for them as well, you would
run:
.IP
.nf
\fBypost --sfv -g alt.binaries.test.yenc /home/bboy/video/*\fP
.fi
.LP
When you run the command, \fBypost\fP will output a summary of the messages it is about to post, before actually posting
the messages:
.IP
.nf
       Server: news.example.com
    Newsgroup: alt.binaries.test.yenc
       Author: juser@example.net (Joe User)

  1. "shortfilm.nfo" 1776 yEnc bytes
  2. "shortfilm.sfv" 402 yEnc bytes
  3. "shortfilm.rar" yEnc (x/5) 3072000 bytes
  4. "shortfilm.r00" yEnc (x/5) 3072000 bytes
  5. "shortfilm.r01" yEnc (x/2) 817510 bytes

Post 5 files (14 parts)? [y]es, [n]o: 
.LP
Notice that \fBypost\fP tries to post your files in a sensible order.  \fB.nfo\fP and \fB.sfv\fP files and the like
get posted first, and the \fB.rar\fP file gets posted before the \fB.r00\fP file, instead of at the end.
.LP


.\"
.\"  SUBJECT LINE FORMAT
.\" 
.SH SUBJECT LINE FORMAT
The yEnc specification includes subject line formats for single part and multipart Usenet posts, and strongly
recommends their use.  \fBypost\fP is compliant with the specification, and no facility is included to override this
behavior.  However, there are two comment areas allowed by the specification: one before, and one after the file information.
The comment before the file info may be specified by the \fB-s\fP (\fB--subject\fP) option, and the comment after the
file info may be specified by the \fB-c\fP (\fB--comment\fP) option.  Thus
.IP
.nf
ypost -s'Test Post' -c'file %f of %F' test.zip test.txt
.fi
.LP
would post the two files specified (\fBtest.zip\fP and \fBtest.txt\fP) with the following subject lines:
.IP
.nf
[Test Post] "test.txt" 4281 yEnc bytes [file 1 of 2]
[Test Post] "test.zip" yEnc (1/5) 3065891 bytes [file 2 of 2]
[Test Post] "test.zip" yEnc (2/5) 3065891 bytes [file 2 of 2]
[Test Post] "test.zip" yEnc (3/5) 3065891 bytes [file 2 of 2]
[Test Post] "test.zip" yEnc (4/5) 3065891 bytes [file 2 of 2]
[Test Post] "test.zip" yEnc (5/5) 3065891 bytes [file 2 of 2]
.fi
.LP
The variables used in the preceding example may be included in either the subject or the comment line, and will be
replaced on a per-file basis with the relevant data.  The available variables are:
.IP \fB%p\fP
The current part number within the current file.
.IP \fB%P\fP
The total number of parts within the current file.
.IP \fB%f\fP
The current file number within the overall list of files to post.
.IP \fB%F\fP
The total number of files to be posted.
.LP
If you specify either the \fB-s\fP (\fB--subject\fP) or \fB-c\fP (\fB--comment\fP) option without an argument, \fBypost\fP
will prompt you to enter this information.


.\"
.\"  AUTHOR SYNTAX
.\" 
.SH AUTHOR SYNTAX
\fBRFC 1036\fP specifies three permissible forms of user identification.  \fBypost\fP will enforce use of one of these
forms:
.IP "\fBjuser@example.net\fP"
An email address without further explanation.
.IP "\fBjuser@example.net (Joe User)\fP"
An email address followed by comments enclosed by parentheses.
.IP "\fBJoe User <juser@example.net>\fP"
The user's name followed by an email address enclosed by angle brackets.


.\"
.\"  FILES
.\" 
.SH FILES
.I ~/.ypostrc
.RS 
The configuration file used by \fBypost\fP if it is present. See \fBypostrc\fP(5) for further details.


.\"
.\"  AUTHOR
.\"
.SH AUTHOR
Don Moore <bboy@bboy.net>


.\"
.\"  HOMEPAGE
.\"
.SH HOMEPAGE
http://www.yencode.org/


.\"
.\"  SEE ALSO
.\"
.SH "SEE ALSO"
.BR ypostrc (5),
.BR yencode (1),
.BR ydecode (1)