From fdf05235b45a22d8708464841162f396ea49dc86 Mon Sep 17 00:00:00 2001 From: Ed Ward Date: Fri, 24 Feb 2017 13:15:07 +0100 Subject: [PATCH] Documenting Session > Archive... and adding breadcrumbs to build.py --- build.py | 46 +++++++++- include/backup-and-sharing-of-sessions.html | 91 +++++++++++++++++++- include/the-session-menu.html | 6 +- page-template.txt | 4 +- source/images/archive-session.png | Bin 0 -> 8332 bytes 5 files changed, 134 insertions(+), 13 deletions(-) create mode 100644 source/images/archive-session.png diff --git a/build.py b/build.py index 5d6ecfd..127f43f 100755 --- a/build.py +++ b/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 = ' >
  • '+ fs[pos]['title'] + '
    • ' + # The > is for Bootstrap pre-3.0 + while pos: + pos = GetParent(fs,pos) + if pos: + breadcrumbs=' >
  • '+ fs[pos]['title'] + '
    • '+ breadcrumbs + + breadcrumbs = '
    1. Home
      2. ' + breadcrumbs + '
    ' + return breadcrumbs # # Make an array of children attached to each node in the file structure @@ -431,17 +456,28 @@ for header in fileStruct: more = '
    \n' + '

    This section contains the following topics:

    \n' + '\n' + '
    \n' + parent = GetParent(fileStruct, pageNumber) + # Make the 'Previous' & 'Next' content nLink = '' pLink = '' + uLink = '' if pageNumber > 0: - pLink = '
    • ' + pLink = '
    • ' if pageNumber < len(fileStruct) - 1: - nLink = '
    • ' + nLink = '
    • ' - prevnext = '' + if level > 0: + uLink = '
  • ↑ Up
    • ' + else: + uLink = '
  • ↑ Up
    • ' + + prevnext = '' + + # 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 = '

    link: ' + header['link'] + '

    \n

    \n' + content + content = '

    link: ' + header['link'] + '

    \n

    \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') diff --git a/include/backup-and-sharing-of-sessions.html b/include/backup-and-sharing-of-sessions.html index dfb0425..e27ddba 100644 --- a/include/backup-and-sharing-of-sessions.html +++ b/include/backup-and-sharing-of-sessions.html @@ -1,13 +1,96 @@

    - An Ardour session is stored in a single folder on the computer's filesystem. This makes backup very easy—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—by default it will be in the default session location, which can be altered via Edit > Preferences > Misc > Session Management. + An Ardour session is stored in a single folder on the computer's filesystem. + This makes backup 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 —by default it will be in the default session location, + which can be altered via Edit > Preferences > General > + Session. +

    +

    + 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. +

    +

    + 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 + Session > Import > Copy to Session 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 Session > Clean-up > + Bring all media into session folder menu can be used.

    -

    - There is one complication: a session may reference media files that are stored outside of the session folder, if Session > Import > Copy to Session is not selected during import. Backing up a session without embedded files will not create a copy of the session containing those files. +

    Using the dedicated Zip/Archive Current Session tool

    + +
    + The Zip/Archive Current Session window +
    + The Zip/Archive Current Session window +
    +
    + +

    + The Zip/Archive Current Session tool is located in the + File > Archive… menu. +

    +

    + 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 (Session > Open…). +

    +

    + As opposed to zipping the entire session-folder manually, +

    +
      +
    1. the session-archive only contains the current session-snapshot and only + files which are used
      2. +
    2. externally referenced files are included in the archive.
      3. +
    +

    - 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:

    +
    +
    Archive Name
    The name of the archive file, defaulting to + the name of the session followed by the date and time
    +
    a dropdown extension selector
    allowing to choose between different kind or + compressed archive file types
    +
    Target directory/folder
    defining where in the filesystem + the archive file will be generated
    +
    Audio Compression
    a dropdown menu allowing to compress + the audio files themselves by using an audio-tailored compression format, more + on that bellow
    +
    Exclude unused audio sources
    a checkbox to drop every + audio that is in the session, but not actually used in the editor
    +
    +

    + The Audio Compression selection accepts any of: +

    + +

    + Encoding the audio sources to FLAC 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 "None" 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. +

    +

    + Using the Exclude unused audio sources 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. +

    diff --git a/include/the-session-menu.html b/include/the-session-menu.html index 21acd71..bcb1a63 100644 --- a/include/the-session-menu.html +++ b/include/the-session-menu.html @@ -12,9 +12,10 @@
    Save
    Saves the current session
    Save As…
    Saves to a new session (with options)
    Rename…
    Changes the name of the session
    -
    Snapshot (keep working on current version) …
    Create a Snapshot but any subsequent change will be saved to this session
    -
    Snapshot ( switch to new version) …
    Same thing, and any subsequent change will be saved to this new snapshot session
    +
    Snapshot (& keep working on current version)…
    Create a Snapshot but any subsequent change will be saved to this session
    +
    Snapshot (& switch to new version)…
    Same thing, and any subsequent change will be saved to this new snapshot session
    Save Template…
    Saves the session as a template, without the audio
    +
    Archive…
    Exports the session as a compressed file for archiving or sharing purposes, optionnaly compressing the audio to FLAC
    Metadata
    Edit Metadata…
    Opens the Metadata window, where informations about the session can be saved
    Import Metadata…
    Creates the metadata by extracting them from another session
    @@ -44,4 +45,3 @@
    Quit
    Exits Ardour. Prompts for saving the session if it has been modified.
    - diff --git a/page-template.txt b/page-template.txt index 2e963dc..005e05d 100644 --- a/page-template.txt +++ b/page-template.txt @@ -1,7 +1,7 @@ - + {{page.page_title}} @@ -26,6 +26,7 @@
    + {% breadcrumbs %}

    {{ page.title }}

    {{ content }} @@ -61,4 +62,3 @@ if ( (isA(/Mac/) || isAbout(/OS X/)) && (!isAbout(/Linux/)) ) { - diff --git a/source/images/archive-session.png b/source/images/archive-session.png new file mode 100644 index 0000000000000000000000000000000000000000..6d17e51a20efd1d27d436e432110ab10d661e861 GIT binary patch literal 8332 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