:xml{<?xml version="1.0" encoding="ISO-8859-1"?>}
:xml{<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"/usr/share/docbook-xml42/docbookx.dtd">}

article
{
	title{xfront 0.3.3}

	articleinfo{
	author{firstname{Armin} surname{Sander}}
	}

section id = Intro
{
	title{Introduction}

	p{
		command{xfront} is a frontend to support writing XML documents in a
		style similar to C/C++/Java, using curly brackets to specify scopes of
		elements.  command{xfront} has been developed to get around writing
		documents in the rather intricate XML syntax.
	}

	p{
		cmd{xfront} has been created to aid developers who are in the need of
		writing documentation. Developers usually tend to prefer the C/C++/Java
		style syntax to write their programs, and with time and practice, they
		get very fast writing source code. command{xfront} tries to support
		this style, and wants to attack prejudices against writing XML
		documents.
	}

	p{
		Additionally, XML documents are not really adequate to be used in
		collaboration with revison control systems. The syntax command{xfront}
		expects does not incorporate redundand and distracting XML closing
		element names, and so it is easier to read and - in case of revision
		control - easier to compare visually. 
	}

	p{
		cmd{xfront} tries to support concise writing using em{element name
		aliases} and em{element name combiners}. Both very helpful for
		writing documents using verbose XML DTDs like \ulink
		url="http://www.docbook.org"{DocBook}.  
	}

	p{
		This text has been created using cmd{xfront} and \ulink
		url="http://www.docbook.org" {DocBook}.
	}
}

section
{
	title{Syntax}

	p{
		The syntax of command{xfront} input files is based on emphasis{scoped areas}
		enclosed by lit{'\{'} and lit{'\}'} curly brackets. The
		lit{'\\'} backslash character is used to escape characters which
		would confuse the lexical analysis.

	}
	p{
		Each emphasis{scoped area} is translated into the appropriate XML
		element.  
	}

	section
	{
		title{Elements}

		p{
			XML element names are simply placed before a scope. command{xfront} uses 
			backtracking to query the element name. 
		}

		example
		{
			title{Simple element}

			ix{xp{elements}xs{simple}}

			p/lit{section\{ title\{Introduction\} \}}

			p{produces:}

			p/lit{<section> <title>Introduction</title> </section>}
		}

		p{
			ix/xp{whitespace}

			Whitespace is ignored at places where command{xfront} scans for element
			names. All other whitespaces (including line feeds and tabs) are
			emitted to the resulting XML output. 
		}

		p{
			The whitespace em{before} an element name is emitted, to output
			elements without leading whitespace, you may escape the element
			identifier by the escape character lit{'\\'}. 
		}

		example
		{
			title{Escaping}

			ix{xp{elements}xs{escaping}}

			p/lit{p\{Here I em\\em\{pha\}sized the second syllable.\} }

			p{
				In this example the lit{em} element is escaped using the
				lit{'\\'} character to produce the output:
			}

			p{
				Here I em\emphasis{pha}sized the second syllable.
			}
		}


		p{
			ix{xp{whitespace}xs{in XML output}}

			To avoid whitespace prefixed in lines for literal layouts, leading
			whitespace can be removed by placing the scope introducing
			character lit{'\{'} into a separate line.
		}

		p{
			If cmd{xfront} detects a lit{'\{'} in a separate line, it
			automatically removes the whitespace prefixes which are equal to
			the one seen before the lit{'\{'} from all the lines in the
			associated element scope.
		}
	
		example
		{
			title{Literal layout}
		
			programlisting
			{programlisting
				\{10 PRINT "HELLO"
				20 GOTO 10\}}
		}

		section{
			title{Combining elements}

			ix{xp{elements}xs{combining}}

			p{
				Combining elements is supported using the lit{'/'} character. 
				
				example
				{
					title{Combining elements}

					p{writing}

					p/lit{p/lit\{literal paragraph\}}

					p{is equavilent to writing}

					p/lit{p\{lit\{literal paragraph\}\}}
				}
			}
		}
	}

	section
	{
		title{Attributes}

		p{
			ix/xp{attributes}

			XML attributes are placed emphasis{after} the element name and
			emphasis{before} the scope introducing lit{'\{'} character.
			They are specified similar to the attributes in XML.
		}

		example
		{
			title{Simple attribute}

			ix{xp{attributes}xs{simple}}

			p/lit{section id="A Tutorial" \{ title\{Tutorial\} \}}
		}

		p{
			If the attribute value does not contain whitespace, the quotes
			are optional:  
		}

		example
		{
			title{Attribute quotes}

			ix{xp{attributes}xs{quotes}}

			p/lit{section id=Tutorial \{ title\{Tutorial\} \}}
		}

		p{
			Combined elements and attributes are supported: 
		}

		example
		{
			title{Combined elements and attributes}

			ix{xp{attributes}xs{and combined elements}}

			p/lit{p id="Examples"/ulink url="http://www.examples.org"\{Klick me\}}
		}
	}
}

section { title{xfront command} 

	ix{xp{xfront}xs{command}}

	p{
		lit{xfront [options] [filename...]}
	}

	p{
		command{xfront} processes all input files provided at the command
		line. In case there is no filename given, command{xfront} expects
		input characters to arrive at standard input.  If filenames are
		given, command{xfront} generates an XML file for each input file.
		The output files get the same names like their input files with the
		extension changed to lit{.xml}.  If no filename is specified,
		command{xfront} writes the XML file to standard output.
	}

	vlist
	{
		title{Options}

		ix{xp{xfront}xs{options}}

		ventry{
			term{-a, --aliases FILENAME}

			li/p{Specifies the alias file to use. Aliases are specified for
			em{element names} in the form rpl{alias}=\rpl{elementname}. Empty
			lines and comments (beginning with the lit{'#'} character) are
			supported.}
		}


	}



}	

section
{
	title{Quick help}

		subtitle{
			The most important facts to learn using cmd{xfront}.
		}

	ilist
	{

		li/p
		{
			For escaping lit{'\{' '\}'} or lit{'\\'} use lit{'\\\{'
				'\\\}' '\\\\'}, respectively.  
		} 

		li/p
		{
			To suppress whitespace emphasis{before} an element name, escape the
			element name using lit{'\\'}. 
		}

		li/p
		{
			To emit text directly to XML, use ":xml" as element name. Here,
			command{xfront} will not convert lit{'<'}, lit{'>'} or lit{'&'} to
			their appropriate XML entity representation.

			example
			{
				title{Emit text to XML}

				programlisting
				{:xml\{<?xml version="1.0" encoding="UTF-8"?>\}
				:xml\{<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
				"http://www.oasis-open.org/docbook/xml/4/2/docbookx.dtd">\}}
			}
		}

		li/p
		{
			For using umlauts, you may use lit{ISO-8859-1} encoding instead of
			lit{UTF-8}.  
		}

		li/p
		{
			In case of verbose element names, use alias files and use the
			lit{'/'} character to combine multiple element names.  
		}
	}
}

appendix
{
	title{Installation}

	p{
		cmd{xfront} is part of the si/ulink
		url="http://www.libsmart.com"{Libsmart} library. The cmd{xfront}
		project is located at the directory si{tools/xfront}.  To compile and
		install cmd{xfront} type userinput{make install} in that directory.
	}

	p{Here is a list of the files installed:}

	vlist
	{
		title{xfront installation files}

		ventry
		{
			term/file{xfront}
			li/p{Binary directory (usually si{/usr/local/bin})}
		}

		ventry
		{
			term/file{docbook.aliases}
			li/p{Data directory (usually si{/usr/local/share})}
		}

	}
}


appendix
{
	title{Required features for version 1.0}

	p{
		cmd{xfront} is not finished yet, following things are known to be
		required for version 1.0: 
	}

	ilist
	{
		li/p{

			Support of (verbatim?) text where the special characters
			lit{'\{'} and lit{'\}'} are common. Parts of C/C++/Java
			source code are an example. Suggestion: lit{'\{\{'} and
			lit{'\}\}'} scopes. 

			example
			{
				title{Verbatim text}

				p/lit{\{\{Herein one can write \{, \} without escaping them using \\. \}\}}
			}

		} 


		li/p 
		{
			Support for XML comments. Suggestion: lit{':\{'} scope.

			example
			{
				title{XML comments}

				p/lit{:\{This is an XML comment\}}
			}

		} 

		li/p {
			Required: cmd{vi} and cmd{emacs} syntax highlighting.
		}

		li/p
		{
			C/C++ style comments? Not sure about this. Currently they are
			supported but not part of the specification. Probably
			command{xfront} needs to support two styles of comments, one
			comment type only appearing in the source, the other emitted as XML
			comments.

		}

		li/p { Support for combined aliases (like lip=li/p for example) }

		li/p { Includes??? }


		li/p { Support entities for shared text. }
	}
}

appendix
{
	title{Known problems}

	ilist
	{
		li/p{
			Parsing of strings enclosed by lit{'"'} may confuse
			backtracking and users (inside strings lit{'\{'} and
			lit{'\}'} need not to be escaped), so lit{'"'} content
			parsing shall be avoided.
		}

		li/p
		{
			For some reason XML file line numbers differ from the line numbers
			of their original lit{.xf} files.  
		}
	}


}


appendix
{
	title{Revision history}

	ilist
	{
		li{
			p{2003 12 08 Version 0.3.3:}
		
			ilist/li/p{support for escaping lit{'/'} characters using the
			backslash lit{'\\'} character.}
		}

		li{
			p{2003 09 03 Version 0.3.2:}

			ilist/li/p{implemented dynamic whitespace indent detection and removal}
		}

		li{
			p{2003 09 02 Version 0.3.1:}

			ilist/li/p{fixed problem with detecting escaped parameter names}
		}

		li{ 
			p{2003 09 02 Version 0.3:}

			ilist{
				li/p{fixed problem with string parsing (was longest match instead of shortest).}
				li/p{implemented aliases}
				li/p{implemented element combiners}
				li/p{Included some DocBook examples}
			}
		}

		li/p{ 2003 08 29 Version 0.2: Initial release }
	}
}

appendix
{
	title{Docbook examples}

	ix/xp{examples}

	para{For the impatient ones wanting to write DocBook, here are some useful
	examples, inspired by the ulink
	url="http://opensource.bureau-cornavin.com/crash-course/"{Docbook Crash Course}.}

	note/p{You can read the original markup in filename{xfront.xf}.}

	example
	{
		title{Table}

		p/table{
			title{Example table}

			tgroup cols=3
			{
				thead{row{entry{Month}entry{Week}entry{Feet Traveled}}}
				tfoot{row{entry{Total}entry{0}entry{many}}}
				tbody
				{
					row{entry{10}entry{20}entry{30}}	
					row{entry{11}entry{23}entry{33}}	
					row{entry{12}entry{25}entry{32}}	
					row{entry{13}entry{27}entry{31}}	
				}
			}
		}

		p{Use command{informaltable} to create tables without titles}
	}

	example
	{
		title{Segmented list}

		segmentedlist
		{

			segtitle{Name}segtitle{Address}
			seglistitem
			{
				seg{Fred}
				seg{Fred's street}
			}
			seglistitem
			{
				seg{Bernd}
				seg{Bernd's street}
			}
			seglistitem
			{
				seg{Felix}
				seg{Felix's street}
			}
		}
	}

	example
	{
		title{Program listing}

		p/programlisting
		{10 PRINT "HELLO WORLD"
		20 GOTO 10}

		p/note/p
		{
			For PDF output, program listings must be aligned at column 1 in
			command{xfront} input documents.  
		}

	}

	example
	{
		title{Warnings, Tips and Notes}

		p{
			caution/p{Hot!}

			important/p{RTFM!}

			note/p{Big brother is watching you!}

			tip/p{Always take the red pill}

			warning/p{Low Battery}
		}
	}

	example
	{ 
		title{Links}
	
		p/ilist
		{
			li/p
			{
				External ulink url="http://www.replicator.org"{link}.
			}

			li/p
			{
				Link to a known lit{id} in the same document: see link linkend=Intro{Introduction}.
			}
		
			li/p
			{
				My email address: email{armin@replicator.org}
			}

		}
	}

	example
	{
		title{VarList}

		p/vlist
		{
			ventry{
				term{VarList Term A}

				li/p{
					Text for variable list entry 1.
				}
			}


			ventry{
				term{VarList Term B}
				li/p{
					Text for variable list entry 2.
				}
			}

			ventry{
				term{VarList Term C}
				li/p{
					Text for variable list entry 3.
				}
			}

		}
	}
}

index{}

} // article