#
#
# patch "monotone.texi"
#  from [766accbccb43835d476db4c637212d68abcd17fa]
#    to [08a79de6cdbe33b3c16e38ef005a34acef0408fa]
#
============================================================
--- monotone.texi	766accbccb43835d476db4c637212d68abcd17fa
+++ monotone.texi	08a79de6cdbe33b3c16e38ef005a34acef0408fa
@@ -6852,7 +6852,50 @@ @section Automation
 also give useful chatter on @code{stderr}, including warnings and error
 messages.
 
address@hidden @code{basic_io} Format
 
+Many commands produce output in a format called basic_io. At the most basic
+level this is a stream of three token types, separated by whitespace; a
address@hidden matches @code{/[a-z_]+/} (a word consisting of lowercase letters
+and underscores), a @code{string} matches @code{/"([^\\]|\\\\|\\")*"/} (a pair
+of double-quotes containing arbitrary characters, with only backslash and
+double-quote escaped with a backslash), and a @code{hex} matches
address@hidden/address@hidden@}\]/} (40 lowercase hex digits enclosed by square
+brackets; this will necessarily change in some manner when we eventually move
+to a stronger hash than sha1). Each @code{symbol} is followed by one or more
address@hidden and/or @code{hex}es.
+
+While the above is all that is strictly necessary to parse basic_io, there is
+some formatting of the stream which may be helpful when parsing and is required
+(but not always verified) when producing basic_io for consumption by monotone:
address@hidden
address@hidden
+Each @code{symbol} begins a new line.
address@hidden
+Tokens on the same line are separated by a single space.
address@hidden
+Lines are grouped into logical @code{stanza}s, separated by a single empty line.
+Each stanza then describes a particular item, with the different lines
+(@code{symbol}s followed by @code{string} and @code{hex} values) describing
+different aspects of that item.
address@hidden
address@hidden in a stanza are right-aligned with eachother; each @code{symbol}
+other than the longest is preceeded by spaces. The longest @code{symbol} in a
+stanza is not preceeded by spaces, even if there are longer @code{symbol}s in
+other stanzas.
address@hidden
+Lines and stanzas are generally required to be in a particular order. This is
+particularly important for objects such as for example revisions, where the
+logical structure is nested more deeply that the basic_io format can represent.
+In this case the logical structure is a list of changes vs. each parent
+revision, with each changed file being a separate stanza and header information
+for each parent and the revision as a whole also being separate stanzas;
+reordering the stanzas could cause a particular file change to be interpreted
+against the wrong parent.
address@hidden itemize
+
address@hidden Automation Commands
+
 @ftable @command
 @item mtn automate interface_version