Manual: Initial revision

diff --git a/INSTALL b/INSTALL
index 445e36b8e34561b5e91118a9a9f5a06d4f1abd92..833db389b636890ab1526d41bcd6f94081cd8bd1 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -25,6 +25,7 @@ Requirements
  - libsigrokcxx >= 0.6.0 (libsigrok C++ bindings)
  - libsigrokdecode >= 0.6.0
  - libsigrokandroidutils >= 0.1.0 (optional, only needed on Android)
+ - Asciidoctor (optional, only needed to build the manual)
 
 
 Building and installing
@@ -56,3 +57,22 @@ In order to build a source package begin with an unconfigured source tree.
  $ cmake ..
  $ make package_source
 
+
+Generating the manual
+---------------------
+
+To generate the HTML manual, you only need Asciidoctor. If you also want
+to generate the PDF manual, you need to install asciidoctor-pdf as well
+and make it available for execution:
+
+ $ gem install --pre asciidoctor-pdf
+ $ export PATH=~/.gem/ruby/2.3.0/bin:$PATH
+
+Then, to build the PulseView manual, run:
+
+ $ cd manual
+ $ ./generate
+
+Note: The stylesheet used is a lightly modified version of "Read The Docs"
+from the Asciidoctor stylesheet factory:
+https://asciidoctor.org/docs/user-manual/#stylesheet-factory

diff --git a/manual/acquisition.txt b/manual/acquisition.txt
new file mode 100644 (file)
index 0000000..05d2c84
--- /dev/null
+++ b/manual/acquisition.txt
@@ -0,0 +1,120 @@
+== Data Acquisition
+
+Working with PulseView follows a pattern:
+
+image::pv_nodevice.png[]
+<1> Open a new session
+<2> Select the device you want to work with:
+<3> Click "Run" to acquire signal data (waiting for a trigger first if you set one)
+
+When you start PulseView and no sessions are restored from the last time you used it, it will
+come up with a session that has the demo device selected. That way, you can get to know the
+program even when you don't have any hardware to use it with.
+
+=== Device Selection
+
+The device selector offers two methods to choose the device to use. If you click on the small
+arrow on the side, you see a list of devices PulseView has recognized. If the device you want
+to use it listed, you can just select it here to use it.
+
+image::device_selector_dropdown.png[]
+
+If it's not listed, you'll need to scan for it first. Since most serial port and Ethernet
+devices can't be auto-detected, this is usually required for those.
+To do so, either choose the "Connect to Device" option from the list or click on the button
+itself. You will see the following dialog:
+
+image::device_selector_scan.png[]
+
+First, you'll need to pick a driver that you want to use. In order to do this, you'll need
+to know which driver is used to talk to the device. If you're unsure, you can either try the
+driver which you think may fit best or you can check the wiki. For every supported device there's
+a wiki page, showing you which driver is used.
+
+Once the driver has been chosen, you need to select the interface. Please be aware that USB
+is only usable for devices that directly communicate over USB. Devices that use USB to emulate
+a serial port (like the OpenBench Logic Sniffer) will have their serial port listed in the
+serial port drop-down.
+
+In case your device connects via Ethernet, you must supply the IP address and port. You are
+also given the option to choose between raw TCP access and using the VXI protocol. VXI is an
+industry standard which is mainly used in professional equipment and the device will most
+likely let you know that it supports VXI. If your device however is more of a hobbyist grade
+device, it's more likely that using raw TCP will be the correct choice.
+
+After you selected the appropriate options, clicking the scan button will make PulseView try
+to connect to the device with the given settings. If successful, any device(s) found will be
+shown in the list box.
+
+[NOTE]
+When a session uses a USB device and you close Pulseview, a session with that same device
+is re-opened when you start Pulseview again. Currently, this is however not the case for non-USB
+devices, such as ones that connect via serial port or Ethernet.
+
+[NOTE]
+To avoid having to manually enter the device configuration for a serial port or Ethernet
+device every time you want to use it and then having to scan for it, you can also use the
+command line parameter -d to have PulseView scan for it on startup.
+
+=== Device Configuration
+
+In PulseView, the device configuration is done using these buttons:
+
+image::pv_device_config.png[]
+<1> Device-specific settings
+<2> Channel-specific settings
+<3> Number of samples to capture
+<4> Sample rate at which to capture the samples
+<5> Per-channel trigger setting (see below)
+
+The values offered for those four elements depend on your device. Which settings you should choose
+depends on several factors: the needs of your measurement, the device you use to capture the data
+and the capabilities of your computer.
+
+The sample rate you choose must at least be twice that of the highest frequency you want to
+capture - ideally 3 to 5 times as much so that you have some margin. That way, a jittering signal
+won't ruin your measurements.
+
+[NOTE]
+If you're using a device with a Cypress FX2 (most 8 channel / 24 MHz logic analyzers do) then you should
+be aware that the 24 MHz sampling rate (12 MHz for 16 channels) can only be sustained under perfect
+conditions. Usually, those devices are shipped with low-quality USB cables, impairing USB transfers as
+USB traffic increases. Therefore, you can try a different USB cable if you're facing issues at higher
+sample rates. If they persist, it's worth trying a different USB port as well.
+
+=== Triggers
+
+The signal labels on the left side of the view (D0, D1 and so on in the picture above) allow you to
+configure certain aspects of these signals. If the device supports it then the trigger that will be
+used for this signal will be among them.
+
+As of now, the trigger system is awaiting extension for advanced and complex trigger types, meaning
+that the only triggers available to you are:
+
+* Trigger when the signal has a "low" level
+* Trigger when the signal has a "high" level
+* Trigger when the signal switches from "low" to "high" level (rising edge)
+* Trigger when the signal switches from "hig" to "low" level (falling edge)
+* Trigger when the signal changes level in any way (any edge)
+
+Once you choose a trigger, the icon for the type you chose becomes visible on the right side of the
+trace view.
+
+When you click "Run" with a trigger configured, PulseView will wait for the device to trigger and
+send data before it can show anything. There is currently no frame limit, so if the device driver
+supports it, PulseView will continue arming the trigger and collecting data until you either click
+"Stop" or it runs out of memory.
+
+=== Channel Groups
+
+Some devices share certain settings between a group of channels, which is why PulseView may show
+the channels your device offers in groups. You can see which channels are grouped by looking at the
+dark gray bar on the left. If there is none, no channels are grouped.
+
+Currently, the grouping is only done for your convenience and there's no direct functional impact.
+This means that you're free to ungroup and group channels as you please. To do so, right-click
+on the dark gray bar and select "Ungroup".
+If you want to create a new group, select the signals you want to group by holding down CTRL
+and clicking on the signal labels. Once you have selected the ones you want to be grouped,
+right-click on one of the labels you selected and choose "Group".
+

diff --git a/manual/analysis.txt b/manual/analysis.txt
new file mode 100644 (file)
index 0000000..f9886ae
--- /dev/null
+++ b/manual/analysis.txt
@@ -0,0 +1,68 @@
+== Data Analysis
+
+Once you have acquired some measurement data, it's time to have a look and see what
+insights you can gain from it. Usually, the first step is to look at the data as a
+whole, achieved by clicking the _Zoom to Fit_ button:
+
+image::pv_analysis.png[]
+
+<1> Zoom-to-Fit button
+<2> Zoom in/zoom out buttons
+<3> Cursors
+<4> Time scale (used to set up and show time markers, see below)
+
+If you have located an area of interest (maybe with the help of decoders, more about
+that later), you can zoom in on it using the _zoom in_/_zoom out_ buttons, using the
+scroll wheel of your mouse or the pinch/expand gestures on your touch panel.
+
+[NOTE]
+When a data capture is ongoing, the Zoom-to-Fit button stays active if you click it,
+meaning that PulseView automatically fits all data to the views until either the
+capture is finished or the Zoom-to-Fit button is clicked again.
+
+=== Cursors and Time Markers
+
+Just looking at the signal data however is usually not sufficient. A lot of times,
+you'll want to make sure that timings are honored and the bit times are like what
+you'd expect. To do so, you'll want to use cursors and time markers.
+
+In the picture above, you can enable the cursor by clicking on the cursor button.
+You can move both of its boundaries around by clicking on the blue flags in the
+time scale area. The area between the two boundary lines shows the time distance
+and its inverse (i.e. the frequency). If you can't see it, just zoom in until it
+shows. You can also move both boundaries at the same time by dragging the label
+where this information is shown.
+
+image::pv_cursors_markers.png[]
+
+<1> Cursors button, showing enabled state
+<2> Cursor
+<3> Time Marker
+
+Time markers are static markers that you can create wherever you like on the
+time scale - just double-click on it and it'll create one for you where your
+mouse cursor is at the time. You can click on its label and you'll have the
+option to change its name.
+
+[NOTE]
+For timing comparison purposes, you can also enable a vertical marker line that
+follows your mouse cursor: _Settings_ -> _Views_ -> _Highlight mouse cursor_
+
+[NOTE]
+There is also a special kind of time marker that appears for each time the data
+acquisition device has triggered. It cannot be moved and appears as a vertical
+dashed line.
+
+=== Special-Purpose Decoders
+
+There are some decoders available that analyze the data instead of decoding it.
+You can make use of them to examine various properties of the signals that are
+of interest to you.
+
+Their names are:
+
+* Counter - counts pulses and/or groups of pulses (i.e. words)
+* Guess bitrate - guesses the bitrate when using a serial protocol
+* Jitter - determines the jitter (variance) of a signal
+* Timing - shows the time passing between the chosen signal edges
+

diff --git a/manual/asciidoctor-stylesheet-factory/LICENSE b/manual/asciidoctor-stylesheet-factory/LICENSE
new file mode 100644 (file)
index 0000000..5f4d18e
--- /dev/null
+++ b/manual/asciidoctor-stylesheet-factory/LICENSE
@@ -0,0 +1,45 @@
+Asciidoctor styles
+------------------
+
+Copyright (c) 2013 Dan Allen
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+Other licensed work
+-------------------
+
+- Foundation 4 by Zurb, on which the themes are built, is licensed under the
+  Apache License, v2.0:
+
+  http://apache.org/licenses/LICENSE-2.0
+  http://foundation.zurb.com
+
+- The riak theme is derived from the Riak documentation theme by Basho,
+  licensed under the Creative Commons Attribution 3.0 Unported License:
+
+  http://creativecommons.org/licenses/by/3.0/us
+  http://docs.basho.org
+
+- The iconic theme is inspired by O'Reilly typography and Atlas manual.
+
+  http://oreilly.com

diff --git a/manual/asciidoctor-stylesheet-factory/stylesheets/readthedocs.css b/manual/asciidoctor-stylesheet-factory/stylesheets/readthedocs.css
new file mode 100644 (file)
index 0000000..7adc8d1
--- /dev/null
+++ b/manual/asciidoctor-stylesheet-factory/stylesheets/readthedocs.css
@@ -0,0 +1,727 @@
+/*! normalize.css v2.1.2 | MIT License | git.io/normalize */
+/* ========================================================================== HTML5 display definitions ========================================================================== */
+/** Correct `block` display not defined in IE 8/9. */
+article, aside, details, figcaption, figure, footer, header, hgroup, main, nav, section, summary { display: block; }
+
+/** Correct `inline-block` display not defined in IE 8/9. */
+audio, canvas, video { display: inline-block; }
+
+/** Prevent modern browsers from displaying `audio` without controls. Remove excess height in iOS 5 devices. */
+audio:not([controls]) { display: none; height: 0; }
+
+/** Address `[hidden]` styling not present in IE 8/9. Hide the `template` element in IE, Safari, and Firefox < 22. */
+[hidden], template { display: none; }
+
+script { display: none !important; }
+
+/* ========================================================================== Base ========================================================================== */
+/** 1. Set default font family to sans-serif. 2. Prevent iOS text size adjust after orientation change, without disabling user zoom. */
+html { font-family: sans-serif; /* 1 */ -ms-text-size-adjust: 100%; /* 2 */ -webkit-text-size-adjust: 100%; /* 2 */ }
+
+/** Remove default margin. */
+body { margin: 0; }
+
+/* ========================================================================== Links ========================================================================== */
+/** Remove the gray background color from active links in IE 10. */
+a { background: transparent; }
+
+/** Address `outline` inconsistency between Chrome and other browsers. */
+a:focus { outline: thin dotted; }
+
+/** Improve readability when focused and also mouse hovered in all browsers. */
+a:active, a:hover { outline: 0; }
+
+/* ========================================================================== Typography ========================================================================== */
+/** Address variable `h1` font-size and margin within `section` and `article` contexts in Firefox 4+, Safari 5, and Chrome. */
+h1 { font-size: 2em; margin: 0.67em 0; }
+
+/** Address styling not present in IE 8/9, Safari 5, and Chrome. */
+abbr[title] { border-bottom: 1px dotted; }
+
+/** Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome. */
+b, strong { font-weight: bold; }
+
+/** Address styling not present in Safari 5 and Chrome. */
+dfn { font-style: italic; }
+
+/** Address differences between Firefox and other browsers. */
+hr { -moz-box-sizing: content-box; box-sizing: content-box; height: 0; }
+
+/** Address styling not present in IE 8/9. */
+mark { background: #ff0; color: #000; }
+
+/** Correct font family set oddly in Safari 5 and Chrome. */
+code, kbd, pre, samp { font-family: monospace, serif; font-size: 1em; }
+
+/** Improve readability of pre-formatted text in all browsers. */
+pre { white-space: pre-wrap; }
+
+/** Set consistent quote types. */
+q { quotes: "\201C" "\201D" "\2018" "\2019"; }
+
+/** Address inconsistent and variable font size in all browsers. */
+small { font-size: 80%; }
+
+/** Prevent `sub` and `sup` affecting `line-height` in all browsers. */
+sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }
+
+sup { top: -0.5em; }
+
+sub { bottom: -0.25em; }
+
+/* ========================================================================== Embedded content ========================================================================== */
+/** Remove border when inside `a` element in IE 8/9. */
+img { border: 0; }
+
+/** Correct overflow displayed oddly in IE 9. */
+svg:not(:root) { overflow: hidden; }
+
+/* ========================================================================== Figures ========================================================================== */
+/** Address margin not present in IE 8/9 and Safari 5. */
+figure { margin: 0; }
+
+/* ========================================================================== Forms ========================================================================== */
+/** Define consistent border, margin, and padding. */
+fieldset { border: 1px solid #c0c0c0; margin: 0 2px; padding: 0.35em 0.625em 0.75em; }
+
+/** 1. Correct `color` not being inherited in IE 8/9. 2. Remove padding so people aren't caught out if they zero out fieldsets. */
+legend { border: 0; /* 1 */ padding: 0; /* 2 */ }
+
+/** 1. Correct font family not being inherited in all browsers. 2. Correct font size not being inherited in all browsers. 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome. */
+button, input, select, textarea { font-family: inherit; /* 1 */ font-size: 100%; /* 2 */ margin: 0; /* 3 */ }
+
+/** Address Firefox 4+ setting `line-height` on `input` using `!important` in the UA stylesheet. */
+button, input { line-height: normal; }
+
+/** Address inconsistent `text-transform` inheritance for `button` and `select`. All other form control elements do not inherit `text-transform` values. Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+. Correct `select` style inheritance in Firefox 4+ and Opera. */
+button, select { text-transform: none; }
+
+/** 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` and `video` controls. 2. Correct inability to style clickable `input` types in iOS. 3. Improve usability and consistency of cursor style between image-type `input` and others. */
+button, html input[type="button"], input[type="reset"], input[type="submit"] { -webkit-appearance: button; /* 2 */ cursor: pointer; /* 3 */ }
+
+/** Re-set default cursor for disabled elements. */
+button[disabled], html input[disabled] { cursor: default; }
+
+/** 1. Address box sizing set to `content-box` in IE 8/9. 2. Remove excess padding in IE 8/9. */
+input[type="checkbox"], input[type="radio"] { box-sizing: border-box; /* 1 */ padding: 0; /* 2 */ }
+
+/** 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome. 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome (include `-moz` to future-proof). */
+input[type="search"] { -webkit-appearance: textfield; /* 1 */ -moz-box-sizing: content-box; -webkit-box-sizing: content-box; /* 2 */ box-sizing: content-box; }
+
+/** Remove inner padding and search cancel button in Safari 5 and Chrome on OS X. */
+input[type="search"]::-webkit-search-cancel-button, input[type="search"]::-webkit-search-decoration { -webkit-appearance: none; }
+
+/** Remove inner padding and border in Firefox 4+. */
+button::-moz-focus-inner, input::-moz-focus-inner { border: 0; padding: 0; }
+
+/** 1. Remove default vertical scrollbar in IE 8/9. 2. Improve readability and alignment in all browsers. */
+textarea { overflow: auto; /* 1 */ vertical-align: top; /* 2 */ }
+
+/* ========================================================================== Tables ========================================================================== */
+/** Remove most spacing between table cells. */
+table { border-collapse: collapse; border-spacing: 0; }
+
+meta.foundation-mq-small { font-family: "only screen and (min-width: 768px)"; width: 768px; }
+
+meta.foundation-mq-medium { font-family: "only screen and (min-width:1280px)"; width: 1280px; }
+
+meta.foundation-mq-large { font-family: "only screen and (min-width:1440px)"; width: 1440px; }
+
+*, *:before, *:after { -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box; }
+
+html, body { font-size: 100%; }
+
+body { background: #fff; color: #222; padding: 0; margin: 0; font-family: "Helvetica Neue", "Helvetica", Helvetica, Arial, sans-serif; font-weight: normal; font-style: normal; line-height: 1; position: relative; cursor: auto; }
+
+a:hover { cursor: pointer; }
+
+img, object, embed { max-width: 100%; height: auto; }
+
+object, embed { height: 100%; }
+
+img { -ms-interpolation-mode: bicubic; }
+
+#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; }
+
+.left { float: left !important; }
+
+.right { float: right !important; }
+
+.text-left { text-align: left !important; }
+
+.text-right { text-align: right !important; }
+
+.text-center { text-align: center !important; }
+
+.text-justify { text-align: justify !important; }
+
+.hide { display: none; }
+
+.antialiased { -webkit-font-smoothing: antialiased; }
+
+img { display: inline-block; vertical-align: middle; }
+
+textarea { height: auto; min-height: 50px; }
+
+select { width: 100%; }
+
+object, svg { display: inline-block; vertical-align: middle; }
+
+.center { margin-left: auto; margin-right: auto; }
+
+.stretch { width: 100%; }
+
+p.lead { font-size: 1.21875em; line-height: 1.6; }
+
+.subheader, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { line-height: 1.4; color: #6c818f; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; }
+
+/* Typography resets */
+div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { margin: 0; padding: 0; direction: ltr; }
+
+/* Default Link Styles */
+a { color: #444; text-decoration: underline; line-height: inherit; }
+a:hover, a:focus { color: #111; }
+a img { border: none; }
+
+/* Default paragraph styles */
+p { font-family: inherit; font-weight: normal; font-size: 1em; line-height: 1.5; margin-bottom: 1.25em; text-rendering: optimizeLegibility; }
+p aside { font-size: 0.875em; line-height: 1.35; font-style: italic; }
+
+/* Default header styles */
+h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: ff-meta-web-pro-1, ff-meta-web-pro-2, Arial, "Helvetica Neue", sans-serif; font-weight: bold; font-style: normal; color: #465158; text-rendering: optimizeLegibility; margin-top: 1em; margin-bottom: 0.5em; line-height: 1.2125em; }
+h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { font-size: 60%; color: #909ea7; line-height: 0; }
+
+h1 { font-size: 2.125em; }
+
+h2 { font-size: 1.6875em; }
+
+h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.375em; }
+
+h4 { font-size: 1.125em; }
+
+h5 { font-size: 1.125em; }
+
+h6 { font-size: 1em; }
+
+hr { border: solid #ddd; border-width: 1px 0 0; clear: both; margin: 1.25em 0 1.1875em; height: 0; }
+
+/* Helpful Typography Defaults */
+em, i { font-style: italic; line-height: inherit; }
+
+strong, b { font-weight: bold; line-height: inherit; }
+
+small { font-size: 60%; line-height: inherit; }
+
+code { font-family: "Consolas", "Deja Vu Sans Mono", "Bitstream Vera Sans Mono", monospace; font-weight: normal; color: #444; }
+
+/* Lists */
+ul, ol, dl { font-size: 1em; line-height: 1.5; margin-bottom: 1.25em; list-style-position: outside; font-family: inherit; }
+
+ul, ol { margin-left: 0; }
+ul.no-bullet, ol.no-bullet { margin-left: 0; }
+
+/* Unordered Lists */
+ul li ul, ul li ol { margin-left: 1.25em; margin-bottom: 0; font-size: 1em; /* Override nested font-size change */ }
+ul.square li ul, ul.circle li ul, ul.disc li ul { list-style: inherit; }
+ul.square { list-style-type: square; }
+ul.circle { list-style-type: circle; }
+ul.disc { list-style-type: disc; }
+ul.no-bullet { list-style: none; }
+
+/* Ordered Lists */
+ol li ul, ol li ol { margin-left: 1.25em; margin-bottom: 0; }
+
+/* Definition Lists */
+dl dt { margin-bottom: 0.3em; font-weight: bold; }
+dl dd { margin-bottom: 0.75em; }
+
+/* Abbreviations */
+abbr, acronym { text-transform: uppercase; font-size: 90%; color: #000; border-bottom: 1px dotted #ddd; cursor: help; }
+
+abbr { text-transform: none; }
+
+/* Blockquotes */
+blockquote { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #ddd; }
+blockquote cite { display: block; font-size: 0.8125em; color: #748590; }
+blockquote cite:before { content: "\2014 \0020"; }
+blockquote cite a, blockquote cite a:visited { color: #748590; }
+
+blockquote, blockquote p { line-height: 1.5; color: #909ea7; }
+
+/* Microformats */
+.vcard { display: inline-block; margin: 0 0 1.25em 0; border: 1px solid #ddd; padding: 0.625em 0.75em; }
+.vcard li { margin: 0; display: block; }
+.vcard .fn { font-weight: bold; font-size: 0.9375em; }
+
+.vevent .summary { font-weight: bold; }
+.vevent abbr { cursor: auto; text-decoration: none; font-weight: bold; border: none; padding: 0 0.0625em; }
+
+@media only screen and (min-width: 768px) { h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; }
+  h1 { font-size: 2.75em; }
+  h2 { font-size: 2.3125em; }
+  h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; }
+  h4 { font-size: 1.4375em; } }
+/* Tables */
+table { background: #fff; margin-bottom: 1.25em; border: solid 0 #ddd; }
+table thead, table tfoot { background: none; font-weight: bold; }
+table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 1px 8px 1px 5px; font-size: 1em; color: #222; text-align: left; }
+table tr th, table tr td { padding: 1px 8px 1px 5px; font-size: 1em; color: #222; }
+table tr.even, table tr.alt, table tr:nth-of-type(even) { background: none; }
+table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.5; }
+
+body { -moz-osx-font-smoothing: grayscale; -webkit-font-smoothing: antialiased; tab-size: 4; }
+
+h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; }
+
+.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; }
+.clearfix:after, .float-group:after { clear: both; }
+
+*:not(pre) > code { font-size: 0.95em; font-style: normal !important; letter-spacing: 0; padding: 0; background-color: #f2f2f2; -webkit-border-radius: 6px; border-radius: 6px; line-height: inherit; word-wrap: break-word; }
+*:not(pre) > code.nobreak { word-wrap: normal; }
+*:not(pre) > code.nowrap { white-space: nowrap; }
+
+pre, pre > code { line-height: 1.2; color: inherit; font-family: "Consolas", "Deja Vu Sans Mono", "Bitstream Vera Sans Mono", monospace; font-weight: normal; }
+
+em em { font-style: normal; }
+
+strong strong { font-weight: normal; }
+
+.keyseq { color: #333333; }
+
+kbd { font-family: "Consolas", "Deja Vu Sans Mono", "Bitstream Vera Sans Mono", monospace; display: inline-block; color: #000; font-size: 0.65em; line-height: 1.45; background-color: #f7f7f7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -moz-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; margin: 0 0.15em; padding: 0.2em 0.5em; vertical-align: middle; position: relative; top: -0.1em; white-space: nowrap; }
+
+.keyseq kbd:first-child { margin-left: 0; }
+
+.keyseq kbd:last-child { margin-right: 0; }
+
+.menuseq, .menuref { color: #000; }
+
+.menuseq b:not(.caret), .menuref { font-weight: inherit; }
+
+.menuseq { word-spacing: -0.02em; }
+.menuseq b.caret { font-size: 1.25em; line-height: 0.8; }
+.menuseq i.caret { font-weight: bold; text-align: center; width: 0.45em; }
+
+b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; }
+
+b.button:before { content: "["; padding: 0 3px 0 2px; }
+
+b.button:after { content: "]"; padding: 0 2px 0 3px; }
+
+p a > code:hover { color: #373737; }
+
+#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 0.9375em; padding-right: 0.9375em; }
+#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; }
+#header:after, #content:after, #footnotes:after, #footer:after { clear: both; }
+
+#content { margin-top: 1.25em; }
+
+#content:before { content: none; }
+
+#header > h1:first-child { color: #111; margin-top: 2.25rem; margin-bottom: 0; }
+#header > h1:first-child + #toc { margin-top: 8px; border-top: 1px solid #ddd; }
+#header > h1:only-child, body.toc2 #header > h1:nth-last-child(2) { border-bottom: 1px solid #ddd; padding-bottom: 8px; }
+#header .details { border-bottom: 1px solid #ddd; line-height: 1.45; padding-top: 0.25em; padding-bottom: 0.25em; padding-left: 0.25em; color: #748590; display: -ms-flexbox; display: -webkit-flex; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; }
+#header .details span:first-child { margin-left: -0.125em; }
+#header .details span.email a { color: #909ea7; }
+#header .details br { display: none; }
+#header .details br + span:before { content: "\00a0\2013\00a0"; }
+#header .details br + span.author:before { content: "\00a0\22c5\00a0"; color: #909ea7; }
+#header .details br + span#revremark:before { content: "\00a0|\00a0"; }
+#header #revnumber { text-transform: capitalize; }
+#header #revnumber:after { content: "\00a0"; }
+
+#content > h1:first-child:not([class]) { color: #111; border-bottom: 1px solid #ddd; padding-bottom: 8px; margin-top: 0; padding-top: 1rem; margin-bottom: 1.25rem; }
+
+#toc { border-bottom: 1px solid #ddd; padding-bottom: 0.5em; }
+#toc > ul { margin-left: 0.125em; }
+#toc ul.sectlevel0 > li > a { font-style: italic; }
+#toc ul.sectlevel0 ul.sectlevel1 { margin: 0.5em 0; }
+#toc ul { font-family: ff-meta-web-pro-1, ff-meta-web-pro-2, Arial, "Helvetica Neue", sans-serif; list-style-type: none; }
+#toc li { line-height: 1.3334; margin-top: 0.3334em; }
+#toc a { text-decoration: none; }
+#toc a:active { text-decoration: underline; }
+
+#toctitle { color: #6c818f; font-size: 1.2em; }
+
+@media only screen and (min-width: 768px) { #toctitle { font-size: 1.375em; }
+  body.toc2 { padding-left: 15em; padding-right: 0; }
+  #toc.toc2 { margin-top: 0 !important; background-color: #f2f2f2; position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #ddd; border-top-width: 0 !important; border-bottom-width: 0 !important; z-index: 1000; padding: 1.25em 1em; height: 100%; overflow: auto; }
+  #toc.toc2 #toctitle { margin-top: 0; margin-bottom: 0.8rem; font-size: 1.2em; }
+  #toc.toc2 > ul { font-size: 0.9em; margin-bottom: 0; }
+  #toc.toc2 ul ul { margin-left: 0; padding-left: 1em; }
+  #toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; }
+  body.toc2.toc-right { padding-left: 0; padding-right: 15em; }
+  body.toc2.toc-right #toc.toc2 { border-right-width: 0; border-left: 1px solid #ddd; left: auto; right: 0; } }
+@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; }
+  #toc.toc2 { width: 20em; }
+  #toc.toc2 #toctitle { font-size: 1.375em; }
+  #toc.toc2 > ul { font-size: 0.95em; }
+  #toc.toc2 ul ul { padding-left: 1.25em; }
+  body.toc2.toc-right { padding-left: 0; padding-right: 20em; } }
+#content #toc { border-style: solid; border-width: 1px; border-color: #d9d9d9; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f2; -webkit-border-radius: 6px; border-radius: 6px; }
+#content #toc > :first-child { margin-top: 0; }
+#content #toc > :last-child { margin-bottom: 0; }
+
+#footer { max-width: 100%; background-color: #000; padding: 1.25em; }
+
+#footer-text { color: white; line-height: 1.35; }
+
+#content { margin-bottom: 0.625em; }
+
+.sect1 { padding-bottom: 0.625em; }
+
+@media only screen and (min-width: 768px) { #content { margin-bottom: 1.25em; }
+  .sect1 { padding-bottom: 1.25em; } }
+.sect1:last-child { padding-bottom: 0; }
+
+.sect1 + .sect1 { border-top: 1px solid #ddd; }
+
+#content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { position: absolute; z-index: 1001; width: 1.5ex; margin-left: -1.5ex; display: block; text-decoration: none !important; visibility: hidden; text-align: center; font-weight: normal; }
+#content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { content: "\00A7"; font-size: 0.85em; display: block; padding-top: 0.1em; }
+#content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { visibility: visible; }
+#content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { color: #465158; text-decoration: none; }
+#content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { color: #3b444a; }
+
+.audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .videoblock { margin-bottom: 1.25em; }
+
+.admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-rendering: optimizeLegibility; text-align: left; }
+
+table.tableblock.fit-content > caption.title { white-space: nowrap; width: 0; }
+
+.paragraph.lead > p, #preamble > .sectionbody > [class="paragraph"]:first-of-type p { font-size: 1.21875em; line-height: 1.6; color: #111; }
+
+table.tableblock #preamble > .sectionbody > [class="paragraph"]:first-of-type p { font-size: inherit; }
+
+.admonitionblock > table { border-collapse: separate; border: 0; background: none; width: 100%; }
+.admonitionblock > table td.icon { text-align: center; width: 80px; }
+.admonitionblock > table td.icon img { max-width: none; }
+.admonitionblock > table td.icon .title { font-weight: bold; font-family: ff-meta-web-pro-1, ff-meta-web-pro-2, Arial, "Helvetica Neue", sans-serif; text-transform: uppercase; }
+.admonitionblock > table td.content { padding-left: 1.125em; padding-right: 1.25em; border-left: 1px solid #ddd; color: #748590; }
+.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; }
+
+.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: #fff; -webkit-border-radius: 6px; border-radius: 6px; }
+.exampleblock > .content > :first-child { margin-top: 0; }
+.exampleblock > .content > :last-child { margin-bottom: 0; }
+
+.sidebarblock { border-style: solid; border-width: 1px; border-color: #d9d9d9; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f2; -webkit-border-radius: 6px; border-radius: 6px; }
+.sidebarblock > :first-child { margin-top: 0; }
+.sidebarblock > :last-child { margin-bottom: 0; }
+.sidebarblock > .content > .title { color: #6c818f; margin-top: 0; }
+
+.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; }
+
+.literalblock pre, .listingblock pre:not(.highlight), .listingblock pre[class="highlight"], .listingblock pre[class^="highlight "], .listingblock pre.CodeRay, .listingblock pre.prettyprint { background: #eee; }
+.sidebarblock .literalblock pre, .sidebarblock .listingblock pre:not(.highlight), .sidebarblock .listingblock pre[class="highlight"], .sidebarblock .listingblock pre[class^="highlight "], .sidebarblock .listingblock pre.CodeRay, .sidebarblock .listingblock pre.prettyprint { background: #f2f1f1; }
+
+.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { border: 1px solid #ccc; -webkit-border-radius: 6px; border-radius: 6px; word-wrap: break-word; padding: 0.5em; font-size: 0.8125em; }
+.literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { overflow-x: auto; white-space: pre; word-wrap: normal; }
+@media only screen and (min-width: 768px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 0.90625em; } }
+@media only screen and (min-width: 1280px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 1em; } }
+
+.literalblock.output pre { color: #eee; background-color: inherit; }
+
+.listingblock pre.highlightjs { padding: 0; }
+.listingblock pre.highlightjs > code { padding: 0.5em; -webkit-border-radius: 6px; border-radius: 6px; }
+
+.listingblock > .content { position: relative; }
+
+.listingblock code[data-lang]:before { display: none; content: attr(data-lang); position: absolute; font-size: 0.75em; top: 0.425rem; right: 0.5rem; line-height: 1; text-transform: uppercase; color: #999; }
+
+.listingblock:hover code[data-lang]:before { display: block; }
+
+.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: #999; }
+
+.listingblock.terminal pre .command:not([data-prompt]):before { content: "$"; }
+
+table.pyhltable { border-collapse: separate; border: 0; margin-bottom: 0; background: none; }
+
+table.pyhltable td { vertical-align: top; padding-top: 0; padding-bottom: 0; line-height: 1.2; }
+
+table.pyhltable td.code { padding-left: .75em; padding-right: 0; }
+
+pre.pygments .lineno, table.pyhltable td:not(.code) { color: #999; padding-left: 0; padding-right: .5em; border-right: 1px solid #ddd; }
+
+pre.pygments .lineno { display: inline-block; margin-right: .25em; }
+
+table.pyhltable .linenodiv { background: none !important; padding-right: 0 !important; }
+
+.quoteblock { margin: 0 1em 1.25em 1.5em; display: table; }
+.quoteblock > .title { margin-left: -1.5em; margin-bottom: 0.75em; }
+.quoteblock blockquote, .quoteblock blockquote p { color: #909ea7; font-size: 1.15rem; line-height: 1.75; word-spacing: 0.1em; letter-spacing: 0; font-style: italic; text-align: justify; }
+.quoteblock blockquote { margin: 0; padding: 0; border: 0; }
+.quoteblock blockquote:before { content: "\201c"; float: left; font-size: 2.75em; font-weight: bold; line-height: 0.6em; margin-left: -0.6em; color: #6c818f; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); }
+.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; }
+.quoteblock .attribution { margin-top: 0.5em; margin-right: 0.5ex; text-align: right; }
+.quoteblock .quoteblock { margin-left: 0; margin-right: 0; padding: 0.5em 0; border-left: 3px solid #748590; }
+.quoteblock .quoteblock blockquote { padding: 0 0 0 0.75em; }
+.quoteblock .quoteblock blockquote:before { display: none; }
+
+.verseblock { margin: 0 1em 1.25em 1em; }
+.verseblock pre { font-family: "Open Sans", "DejaVu Sans", sans; font-size: 1.15rem; color: #909ea7; font-weight: 300; text-rendering: optimizeLegibility; }
+.verseblock pre strong { font-weight: 400; }
+.verseblock .attribution { margin-top: 1.25rem; margin-left: 0.5ex; }
+
+.quoteblock .attribution, .verseblock .attribution { font-size: 0.8125em; line-height: 1.45; font-style: italic; }
+.quoteblock .attribution br, .verseblock .attribution br { display: none; }
+.quoteblock .attribution cite, .verseblock .attribution cite { display: block; letter-spacing: -0.025em; color: #748590; }
+
+.quoteblock.abstract { margin: 0 1em 1.25em 1em; display: block; }
+.quoteblock.abstract > .title { margin: 0 0 0.375em 0; font-size: 1.15em; text-align: center; }
+.quoteblock.abstract blockquote, .quoteblock.abstract blockquote p { word-spacing: 0; line-height: 1.6; }
+.quoteblock.abstract blockquote:before, .quoteblock.abstract p:before { display: none; }
+
+table.tableblock { max-width: 100%; border-collapse: separate; }
+
+p.tableblock:last-child { margin-bottom: 0; }
+
+td.tableblock > .content { margin-bottom: -1.25em; }
+
+table.tableblock, th.tableblock, td.tableblock { border: 0 solid #ddd; }
+
+table.grid-all > thead > tr > .tableblock, table.grid-all > tbody > tr > .tableblock { border-width: 0 0 0 0; }
+
+table.grid-all > tfoot > tr > .tableblock { border-width: 0 0 0 0; }
+
+table.grid-cols > * > tr > .tableblock { border-width: 0 0 0 0; }
+
+table.grid-rows > thead > tr > .tableblock, table.grid-rows > tbody > tr > .tableblock { border-width: 0 0 0 0; }
+
+table.grid-rows > tfoot > tr > .tableblock { border-width: 0 0 0 0; }
+
+table.grid-all > * > tr > .tableblock:last-child, table.grid-cols > * > tr > .tableblock:last-child { border-right-width: 0; }
+
+table.grid-all > tbody > tr:last-child > .tableblock, table.grid-all > thead:last-child > tr > .tableblock, table.grid-rows > tbody > tr:last-child > .tableblock, table.grid-rows > thead:last-child > tr > .tableblock { border-bottom-width: 0; }
+
+table.frame-all { border-width: 0; }
+
+table.frame-sides { border-width: 0 0; }
+
+table.frame-topbot, table.frame-ends { border-width: 0 0; }
+
+table.stripes-all tr, table.stripes-odd tr:nth-of-type(odd) { background: none; }
+
+table.stripes-none tr, table.stripes-odd tr:nth-of-type(even) { background: none; }
+
+th.halign-left, td.halign-left { text-align: left; }
+
+th.halign-right, td.halign-right { text-align: right; }
+
+th.halign-center, td.halign-center { text-align: center; }
+
+th.valign-top, td.valign-top { vertical-align: top; }
+
+th.valign-bottom, td.valign-bottom { vertical-align: bottom; }
+
+th.valign-middle, td.valign-middle { vertical-align: middle; }
+
+table thead th, table tfoot th { font-weight: bold; }
+
+tbody tr th { display: table-cell; line-height: 1.5; background: none; }
+
+tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: #222; font-weight: bold; }
+
+p.tableblock > code:only-child { background: none; padding: 0; }
+
+p.tableblock { font-size: 1em; }
+
+td > div.verse { white-space: pre; }
+
+ol { margin-left: 0.25em; }
+
+ul li ol { margin-left: 0; }
+
+dl dd { margin-left: 1.125em; }
+
+dl dd:last-child, dl dd:last-child > :last-child { margin-bottom: 0; }
+
+ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { margin-bottom: 0.625em; }
+
+ul.checklist, ul.none, ol.none, ul.no-bullet, ol.no-bullet, ol.unnumbered, ul.unstyled, ol.unstyled { list-style-type: none; }
+
+ul.no-bullet, ol.no-bullet, ol.unnumbered { margin-left: 0.625em; }
+
+ul.unstyled, ol.unstyled { margin-left: 0; }
+
+ul.checklist { margin-left: 0.625em; }
+
+ul.checklist li > p:first-child > .fa-square-o:first-child, ul.checklist li > p:first-child > .fa-check-square-o:first-child { width: 1.25em; font-size: 0.8em; position: relative; bottom: 0.125em; }
+
+ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; }
+
+ul.inline { display: -ms-flexbox; display: -webkit-box; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; list-style: none; margin: 0 0 0.625em -1.25em; }
+
+ul.inline > li { margin-left: 1.25em; }
+
+.unstyled dl dt { font-weight: normal; font-style: normal; }
+
+ol.arabic { list-style-type: decimal; }
+
+ol.decimal { list-style-type: decimal-leading-zero; }
+
+ol.loweralpha { list-style-type: lower-alpha; }
+
+ol.upperalpha { list-style-type: upper-alpha; }
+
+ol.lowerroman { list-style-type: lower-roman; }
+
+ol.upperroman { list-style-type: upper-roman; }
+
+ol.lowergreek { list-style-type: lower-greek; }
+
+.hdlist > table, .colist > table { border: 0; background: none; }
+.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; }
+
+td.hdlist1, td.hdlist2 { vertical-align: top; padding: 0 0.625em; }
+
+td.hdlist1 { font-weight: bold; padding-bottom: 1.25em; }
+
+.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; }
+
+.colist td:not([class]):first-child { padding: 0.4em 0.75em 0 0.75em; line-height: 1; vertical-align: top; }
+.colist td:not([class]):first-child img { max-width: none; }
+.colist td:not([class]):last-child { padding: 0.25em 0; }
+
+.thumb, .th { line-height: 0; display: inline-block; border: solid 4px #fff; -webkit-box-shadow: 0 0 0 1px #ddd; box-shadow: 0 0 0 1px #ddd; }
+
+.imageblock.left { margin: 0.25em 0.625em 1.25em 0; }
+.imageblock.right { margin: 0.25em 0 1.25em 0.625em; }
+.imageblock > .title { margin-bottom: 0; }
+.imageblock.thumb, .imageblock.th { border-width: 6px; }
+.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; }
+
+.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; }
+.image.left { margin-right: 0.625em; }
+.image.right { margin-left: 0.625em; }
+
+a.image { text-decoration: none; display: inline-block; }
+a.image object { pointer-events: none; }
+
+sup.footnote, sup.footnoteref { font-size: 0.875em; position: static; vertical-align: super; }
+sup.footnote a, sup.footnoteref a { text-decoration: none; }
+sup.footnote a:active, sup.footnoteref a:active { text-decoration: underline; }
+
+#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; }
+#footnotes hr { width: 20%; min-width: 6.25em; margin: -0.25em 0 0.75em 0; border-width: 1px 0 0 0; }
+#footnotes .footnote { padding: 0 0.375em 0 0.225em; line-height: 1.3334; font-size: 0.875em; margin-left: 1.2em; margin-bottom: 0.2em; }
+#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; margin-left: -1.05em; }
+#footnotes .footnote:last-of-type { margin-bottom: 0; }
+#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; }
+
+.gist .file-data > table { border: 0; background: #fff; width: 100%; margin-bottom: 0; }
+.gist .file-data > table td.line-data { width: 99%; }
+
+div.unbreakable { page-break-inside: avoid; }
+
+.big { font-size: larger; }
+
+.small { font-size: smaller; }
+
+.underline { text-decoration: underline; }
+
+.overline { text-decoration: overline; }
+
+.line-through { text-decoration: line-through; }
+
+.aqua { color: #00bfbf; }
+
+.aqua-background { background-color: #00fafa; }
+
+.black { color: black; }
+
+.black-background { background-color: black; }
+
+.blue { color: #0000bf; }
+
+.blue-background { background-color: #0000fa; }
+
+.fuchsia { color: #bf00bf; }
+
+.fuchsia-background { background-color: #fa00fa; }
+
+.gray { color: #606060; }
+
+.gray-background { background-color: #7d7d7d; }
+
+.green { color: #006000; }
+
+.green-background { background-color: #007d00; }
+
+.lime { color: #00bf00; }
+
+.lime-background { background-color: #00fa00; }
+
+.maroon { color: #600000; }
+
+.maroon-background { background-color: #7d0000; }
+
+.navy { color: #000060; }
+
+.navy-background { background-color: #00007d; }
+
+.olive { color: #606000; }
+
+.olive-background { background-color: #7d7d00; }
+
+.purple { color: #600060; }
+
+.purple-background { background-color: #7d007d; }
+
+.red { color: #bf0000; }
+
+.red-background { background-color: #fa0000; }
+
+.silver { color: #909090; }
+
+.silver-background { background-color: #bcbcbc; }
+
+.teal { color: #006060; }
+
+.teal-background { background-color: #007d7d; }
+
+.white { color: #bfbfbf; }
+
+.white-background { background-color: #fafafa; }
+
+.yellow { color: #bfbf00; }
+
+.yellow-background { background-color: #fafa00; }
+
+span.icon > .fa { cursor: default; }
+a span.icon > .fa { cursor: inherit; }
+
+.admonitionblock td.icon [class^="fa icon-"] { font-size: 2.5em; text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); cursor: default; }
+.admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #333333; }
+.admonitionblock td.icon .icon-tip:before { content: "\f0eb"; text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); color: #111; }
+.admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #bf6900; }
+.admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #bf3400; }
+.admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #bf0000; }
+
+.conum[data-value] { display: inline-block; color: #fff !important; background-color: #000; -webkit-border-radius: 100px; border-radius: 100px; text-align: center; font-size: 0.75em; width: 1.67em; height: 1.67em; line-height: 1.67em; font-family: "Open Sans", "DejaVu Sans", sans-serif; font-style: normal; font-weight: bold; }
+.conum[data-value] * { color: #fff !important; }
+.conum[data-value] + b { display: none; }
+.conum[data-value]:after { content: attr(data-value); }
+pre .conum[data-value] { position: relative; top: -0.125em; }
+
+b.conum * { color: inherit !important; }
+
+.conum:not([data-value]):empty { display: none; }
+
+h4 { color: #6c818f; }
+
+.literalblock > .content > pre, .listingblock > .content > pre { -webkit-border-radius: 6px; border-radius: 6px; margin-left: 2em; margin-right: 2em; }
+
+.admonitionblock { margin-left: 2em; margin-right: 2em; }
+.admonitionblock > table { border: 1px solid #607f90; border-top-width: 1.5em; background-color: #f0f9ff; border-collapse: separate; -webkit-border-radius: 0; border-radius: 0; }
+.admonitionblock > table td.icon { padding-top: .5em; padding-bottom: .5em; }
+.admonitionblock > table td.content { padding: .5em 1em; color: #000; font-size: .9em; border-left: none; }
+
+.sidebarblock { background-color: #e8ecef; border-color: #ccc; }
+.sidebarblock > .content > .title { color: #444; }
+
+table.tableblock.grid-all { border-collapse: collapse; -webkit-border-radius: 0; border-radius: 0; }
+table.tableblock.grid-all th.tableblock, table.tableblock.grid-all td.tableblock { border-bottom: 1px solid #aaa; }
+
+#footer { background-color: #465158; padding: 2em; }
+
+#footer-text { color: #eee; font-size: 0.8em; text-align: center; }

diff --git a/manual/cli.txt b/manual/cli.txt
new file mode 100644 (file)
index 0000000..c7798df
--- /dev/null
+++ b/manual/cli.txt
@@ -0,0 +1,42 @@
+== Command-line Interface
+
+Even though PulseView has a graphical user interface, there is also a command-line interface that
+you can make use of. It is meant to provide functions for convenience and debug purposes, not to
+replace the user interface itself.
+
+Running 
+
+       pulseview -h
+
+gives you a list of these functions.
+
+Since PulseView can't automatically scan for devices connected to a COM port (ttySx on Linux) or
+Ethernet, you can tell it to look for a specific device using the -d or --driver parameter. Its
+usage is the same as for sigrok-cli. For example:
+
+       pulseview -d lecroy-xstream:conn=vxi/192.168.178.20/111
+
+Also, just as with sigrok-cli, you can specify -i / --input-file and -I / --input-format to open
+a file on startup. Without -I, it is assumed that the file is in the native sigrok format (.sr).
+You can also specify more than one file but they are all expected to be in the same format then.
+Example:
+
+       pulseview -i data.vcd -I vcd
+
+The remaining parameters are mostly for debug purposes:
+
+       -V / --version          Shows the release version
+       -l / --loglevel         Sets the libsigrok/libsigrokdecode log level (max is 5)
+       -D / --no-scan          Don't auto-scan 
+       -c / --clean            Don't restore previous sessions on startup
+
+Of these, -D can be useful when PulseView gets stuck during the startup device scan. No such
+scan will be performed then, allowing the program to start up but you'll have to scan for your
+acquisition device(s) manually before you can use them then.
+
+Another potentially useful option is -c, which can be used when PulseView doesn't start up and
+you don't know what could cause this.
+
+Thus, the combination of both parameters can be seen as some kind of "safe mode" for PulseView:
+
+       pulseview -D -c

diff --git a/manual/decoders.txt b/manual/decoders.txt
new file mode 100644 (file)
index 0000000..aef3034
--- /dev/null
+++ b/manual/decoders.txt
@@ -0,0 +1,104 @@
+== Decoders
+
+Protocol decoders are one of the key elements of PulseView's functionality. They take
+input data that you acquired and process it in a way that results in a (hopefully) much
+easier to understand representation of that same data.
+
+In its simplest form, a protocol decoder (PD) converts a group of 1-bit signals into a
+stream of n-bit events. This is exactly what the parallel PD does: it takes for example
+8 logic channels and treats them like an 8-bit parallel bus, emitting annotations that
+show the current state of the bus at any point in time.
+
+=== Basic Operation
+
+Another one of the protocol decoders available to you is the I²C decoder. It takes the
+two I²C signals SCL and SDA (serial clock / serial data) and shows you the details of
+the I²C communication without the need to evaluate the signal bit by bit yourself.
+
+As an example, let's have look at one of the sample .sr files we keep around for
+validation of the PD code base: https://sigrok.org/gitweb/?p=sigrok-dumps.git;a=blob_plain;f=i2c/rtc_dallas_ds1307/rtc_ds1307_200khz.sr;hb=HEAD[rtc_ds1307_200khz.sr].
+It contains the capture of an I²C master interacting with a https://www.maximintegrated.com/en/products/digital/real-time-clocks/DS1307.html[Dallas DS1307 I²C Real-Time Clock]
+where the master repeatedly sets and queries the time of day. After loading and using
+"zoom-to-fit", it looks similar to this:
+
+image::pv_decoders_1.png[]
+
+Adding the I²C decoder by clicking on ➊ and selecting I²C from the list adds
+a new decode signal to the view. PulseView tries to match existing signals to the signals
+that the newly added protocol decoder needs to function, which is what happened here -
+SCL and SDA have been automatically assigned and the PD has decoded the communication with
+the default parameters. If you need to change the signal assignment or change the decoding
+parameters, you can click on ➋ to do so.
+
+When you zoom in, you now see that PulseView has decoded the I²C messages and displays
+these annotations as part of the decode signal (note that we have zoomed in so far that
+PulseView shows you the individual samples):
+
+image::pv_decoders_2.png[]
+
+This is already very useful, and a massive improvement over counting out pulses on an
+oscilloscope screen. However, sigrok allows us to go one step further with the use of
+so-called stacked decoders. 
+
+=== Decoder Stacking
+
+To add a stacked decoder we open the settings of the decode signal, go to the _Stack
+Decoder_ menu ➊, and select the DS1307 decoder:
+
+image::pv_decoders_3.png[]
+
+With the stacked decoder added, we can now see that PulseView has decoded the meaning
+of the I²C commands, so that we don't need to bother searching the reference manual.
+In this view, we can see that the I²C packet was a command to read the date and time,
+which was then reported to be 10.03.2013 23:35:30. 
+
+There are all kinds of stacked decoders available, but keep in mind that they're not
+shown in the decoder menu. Stacked decoders require a lower-level decoder first before
+they become stackable. Most of the time, they require either the UART, I²C or SPI decoder.
+
+You can check the https://sigrok.org/wiki/Protocol_decoders[List of Protocol Decoders]
+to see which protocol decoders have been created already.
+
+=== Using Decoders on Analog Signals
+
+If you're capturing data using an oscilloscope or import analog signal data from a file,
+you'll quickly notice that protocol decoders don't give you the option to select analog
+channels as inputs. That is because as of now, decoders only work on logic signals. You
+can however convert analog signals into logic signals by choosing a conversion setting
+from the signal setting popup.
+
+image::pv_conversion_a2l.png[]
+
+Here, A1 has been converted using a threshold (with default settings) and A2 has been
+converted using a Schmitt-Trigger emulation (also with default settings). Additionally,
+the conversion threshold display mode has been set to _Background_ in the _Views_ settings
+dialog. This way, you can tell how PulseView decided to change the logic signal level
+as you can now visually understand where the ranges for high and low are placed.
+
+Aside from the default conversion threshold(s), you can choose from a few common presets
+or enter custom values as well. They take the form "0.0V" and "0.0V/0.0V", respectively.
+
+=== Exporting Annotations
+
+If you want to postprocess annotations that were generated by a protocol decoder, you
+can do so by right-clicking into the area of the decode signal (not on the signal label
+on the left). You are shown several export methods to choose from, with the last one
+being only available if the cursor is enabled.
+
+After you chose a method that suits your needs, you are prompted for a file to export
+the annotations to. The contents of the file very much depend on the option you chose
+but also on the annotation export format string that you can define in the _Decoders_
+menu of the settings dialog. If the default output isn't useful to you, you can
+customize it there.
+
+=== Creating a Protocol Decoder
+
+Protocol decoders are written in Python and can be created using nothing more than a
+text editor. You, too, can write one!
+
+To find out how to go about it, please see our https://sigrok.org/wiki/Protocol_decoder_HOWTO[Protocol Decoder How-To]
+and the https://sigrok.org/wiki/Protocol_decoder_API[Protocol Decoder API Reference].
+
+If you do write one, we'd appreciate if you'd contribute to our project so that everyone
+can benefit from your work.
+

diff --git a/manual/generate b/manual/generate
new file mode 100755 (executable)
index 0000000..19d1ca3
--- /dev/null
+++ b/manual/generate
@@ -0,0 +1,28 @@
+#!/bin/sh
+##
+## This file is part of the PulseView project.
+##
+## Copyright (C) 2018 Soeren Apel <soeren@apelpie.net>
+##
+## This program is free software; you can redistribute it and/or modify
+## it under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 2 of the License, or
+## (at your option) any later version.
+##
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with this program; if not, see <http://www.gnu.org/licenses/>.
+##
+
+echo "Trying to generate HTML output..."
+asciidoctor -a stylesheet=readthedocs.css -a stylesdir=asciidoctor-stylesheet-factory/stylesheets -a toc=left pulseview_manual.txt || exit
+echo " --> pulseview_manual.html OK"
+
+# Run asciidoctor-pdf only if it can be found in $PATH
+#echo "Trying to generate PDF output..."
+#type asciidoctor-pdf && asciidoctor-pdf -a stylesheet=readthedocs.css -a stylesdir=asciidoctor-stylesheet-factory/stylesheets pulseview_manual.txt || exit
+#echo " --> pulseview_manual.pdf OK"

diff --git a/manual/images/_callouts.xcf b/manual/images/_callouts.xcf
new file mode 100644 (file)
index 0000000..c712315
Binary files /dev/null and b/manual/images/_callouts.xcf differ

diff --git a/manual/images/device_selector.png b/manual/images/device_selector.png
new file mode 100644 (file)
index 0000000..2bba96b
Binary files /dev/null and b/manual/images/device_selector.png differ

diff --git a/manual/images/device_selector_dropdown.png b/manual/images/device_selector_dropdown.png
new file mode 100644 (file)
index 0000000..08c7399
Binary files /dev/null and b/manual/images/device_selector_dropdown.png differ

diff --git a/manual/images/device_selector_scan.png b/manual/images/device_selector_scan.png
new file mode 100644 (file)
index 0000000..0cbe54b
Binary files /dev/null and b/manual/images/device_selector_scan.png differ

diff --git a/manual/images/pv_after_startup.png b/manual/images/pv_after_startup.png
new file mode 100644 (file)
index 0000000..22a0fcc
Binary files /dev/null and b/manual/images/pv_after_startup.png differ

diff --git a/manual/images/pv_after_startup.xcf b/manual/images/pv_after_startup.xcf
new file mode 100644 (file)
index 0000000..e81a4a5
Binary files /dev/null and b/manual/images/pv_after_startup.xcf differ

diff --git a/manual/images/pv_analysis.png b/manual/images/pv_analysis.png
new file mode 100644 (file)
index 0000000..215d148
Binary files /dev/null and b/manual/images/pv_analysis.png differ

diff --git a/manual/images/pv_analysis.xcf b/manual/images/pv_analysis.xcf
new file mode 100644 (file)
index 0000000..93b7859
Binary files /dev/null and b/manual/images/pv_analysis.xcf differ

diff --git a/manual/images/pv_conversion_a2l.png b/manual/images/pv_conversion_a2l.png
new file mode 100644 (file)
index 0000000..b804fef
Binary files /dev/null and b/manual/images/pv_conversion_a2l.png differ

diff --git a/manual/images/pv_cursors_markers.png b/manual/images/pv_cursors_markers.png
new file mode 100644 (file)
index 0000000..fc8552c
Binary files /dev/null and b/manual/images/pv_cursors_markers.png differ

diff --git a/manual/images/pv_cursors_markers.xcf b/manual/images/pv_cursors_markers.xcf
new file mode 100644 (file)
index 0000000..3748545
Binary files /dev/null and b/manual/images/pv_cursors_markers.xcf differ

diff --git a/manual/images/pv_decoders_1.png b/manual/images/pv_decoders_1.png
new file mode 100644 (file)
index 0000000..ac33def
Binary files /dev/null and b/manual/images/pv_decoders_1.png differ

diff --git a/manual/images/pv_decoders_1.xcf b/manual/images/pv_decoders_1.xcf
new file mode 100644 (file)
index 0000000..19fc127
Binary files /dev/null and b/manual/images/pv_decoders_1.xcf differ

diff --git a/manual/images/pv_decoders_2.png b/manual/images/pv_decoders_2.png
new file mode 100644 (file)
index 0000000..4c85672
Binary files /dev/null and b/manual/images/pv_decoders_2.png differ

diff --git a/manual/images/pv_decoders_3.png b/manual/images/pv_decoders_3.png
new file mode 100644 (file)
index 0000000..153cfdd
Binary files /dev/null and b/manual/images/pv_decoders_3.png differ

diff --git a/manual/images/pv_decoders_3.xcf b/manual/images/pv_decoders_3.xcf
new file mode 100644 (file)
index 0000000..f570f12
Binary files /dev/null and b/manual/images/pv_decoders_3.xcf differ

diff --git a/manual/images/pv_decoders_4.png b/manual/images/pv_decoders_4.png
new file mode 100644 (file)
index 0000000..bb8d863
Binary files /dev/null and b/manual/images/pv_decoders_4.png differ

diff --git a/manual/images/pv_device_config.png b/manual/images/pv_device_config.png
new file mode 100644 (file)
index 0000000..ee7694b
Binary files /dev/null and b/manual/images/pv_device_config.png differ

diff --git a/manual/images/pv_device_config.xcf b/manual/images/pv_device_config.xcf
new file mode 100644 (file)
index 0000000..0e7252d
Binary files /dev/null and b/manual/images/pv_device_config.xcf differ

diff --git a/manual/images/pv_import.png b/manual/images/pv_import.png
new file mode 100644 (file)
index 0000000..645e319
Binary files /dev/null and b/manual/images/pv_import.png differ

diff --git a/manual/images/pv_nodevice.png b/manual/images/pv_nodevice.png
new file mode 100644 (file)
index 0000000..a5db293
Binary files /dev/null and b/manual/images/pv_nodevice.png differ

diff --git a/manual/images/top_bar.png b/manual/images/top_bar.png
new file mode 100644 (file)
index 0000000..5aeae70
Binary files /dev/null and b/manual/images/top_bar.png differ

diff --git a/manual/import_export.txt b/manual/import_export.txt
new file mode 100644 (file)
index 0000000..b3ba772
--- /dev/null
+++ b/manual/import_export.txt
@@ -0,0 +1,33 @@
+== Data Import/Export
+
+In order to facilitate versatile use of the sigrok suite, libsigrok allows users to import
+and export data from files in various formats - some of them as generic as possible, others
+very specific. For a list and details, make sure to check https://sigrok.org/wiki/Input_output_formats[the wiki].
+
+=== Import
+
+The first step to importing data from a file is to know what format the data in the file is
+encoded in. There are common, not-so-common and outright exotic ways to represent data and sigrok
+tries to suit as many needs as it can. To see which formats your version of PulseView supports,
+just click on the small arrow next to the _Open_ button:
+
+image::pv_import.png[]
+
+After choosing the format that you want to use, PulseView will ask for the file name to open.
+Once you picked the file, you may be asked to specify the details of the format, if the input
+module requires them.
+
+For example, the VCD import will ask you for these:
+
+* Compress idle periods: Compress idle periods longer than the specified value (default 0)
+* Downsampling factor: Downsample, i.e. divide the samplerate by the specified factor (default 1)
+* Number of logic channels: The number of (logic) channels in the data (default 0)
+* Skip samples until timestamp: Skip samples until the specified timestamp; < 0: Skip until first timestamp listed; 0: Don't skip (default -1)
+
+
+A click on _Ok_ then loads the data from the selected file and you can work with it.
+
+=== Export
+
+Export works just the same as the import: clicking on the small arrow next to the _Save_ button
+brings up the export menu. Simply choose the format you want to use and proceed.

diff --git a/manual/installation.txt b/manual/installation.txt
new file mode 100644 (file)
index 0000000..82ed0fd
--- /dev/null
+++ b/manual/installation.txt
@@ -0,0 +1,92 @@
+[[installation,Installation]]
+== Installation
+
+PulseView can be run on Linux, Windows, Mac OS X or Android. For some platforms, we provide binary
+packages, for others we provide installers and for others we provide AppImage containers that
+you can run without the need to install anything. Check the https://sigrok.org/wiki/Downloads[sigrok download page]
+to see which option is available for your platform.
+
+=== Linux
+
+On Linux, the usual way to install PulseView is to install the packages provided by your distro's
+package manager. However, sometimes only outdated packages are made available to you. In that case,
+you have two options:
+
+. Use the AppImage which contains all required files and needs no installation:
++
+--
+[listing, subs="normal"]
+wget https://sigrok.org/jenkins/job/sigrok-native-appimage/platform=native-x86_64-appimage/lastSuccessfulBuild/artifact/cross-compile/appimage/out/PulseView-NIGHTLY-x86_64.AppImage
+chmod u+x PulseView-NIGHTLY-x86_64.AppImage
+./PulseView-NIGHTLY-x86_64.AppImage
+
+Please be aware, however, that the AppImages are built every night, so they always contain
+the latest development changes. While we do try to keep the code base in a working state, it is sometimes
+unavoidable to introduce bugs that show up in the nightly builds. If you encounter something that is
+odd to you, please download and install the latest nightly and check if the issue still exists. If it
+does, feel free to https://sigrok.org/bugzilla/[file a bug].
+
+No system files are changed, so if you decide that you no longer want to use PulseView, simply
+delete the AppImage. If you also want the stored settings gone, delete ~/.config/sigrok as well.
+--
+
+. Uninstall any sigrok packages from your package manager and build PulseView from source:
++
+--
+[listing, subs="normal"]
+_[install dependencies https://sigrok.org/wiki/Linux#Building[as listed on the wiki]]_
+mkdir ~/sr
+cd ~/sr
+wget https://sigrok.org/gitweb/?p=sigrok-util.git;a=blob_plain;f=cross-compile/linux/sigrok-cross-linux
+chmod u+x sigrok-cross-linux
+./sigrok-cross-linux
+export LD_LIBRARY_PATH=~/sr
+build/bin/pulseview
+
+No system files are changed, so if you decide that you no longer want to use PulseView, simply
+delete the ~/sr directory. If you also want the stored settings gone, delete ~/.config/sigrok
+as well.
+--
+
+[WARNING]
+--
+If you don't install the PulseView distro packages (as is the case when using the AppImage or building
+from source), PulseView will not be able to access USB and serial port devices unless it's run as root.
+Since programs shouldn't be run as root unless absolutely necessary, we provide udev configuration files
+that allows PulseView access to those devices without being root.
+
+Here's how you install them:
+[listing, subs="normal"]
+sudo bash
+cd /etc/udev/rules.d/
+wget https://sigrok.org/gitweb/?p=libsigrok.git;a=blob_plain;f=contrib/60-libsigrok.rules
+wget https://sigrok.org/gitweb/?p=libsigrok.git;a=blob_plain;f=contrib/61-libsigrok-plugdev.rules
+wget https://sigrok.org/gitweb/?p=libsigrok.git;a=blob_plain;f=contrib/61-libsigrok-uaccess.rules
+sudo udevadm control --reload-rules
+--
+
+=== Windows
+
+We offer installers for PulseView that contain everything you need to get started. Simply download
+them from the https://sigrok.org/wiki/Downloads[sigrok download page] and run them as any other Windows
+installer.
+Please be aware, however, that the Windows installers are built every night, so they always contain
+the latest development changes. While we do try to keep the code base in a working state, it is sometimes
+unavoidable to introduce bugs that show up in the nightly builds. If you encounter something that is
+odd to you, please download and install the latest nightly and check if the issue still exists. If it
+does, feel free to https://sigrok.org/bugzilla/[file a bug].
+
+After installation, you will find a program called Zadig in the start menu. By default, certain devices
+recognized by Windows will have drivers installed for them that PulseView cannot use. The purpose of
+Zadig is to let you change the driver Windows uses for a particular device - for most devices you'll need
+to choose WinUSB to use them with PulseView or the original proprietary Windows driver to use it with whatever
+other software you access the device with. More details are available https://sigrok.org/wiki/Windows[in the wiki].
+
+In case your device doesn't show up in PulseView and you can't find it with a scan either (see next
+chapter), check with Zadig whether the correct driver is assigned for the device.
+
+=== Mac OS X
+
+(Some Mac user needs to fill this chapter)
+
+

diff --git a/manual/license.txt b/manual/license.txt
new file mode 100644 (file)
index 0000000..34ac580
--- /dev/null
+++ b/manual/license.txt
@@ -0,0 +1,3 @@
+== License
+
+This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.

diff --git a/manual/overview.txt b/manual/overview.txt
new file mode 100644 (file)
index 0000000..bfd87f8
--- /dev/null
+++ b/manual/overview.txt
@@ -0,0 +1,40 @@
+[[overview,Overview]]
+== Overview
+
+PulseView is a graphical frontend for the libsigrok and libsigrokdecode libraries, permitting
+access to a wide range of devices and protocol decoders to let you record, analyze, process
+and export analog and logic data. It is part of the sigrok suite, just like the libraries that
+it makes use of.
+
+The sigrok suite needs some kind of hardware to interface to the signals you want to examine.
+We found that most people are currently using logic analyzers based on the http://www.cypress.com/products/ez-usb-fx2lp[Cypress FX2 microcontroller].
+With http://sigrok.org/wiki/Fx2lafw[fx2lafw], sigrok's open source runtime firmware, any device
+containing an FX2 can become a powerful streaming logic analyzer.
+A variety of compatible low cost chinese made logic analyzer products are available for as little
+as $5. These can easily be found by searching for _24MHz Logic Analyzer_. There are also barebone
+Cypress FX2 boards such as the Lcsoft Mini Board, which can usually be found by searching for
+_Cypress FX2 Board_ or similar.
+
+In addition, a good set of https://sigrok.org/wiki/Probe_comparison[quality probe hooks] is recommended.
+
+Aside from FX2-based logic analyzers, sigrok also supports FX2-based oscilloscopes such as the
+https://sigrok.org/wiki/Hantek_6022BE[Hantek 6022BE], non-FX2 devices like the
+https://sigrok.org/wiki/Openbench_Logic_Sniffer[Openbench Logic Sniffer] or devices that make use
+of the SCPI protocol, as all reasonably modern oscilloscopes do (Rigol DS1054z, LeCroy WaveRunner,
+Yokogawa DLM and similar).
+
+Please be aware however, that PulseView currently only supports devices that can either work as an
+https://sigrok.org/wiki/Supported_hardware#Oscilloscopes[oscilloscope],
+a https://sigrok.org/wiki/Supported_hardware#Logic_analyzers[logic analyzer] or
+a https://sigrok.org/wiki/Supported_hardware#Mixed-signal_devices[mixed-signal device]. This
+means that multimeters in particular are currently only usable with either https://sigrok.org/wiki/Sigrok-cli[sigrok-cli]
+or https://sigrok.org/wiki/Sigrok-meter[sigrok-meter].
+
+image::pv_after_startup.png[]
+
+The PulseView user interface is geared towards navigation and analysis of captured waveforms, so
+the most space is by default used up by the main trace view. From here, you can access the most
+often used features.
+
+Before we dive deeper into how to accomplish things, let's make PulseView available on your
+system first.

diff --git a/manual/pulseview_manual.txt b/manual/pulseview_manual.txt
new file mode 100644 (file)
index 0000000..5d0c04d
--- /dev/null
+++ b/manual/pulseview_manual.txt
@@ -0,0 +1,28 @@
+PulseView User Manual
+=====================
+v0.5, dated 2018-09-04
+:doctype: book
+:imagesdir: ./images
+:sectnums:
+:toc:
+:toclevels: 2
+:icons: font
+:figure-caption: Image
+
+ifdef::ebook-format[:leveloffset: -1]
+
+include::license.txt[]
+
+include::overview.txt[]
+
+include::installation.txt[]
+
+include::acquisition.txt[]
+
+include::analysis.txt[]
+
+include::decoders.txt[]
+
+include::import_export.txt[]
+
+include::cli.txt[]