/usr/share/doc/monotone/html/Formats.html is in monotone-doc 1.0-12.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>monotone documentation: Formats</title>
<meta name="description" content="monotone documentation: Formats">
<meta name="keywords" content="monotone documentation: Formats">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="General-Index.html#General-Index" rel="index" title="General Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index.html#Top" rel="up" title="Top">
<link href="Lua-Reference.html#Lua-Reference" rel="next" title="Lua Reference">
<link href="VCS.html#VCS" rel="prev" title="VCS">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="texinfo.css">
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Formats"></a>
<div class="header">
<p>
Next: <a href="Lua-Reference.html#Lua-Reference" accesskey="n" rel="next">Lua Reference</a>, Previous: <a href="Command-Reference.html#Command-Reference" accesskey="p" rel="prev">Command Reference</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="General-Index.html#General-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Formats-1"></a>
<h2 class="chapter">5 Formats</h2>
<p>Monotone uses three formats to output or to accept input of
data (mostly structured), <code>basic_io</code>, <code>stdio</code>, and <code>packet</code>.
<code>basic_io</code> is often used to represent data or for configuration,
while <code>stdio</code> is used for communication with <code>automate stdio</code>.
</p>
<p>The <code>stdio</code> format is not described here. For information on it,
see <code><a href="Automation.html#mtn-automate-stdio">mtn automate stdio</a></code>.
</p>
<p>The <code>packet</code> format is not described here; see <a href="Packet-I_002fO.html#Packet-I_002fO">Packet I/O</a>.
For examples, see <code><a href="Automation.html#mtn-automate-packet_005ffor_005ffdelta">mtn automate packet_for_fdelta</a></code>, <code><a href="Automation.html#mtn-automate-packet_005ffor_005ffdata">mtn automate packet_for_fdata</a></code>.
</p>
<a name="basic_005fio-Format"></a>
<h3 class="section">5.1 <code>basic_io</code> Format</h3>
<p><code>basic_io</code> is a very simple format, yet expressive, and can be
described with the following ABNF (see RFC 2234) specification:
</p>
<div class="display">
<pre class="verbatim">basic_io = *( item )
item = *sp symbol *sp *( string / hexid ) *sp
; a symbol followed by zero or more strings and/or hexes.
symbol = 1*( lcalpha / "_" )
; One or more letters or underscores.
string = DQUOTE *( charnqnb / "\" "\" / "\" DQUOTE ) DQUOTE
; A series of any character, enclosed with double quotes
; To include a double quote or a backslash in the string,
; escape it with a backslash.
hexid = "[" 40HEXDIG "]"
; 40 hexadecimal characters enclosed in brackets.
; Note: the amount might change as we move away from sha1.
sp = ( WSP CR LF )
charnqnb = %x01-21 / %x23-5B / %x5D-FF
; All characters except NUL (%x00) , " (%x22) and \ (%x5C).
lcalpha = %x61-7A
; Lower case a-z.
</pre></div>
<p>In essence, it’s a stream of items, where each item is a <code>symbol</code>
followed by zero or more <code>string</code>s and <code>hex</code>es.
</p>
<p>There is an idea of stanzas, which is a group of items that logically
belongs together. However, stanzas aren’t defined in the
<code>basic_io</code> syntax, and are instead defined in terms of order and
sequence for what symbols may be part of the stream, how they may
appear, and how many and what arguments should follow them. This is
defined by each command or program using this format.
</p>
<p>For example, revisions have associated data; the structure is header
stanzas followed by a list of changes vs. each parent revision, with
each change represented by a separate stanza; reordering the stanzas
could cause a particular change to be interpreted against the wrong
parent.
</p>
<p>Another example is the <samp>read-permissions</samp> file that’s read by the
default definition of the <a href="Netsync-Permission-Hooks.html#get_005fnetsync_005fread_005fpermitted">get_netsync_read_permitted</a> Lua hook.
</p>
<p>Monotone will format its output in <code>basic_io</code> as follows:
</p><ul>
<li> Each <code>symbol</code> begins a new line.
</li><li> Tokens on the same line are separated by a single space.
</li><li> Lines are grouped into logical <code>stanza</code>s, separated by a single empty line.
Each stanza then describes a particular item, with the different lines
(<code>symbol</code>s followed by <code>string</code> and <code>hex</code> values) describing
different aspects of that item.
</li><li> <code>symbol</code>s in a stanza are right-aligned with each other; each <code>symbol</code>
other than the longest is preceeded by spaces. The longest <code>symbol</code> in a
stanza is not preceeded by spaces, even if there are longer <code>symbol</code>s in
other stanzas.
</li><li> Lines within stanzas have a consistent order, although some may be
optional in some commands.
</li></ul>
<hr>
<div class="header">
<p>
Next: <a href="Lua-Reference.html#Lua-Reference" accesskey="n" rel="next">Lua Reference</a>, Previous: <a href="Command-Reference.html#Command-Reference" accesskey="p" rel="prev">Command Reference</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="General-Index.html#General-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|