Add 2 screenshots, start writing

BasicConcepts.adoc

@@ -0,0 +1,47 @@
+
+Carla is by design a modular audio plugin host.
+This means it will load audio plugins in a modular rather, where each plugin is a module inside a patchbay and you can connect between them and your hardware in order to send signals to the plugins and/or have them generate sound.
+
+In a modular host, the simplest way to achieve sound is by using "generators" (something that either generates sound by itself, or based on user input).
+
+Here is an example of a MIDI keyboard connected to a synth, which is then connected to the output speakers:
+
+image::screenshots/manual/basics_midi_synth.png[]
+
+==== Control Voltage
+
+In modular hosts it is common to have CV (Control Voltage) signals.
+
+These are similar to audio, in that they stream at regular intervals (contrary to events which only happen at specific points in time).
+CV are a good option for parameters that require very precise and fast control, as they provide infinite precision (CV changes are sample-accurate and not limited to a specific amount of steps)
+
+==== Carla specifics
+
+In Carla, audio and CV connections have blue color, while events (including MIDI) have red color.
+Events are merged into a single port, while audio and CV are separate. For example, stereo audio output consists of 2 independent audio ports.
+
+Audio ports can be patched at will, from any port to any port.
+CV is treated similar to audio (because technically it really is), but you are not allowed to connect audio and CV ports together, for safety reasons.
+Audio and CV ports are constantly streaming data from one side to the other.
+An audio port streams data for a single mono audio channel, while a CV port streams data for a single control/parameter.
+
+Event ports transmit events when they happen (for example, pressing a key on a MIDI keyboard).
+All of MIDI and OSC related events are bundled together in a single event port.
+
+==== Engine modes
+
+There are 4 types of engine processing modes in Carla:
+
+- Single-client: (JACK driver only)
+    Same as Multi-client, except that all JACK ports belong to a single master client.
+    This is needed when a setup doesn't support multi-client JACK apps, such as LADISH.
+
+- Multi-client: (JACK driver only)
+    Every single plugin is exposed as a new JACK client. Audio, CV and event ports are registered as needed.
+
+- Continuous Rack:
+    Plugins are processed in order, from top to bottom.
+
+- Patchbay:
+    Modular patchbay mode, just like in JACK Multi-client and many other modular applications.
+    Every plugin gets its own canvas group and ports allowing you to interconnect plugin audio, cv and event ports.

Introduction.adoc

@@ -1,10 +1,14 @@
 
-Carla is...
+=== About Carla
+
+Carla is a fully-featured modular audio plugin host, with support for many audio drivers and plugin formats.
+
+It has some nice features like transport control, automation of parameters via MIDI CC and remote control over OSC.
 
 === About the User Manual
 
-The Manual was divided into several sections:
+This Manual was divided into several sections:
 
 Introduction:: is the first part of the Manual, we're starting with an overview of the application and mowith a few simple tutorials to get the user hands-on with the synthesizer as fast as possible.
-Basic Topics:: is the second part where we start to cover everything from top to bottom. If you're fairly new to Carla, this part should provide you with a comprehensive, yet not overwhelming instruction.
-Advanced Topics:: the third part, where we go into more detail and cover things that were skipped in the previous part. More advanced users should benefit from this part, adding depth to their understanding of the
+Main Topics:: is the second part where we start to cover everything from top to bottom. If you're fairly new to Carla, this part should provide you with a comprehensive, yet not overwhelming instruction.
+// Advanced Topics:: the third part, where we go into more detail and cover things that were skipped in the previous part. More advanced users should benefit from this part, adding depth to their understanding of the

Makefile

@@ -0,0 +1,21 @@
+
+all: build
+
+build: html resources
+
+html: ../manuals/carla.html
+resources: $(patsubst %,../%,$(wildcard screenshots/manual/*.png))
+
+../manuals/carla.html: *.adoc
+	asciidoc \
+		--no-header-footer \
+		--out-file=../manuals/carla.html \
+		Manual.adoc
+
+../screenshots/manual/%.png: screenshots/manual/%.png
+	cp -v $< $@
+
+clean:
+
+watch:
+	while true; do make; sleep 1; done

Manual.adoc

@@ -4,7 +4,10 @@
 == Introduction
 include::Introduction.adoc[]
 
-== Basic Topics
+=== Basic Concepts
+include::BasicConcepts.adoc[]
+
+== Main Topics
 
 === User Interface
 include::UserInterface.adoc[]

UserInterface.adoc

@@ -1,2 +1,55 @@
 === Main Window
+
 When you run Carla you'll be presented with this window:
+
+image::screenshots/manual/ui_main.png[]
+
+You can see some familiar elements from other applications, like the menu-bar and tool-bar.
+Then you have a side-panel where you will find an integrated filesystem browser (with user bookmarks) and transport controls.
+
+The bigger central area is the working space.
+Here you find the "Rack" where all plugin instances will be shown, the "Patchbay" where you can make connections between the plugins and hardware, and "Logs" where debug or warning messages are logged.
+
+Please note that, under some systems or circunstances, these tabs will not be present.
+When Carla runs as a plugin or under Windows platform, the "Logs" is not visible.
+And when Carla runs as "Carla-Rack" plugin, the "Patchbay" tab is not shown.
+
+The toolbar buttons can also be different depending on the occasion.
+For example, "Save" is not available when running as a plugin, since it is the host responsibility to do that instead.
+
+==== Menus
+
+===== File
+
+In the file menu you can start your project/session from scratch, open existing ones, save and quit/close Carla.
+
+==== Engine
+
+In the engine menu you have the chance to start and stop the audio engine.
+
+In the future it is planned to add a direct shortcut to engine settings here.
+
+==== Plugin
+
+In the plugin menu is where you find the action to add new plugins into the session.
+You can also remove all plugins from this menu, and trigger a few action to all of them at once (for convenience).
+
+==== Canvas
+
+In the canvas menu you find options related to the patchbay canvas view.
+These are to refresh, set zoom level and export the canvas as an image.
+
+When running Carla's engine in "Patchbay" mode, you will also find here a "Show Internal" and "Show External" switch.
+This allows to connect the internal patchbay graph into external devices, such as MIDI keyboards and other JACK clients.
+Using the "Show External" switch is how you usually will setup your MIDI devices.
+
+==== Settings
+
+In the settings menu you can find the action to open Carla's settings, as well as a few on/off switches for what to show on screen.
+By default everything is visible, but you can hide stuff if you prefer.
+
+==== About
+
+In the about menu you can open Carla's about dialog.
+
+In the future it is planned to have useful links here.