Documenting Session > Archive... and adding breadcrumbs to build.py

build.py

@@ -188,6 +188,31 @@ def GetChildren(fs, pos):
 
 	return children
 
+#
+# Get the parent at this level
+#
+def GetParent(fs, pos):
+	thisLevel =  fs[pos]['level']
+	pos = pos - 1
+
+	while fs[pos]['level'] >= thisLevel and pos > 0:
+		pos = pos - 1
+
+	return pos
+
+#
+# Creates the BreadCrumbs
+#
+def GetBreadCrumbs(fs, pos):
+	breadcrumbs = ' <span class="divider">&gt;</span> <li class="active">'+ fs[pos]['title'] + '</li>'
+	# The <span class="divider">&gt;</span> is for Bootstrap pre-3.0
+	while pos:
+		pos = GetParent(fs,pos)
+		if pos:
+			breadcrumbs=' <span class="divider">&gt;</span> <li><a href="/' + fs[pos]['filename'] + '/">'+ fs[pos]['title'] + '</a></li>'+ breadcrumbs
+
+	breadcrumbs = '<ol class="breadcrumb"><li><a href="/toc/index.html">Home</a></li>' + breadcrumbs + '</ol>'
+	return breadcrumbs
 
 #
 # Make an array of children attached to each node in the file structure
@@ -431,17 +456,28 @@ for header in fileStruct:
 
 		more = '<div id=subtopics>\n' + '<h2>This section contains the following topics:</h2>\n' + '<ul>\n' + more + '</ul>\n' + '</div>\n'
 
+	parent = GetParent(fileStruct, pageNumber)
+
 	# Make the 'Previous' & 'Next' content
 	nLink = ''
 	pLink = ''
+	uLink = ''
 
 	if pageNumber > 0:
-		pLink = '<li><a title="' + fileStruct[pageNumber - 1]['title'] + '" href="/' + fileStruct[pageNumber - 1]['filename'] + '/" class="previous"> &lt; Previous </a></li>'
+		pLink = '<li><a title="' + fileStruct[pageNumber - 1]['title'] + '" href="/' + fileStruct[pageNumber - 1]['filename'] + '/" class="previous"> &larr; Previous </a></li>'
 
 	if pageNumber < len(fileStruct) - 1:
-		nLink = '<li><a title="' + fileStruct[pageNumber + 1]['title'] + '" href="/' + fileStruct[pageNumber + 1]['filename'] + '/" class="next"> Next &gt; </a></li>'
+		nLink = '<li><a title="' + fileStruct[pageNumber + 1]['title'] + '" href="/' + fileStruct[pageNumber + 1]['filename'] + '/" class="next"> Next &rarr; </a></li>'
 
-	prevnext = '<ul class=pager>' + pLink + nLink + '</ul>'
+	if level > 0:
+		uLink = '<li><a title="' + fileStruct[parent]['title'] + '" href="/' + fileStruct[parent]['filename'] + '/" class="active"> &uarr; Up </a></li>'
+	else:
+		uLink = '<li><a title="Ardour Table of Contents" href="/toc/index.html" class="active"> &uarr; Up </a></li>'
+
+	prevnext = '<ul class=pager>' + pLink + uLink + nLink + '</ul>'
+
+	# Make the BreadCrumbs
+	breadcrumbs = GetBreadCrumbs(fileStruct, pageNumber)
 
 	# Create the link sidebar
 	sidebar = CreateLinkSidebar(fileStruct, pageNumber, nodeChildren)
@@ -473,7 +509,7 @@ for header in fileStruct:
 
 	# Add header information to the page if in dev mode
 	if devmode and 'link' in header:
-		content = '<h1>link: ' + header['link'] + '</h2>\n<br><br>\n' + content
+		content = '<h1>link: ' + header['link'] + '</h1>\n<br><br>\n' + content
 
 	# Set up the actual page from the template
 	if 'style' not in header:
@@ -486,6 +522,7 @@ for header in fileStruct:
 	page = page.replace('{{ page.title }}', header['title'])
 	page = page.replace('{% tree %}', sidebar)
 	page = page.replace('{% prevnext %}', prevnext)
+	page = page.replace('{% breadcrumbs %}', breadcrumbs)
 	page = page.replace('{{ content }}', content + more)
 
 	# Create the directory for the index.html file to go into (we use makedirs,
@@ -509,6 +546,7 @@ page = page.replace('{{ page.title }}', 'Ardour Table of Contents')
 page = page.replace('{% tree %}', sidebar)
 page = page.replace('{{ content }}', toc)
 page = page.replace('{% prevnext %}', '')
+page = page.replace('{% breadcrumbs %}', '')
 
 os.mkdir(siteDir + 'toc', 0o775)
 tocFile = open(siteDir + 'toc/index.html', 'w')

include/backup-and-sharing-of-sessions.html

@@ -1,13 +1,96 @@
 
 <p>
-  An Ardour session is stored in a single folder on the computer's filesystem. This makes <dfn>backup</dfn> very easy&mdash;any tool capable of backing up a folder can be used to backup a session. The location of a session can be chosen when it is created&mdash;by default it will be in the default session location, which can be altered via <kbd class="menu">Edit &gt; Preferences &gt; Misc &gt; Session Management</kbd>. 
+  An Ardour session is stored in a single folder on the computer's filesystem.
+  This makes <dfn>backup</dfn> very easy: any tool capable of backing up a
+  folder can be used to backup a session. The location of a session is picked when
+  it is created &mdash;by default it will be in the default session location,
+  which can be altered via <kbd class="menu">Edit &gt; Preferences &gt; General &gt;
+  Session</kbd>.
+</p>
+<p>
+  The single folder approach also makes sharing a project easy. Simply copy the
+  session folder (onto a storage device, or across a network) and another Ardour
+  user (on any platform) will be able to use it.
+</p>
+<p>
+  There is one complication in both cases: a session may reference media files that are stored
+  outside of the session folder, if the user has opted not to select
+  <kbd class="optoff">Session &gt; Import &gt; Copy to Session</kbd> during import.
+  Backing up a session with embedded files will not create a copy of the session
+  containing those files. To bring those external files to the session folder,
+  the <a href="@@cleaning-up-sessions"><kbd class="menu">Session &gt; Clean-up &gt;
+  Bring all media into session folder</kbd> menu</a> can be used.
 </p>
 
-<p class="warning">
-  There is one complication: a session may reference media files that are stored outside of the session folder, if <kbd class="optoff">Session &gt; Import &gt; Copy to Session</kbd> is not selected during import. Backing up a session without embedded files will <strong>not</strong> create a copy of the session containing those files.
+<h2>Using the dedicated Zip/Archive Current Session tool</h2>
+
+<figure>
+  <img src="/images/archive-session.png" alt="The Zip/Archive Current Session window">
+  <figcaption>
+    The Zip/Archive Current Session window
+  </figcaption>
+</figure>
+
+<p>
+  The <kbd class="menu">Zip/Archive Current Session</kbd> tool is located in the
+  <kbd class="menu"> File &gt; Archive&hellip;</kbd> menu.
+</p>
+<p>
+  It allows to create a single file containing everything usefull in the session,
+  to share it or back it up, conveniently compressed to a session-archive which
+  is a zip-file (tar.xz to be specific) containing all the audio, MIDI,
+  plugin-settings,... and the currently active session. Ardour can also extract
+  those bundles (<kbd class="menu">Session > Open&hellip;</kbd>).
+</p>
+<p>
+  As opposed to zipping the entire session-folder manually,
+</p>
+<ol>
+  <li>the session-archive only contains the current session-snapshot and only
+    files which are used</li>
+  <li>externally referenced files are included in the archive.</li>
+</ol>
+
 </p>
 
 <p>
-  The single folder approach also makes sharing a project easy. Simply copy the session folder (onto a storage device, or across a network) and another Ardour user (on any platform) will be able to use it. The limitation regarding embedded files applies to session sharing as well.
+  The window shows the following options:
 </p>
+<dl>
+  <dt><dfn>Archive Name</dfn></dt><dd>The name of the archive file, defaulting to
+  the name of the session followed by the date and time</dd>
+  <dt>a dropdown extension selector</dt><dd>allowing to choose between different kind or
+  compressed archive file types</dd>
+  <dt><dfn>Target directory/folder</dfn></dt><dd>defining where in the filesystem
+  the archive file will be generated</dd>
+  <dt><dfn>Audio Compression</dfn></dt><dd>a dropdown menu allowing to compress
+  the audio files themselves by using an audio-tailored compression format, more
+  on that bellow</dd>
+  <dt><dfn>Exclude unused audio sources</dfn></dt><dd>a checkbox to drop every
+  audio that is in the session, but not actually used in the editor</dd>
+</dl>
 
+<p>
+  The <kbd class="menu">Audio Compression</kbd> selection accepts any of:
+</p>
+<ul>
+  <li>None</li>
+  <li>FLAC 16bit</li>
+  <li>FLAC 24bit</li>
+</ul>
+<p>
+  Encoding the audio sources to <abbr title="Free Lossless Audio Codec">FLAC</abbr> allows for a good size reduction of the session.
+  It should be noted though that FLAC is a fixed-point format, meaning that if the
+  audio in the session is in a floating-point format, this conversion will loose
+  some information on the samples values that are rounded, though usually, this
+  lost information cannot be perceived. Choosing "<em>None</em>" for Audio
+  Compression does not compress the audio to FLAC, hence preserving the floating-point
+  data at the cost of a bigger file size. Notice also that converting to FLAC
+  automatically normalizes the audio.
+</p>
+<p>
+  Using the <kbd class="option">Exclude unused audio sources</kbd> option allows
+  to only keep the files actually used in the session, which can be useful to leave
+  any unused take or reference material out of the backup, reducing the archive's
+  global file size.
+</p>

include/the-session-menu.html

@@ -12,9 +12,10 @@
 	<dt>Save</dt><dd>Saves the current session</dd>
 	<dt>Save As&hellip;</dt><dd>Saves to a new session (with options)</dd>
 	<dt>Rename&hellip;</dt><dd>Changes the name of the session</dd>
-	<dt>Snapshot (keep working on current version) &hellip;</dt><dd>Create a <a href="@@snapshots">Snapshot</a> but any subsequent change will be saved to this session</dd>
-	<dt>Snapshot ( switch to new version) &hellip;</dt><dd>Same thing, and any subsequent change will be saved to this new snapshot session</dd>
+	<dt>Snapshot (&amp; keep working on current version)&hellip;</dt><dd>Create a <a href="@@snapshots">Snapshot</a> but any subsequent change will be saved to this session</dd>
+	<dt>Snapshot (&amp; switch to new version)&hellip;</dt><dd>Same thing, and any subsequent change will be saved to this new snapshot session</dd>
 	<dt>Save Template&hellip;</dt><dd>Saves the session as a <a href="@@session-templates">template</a>, without the audio</dd>
+  <dt>Archive&hellip;</dt><dd>Exports the session as a <a href="@@backup-and-sharing-of-sessions">compressed file</a> for archiving or sharing purposes, optionnaly compressing the audio to FLAC</dd>
 	<dt>Metadata</dt>
 		<dt class="sub1">Edit Metadata&hellip;</dt><dd>Opens the <a href="@@metadata">Metadata</a> window, where informations about the session can be saved</dd>
 		<dt class="sub1">Import Metadata&hellip;</dt><dd>Creates the metadata by extracting them from another session</dd>
@@ -44,4 +45,3 @@
 
 	<dt>Quit</dt><dd>Exits Ardour. Prompts for saving the session if it has been modified.</dd>
 </dl>
-

page-template.txt

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-      
+
 <head>
 	<title>{{page.page_title}}</title>
 	<meta http-equiv="Content-type" content="text/html; charset=UTF-8" />
@@ -26,6 +26,7 @@
 	</div></div>
 	<div class="span12" id="content">
 		<div id="search" class="gcse-search"></div>
+    {% breadcrumbs %}
 		<div id="content-main">
 		<h1 class="title">{{ page.title }}</h1>
 {{ content }}
@@ -61,4 +62,3 @@ if ( (isA(/Mac/) || isAbout(/OS X/)) && (!isAbout(/Linux/)) ) {
 
 </body>
 </html>
-