yEncode - V1: formal specification proposal   (25. Feb 2002)
------------------------------------------------------------------------------

General:

yEncode is a general efficient method to encode an 8 bit binary for net-transport or 
storage when just a specific amount of character-codes is critical and must be avoided.

yEncoding can be used (for example) in Usenet messages, eMail messages or as a block 
in a file.

This formal spec contains extensions for yEnc-V2 - marked by:  // yEnc-V2

Purpose:

This proposal is made to describe the actual status - and possible future expansions.
It is not a part of yEnc yet.

Notation:
	{ }  // Repetition
	[  ]  // Optional
	//    // Comment
	|      // Or - alternatively
	<xx>  // Item
	CR  // single characters
	
Usenet-Messages
------------------------

<Usenet-message> :=
	<Message-Headers>
	<Empty Line>
	[ <Ignored part> ]
	{
		<yEncoded Binary>
		[ <Ignored part> ]
	} n times

<Message-Headers> := 
	{
	<Subject-Header>
	| // or
	<See RFCs>
	} n times

<Empty Line> := CRLF

<Ignored part> := any text - but CRLF=ybegin

<yEncoded Binary> :=
	<yEnc-Header>
	[ <yEnc-Info> ]   // optional for multiparts
	[<yEnc-Context>]  // yEnc-V2 - tbd.
	<yEnc-Data>
	<yEnc-Terminator>

<yEnc-Header> :=
	CRLF
	// This requires an empty line between two encoded binaries in one message
	=ybegin   | (or)   =ybegin2   (for yEnc-V2)
	SPACE
	<yEnc-Parameter-List>
	CRLF   
<yEnc-Data> :=
	{
		{
		<yEncoded character> 
		| // or
		<yEncoded escape character>
		}  until <linevalue> is reached or exceeded (or binary is done)
		CRLF
	} // until binary is done - or part is complete

<yEnc-Terminator> :=
	=yend
	<yEnc-Trailer-List>

<yEnc-Parameter-List> :=
	<optional parameter list>
	<linesize> SPACE
	<binarysize> SPACE
	<binaryname>
	
<linesize> :=
	line=
	<linevalue>

<linevalue> :=
	unsigned integer. (Range: 63-998)
	// Lines have this size 
	// - or this size+1 if the 2nd last char is the escape character

<binarysize> :=
	size=
	<sizevalue>

<sizevalue> :=
	unsigned integer: Size of the original binary (Range: 1  -  2^62-1)
	// It is not permitted to encode binaries with the size NULL!	

<binaryname> :=
	name=
	ASCII-string // (The name of the binary when stored to disk OK)
			// In case of corruption: <disk filename>
	CRLF
	// The ASCII string must only contain chars from ASCII 32-ASCII 127
	// Leading or tailing spaces (ASCII 32) are generally ignored
	// The string must not be empty
	// Characters which are not available on the platform are replaced 
	// by Underscore at decoding time
	// These characters are not permitted:  / \ : < >" @
	// These character are permitted!:  [ ] ( ) 
	
<yEnc-Trailer-List> :=
	SPACE
	<binarysize>  // identical to the <binarysize> in the <yEnc-Header>
	<optional endparameter list>
	CRLF


<yEncoded character> :=
	(<Permitted character> + <offset-value> ) modulo 256
	// Permitted for the transport medium

<yEncoded escape character> :=
	<escape-character>
	(<critical character> + <offset-value> + <escape-offset-value>) modulo 256
	
<offset-value> :=
	42 // default
	| // Or 
	<offset-parameter> // if present in <optional parameters> // yEnc-V2

<escape-character> :=
	= // default
	// Or 
	<escape-parameter> // if present in <optional parameters> // yEnc-V2

<escape-offset-value> :=
	64
	// Or 
	<escoffset-parameter> // if present in <optional parameters> // yEnc-V2

<critical character> :=
	<character 0-255> + <offset-value>  is not allowed on the medium
	|
	CR, LF, NULL <escape-character>, on Usenet
	|
	CR,LF,NULL, '>' in HTML and XML  // yEnc-V2
	|
	TAB, SPACE as the first or last character in the encoded line (eMail) // yEnc-V2
	|
	DOT as the first character on Usenet	

<optional parameters> :=
	{
	<optional parameter> 
	SPACE
	} n times

<optional parameter>
	part=<partnumber>   // requires <yEnc-Info-Line>
	| // or
	total=<total parts>   // requires "part="   yEnc-V2 
	| // or
	<offset-parameter> // yEnc-V2
	|  // or
	<escape-parameter> // yEnc-V2
	|  // or
	<escoffset-parameter> // yEnc-V2
	|  // or
	<crc-parameter>  // yEnc-V2
	|  //
	<compression-parameter>  // yEnc-V2

<partnumber> :=
	Unsigned integer (1-999)  // part-number for splitted binaries

<total parts> :=
	Unsigned integer (1-999) // total number of part during encoding
	// 1 is possible - this is a splitted message with one part

<offset-parameter>  :=
	offset=
	<42> // on Usenet '*'
	|
	<unsigned integer> (0-255) // by medium and optimization - yEnc V2
	// Must not result in =y at start of a line
	|
	0 // for 1-1 encoding - only escaping critical chars
<escape-parameter> :=
	escape=
	'=' // on Usenet: ASCII 61
	<unsigned integer> (0-255) // by medium and optimization - yEnc V2
	// Must not result in =y at start of a line
	
<escoffset-parameter> :=	
	escoff=
	<64> // on Usenet
	<unsigned integer> (1-255) // by medium and optimization - yEnc V2
	// Must not result in =y at start of a line
	// Cannot be NULL 0

<crc-parameter> :=
	crc32=
	8 char hexvalue // Representing the 8-bit CRC32 of the encoded binary
	// Leading 0's required - fixed size parameter !

<compression-parameter> :=     // yEnc - V2
	comp=
	<compression method>

<compression method> :=   // yEnc - V2
	zip
	|
	rar	
	|
	gzip
	|
	rle
	|
	<other identifier>

	// if the method is unknown then the decoder must write the decoded binary
	// to disk "as is" and expand the filename with a DOT and this identifier
	// for an external decoder.
	
<optional end-parameter list> :=
	{
	SPACE
	<optional end parameter> 
	} n times

<optional end parameter>
	[	part=<partnumber>   // identical to upper appearance
		partcrc=<partial crc-parameter>  // required if "part=" is used
		]
	|  // or
	<crc-parameter>  // identical to upper appearance (if used in =ybegin)

<partial crc-parameter> :=
	pcrc32=
	8 char hexvalue // Representing the 8-bit CRC32 of the encoded binary part 
			// since <yEnc-Header>
			// Leading 0's required - fixed size parameter !

<yEnc-Info> :=
	=ypart
	SPACE
	begin=<start-position>
	SPACE
	end=<end-position>
	CRLF

<start-position> :=
	unsingned integer (1 - 2<62-1) 
	//  the position of the first byte in the originally encoded binary in <yEnc-Data>
	// Remark: The first byte in a binary has the position 1 (one)

<end-position> :=
	unsingned integer (2 - 2<62-1) 
	//  the position of the last byte in the originally encoded binary in <yEnc-Data>
	// Always smaller than <start-position>
	// Remark: The last byte in a binary has the position identically to the size of it.


<Splitted Usenet-message> :=
	{
	<Message-Headers>
	<Empty Line>
	<Ignored part>
	<yEncoded Binary> // with <yEnc-Info> and all other partial info required
	<Ignored part>
	} n times

<Subject-Header> :=
	Subject:
	SPACE
	[<Comment1> SPACE]  // optional - for the user (layer-8)
	" <filename> " SPACE
	SPACE yEnc 
	[SPACE <part-indicator>] // required for multipart
	SPACE <binarysize> 
	SPACE bytes 
	[SPACE <Comment2>] // Optional for the user (layer-8)	
	CRLF

<Comment1>
	Any text - not including  (*/*)  // * = any text
	|
	Any text - not including these characters: ( / ) "  // yEnc-V2

<Comment2>
	Any text - not including  (*/*) and [*/*]  // * = any text
	Any text - not including these characters: ( / ) [ ] "  // yEnc-V2

<part-indicator> :=
	(
	<partnumber>
	/
	<total parts>
	)

<disk filename> :=
	<binaryname> // If decoding worked properly
	| // or
	<binaryname> with illegal characters change to underscore '_'
	| // or

	<name-part in front of '.'> 
	( 
	<problem identifier>
	).
	<name-part after '.')

<problem identifier> :=
	corrupt
	|
	<specific error text>


<42> :=
	integer value 42  
	// Good "rotation value" for common binary formats.
	// Proof is in progress and will be done in the future 
	// (see: Hitchhikers Guide to the Galaxy)

<64> :=
	Integer value 64
	// This value converts  CRLF into =M=J
	// This is a commonly used abbreviation (CTRL+M, CTRL+J)

<yEnc-Context>
	{
		=ydata 
		SPACE
		<additional information about the binary>	
		CRLF
	} n times

<MIME-Message> :=
	// tbd.

<clue> := 
	// N/A   ;-)


-- 
End of doc