Localized File System Version of Ardour 7 Tutorial

[abyss]

I am temporarily making available a zip file of my localized version of the Ardour 7 tutorial at URL https://thoal.us/rsrcs/ardour-7-tutorial-20230916.zip . Maybe someone will find a better online home for it.

This method for obtaining a local copy of the Ardour 7 tutorial suitable for a local file system was created in September 2023 using Gnu/Linux Debian 12. The website build software Hugo was obtained from the Debian package manager via ‘apt install hugo’ in the bourne again (bash) shell. A complicated bash command featuring the stream editor sed and python 3 was used to reformat the local href targets of the web portal from absolute to relative paths. This method is admittedly a hack, but I got the results I wanted. All the linkage issues that I found in my localized web portal were also present in the web portal hosted by GitHub. The Russian translation is largely incomplete, for example.

The Ardour 7 tutorial is linked from the Help menu of the Ardour 7 interface and available in English at URL Home :: Ardour tutorial . A local copy of the tutorial is desirable, but evidently a version of the tutorial suitable for a local file system is not available. Downloading all the webpages from the tutorial web portal with a regular web browser is not practical. The build package of the Ardour 7 tutorial, like the tutorial web portal, is hosted on GitHub. The build package home page is at URL ahych-tee-tee-pee-ess-colan//github.com/prokoudine/ardour-tutorial and may readily be downloaded as a zip bundle (by clicking on the green button labeled ‘Code’) or by using the version control system software Git with an account from GitHub.

Robin Gareus made the entire Ardour 7.3 manual available as a single PDF file (Ardour 7 Manual (PDF Format) - #5 by gr3yh0und). The entire Ardour tutorial in a single PDF file could be nice (text search feature). I can guess that creating one HTML file of the Ardour tutorial could be an intermediary step. I do not know how to do that. I am pleased with the local tutorial document I was able to create. The English tutorial content and presentation is great, and I consider myself to be a fortunate monolinguist.

I downloaded and unzipped the zip bundle. The bundle is incomplete because the empty directory ‘./themes/hugo-theme-relearn’ is a placeholder. I downloaded the Hugo relearn theme as a zip bundle from the theme’s GitHub home page at URL GitHub - McShelby/hugo-theme-relearn: A theme for Hugo designed for documentation .

The build control directory tree requires the builder software Hugo to create the build target directory tree that is the tutorial web portal. I am not well versed with Hugo, but my impression is that the build control deals exclusively with absolute URLs and does not offer relative URLs. Furthermore, I was unable to locate the build target subtree separately from the build control subtree and generate a properly styled web portal. Therefore, final placement of the resultant directory tree with the desired top-level directory name may be advisable before using the build package to build the web portal as shown here. On Linux, a suitable final location could be /usr/local/share/doc/ , but root privileges would be necessary to build and revise it there.

All web portal generation and alteration commands are run from the top-level build directory. This is an overview of the conversion process.

(1) Place the complete build directory tree in the desired location and identify the absolute path of the top-level directory (originally named ‘ardour-tutorial-main’ in my case). Determine if you need root (a.k.a. superuser) privileges. If so, you may prepend ‘sudo ’ to the bash shell commands to get them to work. If the web portal can be converted to relative local paths, it can be done without root privileges (which is more secure), and the use of root privileges can be limited to making and manipulating a copy of the generically localized web portal subtree.

(2) Run the hugo program from within the top-level build directory and provide the absolute path to that directory as the value for the -b option and provide the single dot signifying the current directory for the -s and -d options. The result should be a largely working local copy of the tutorial.

(3) With a web browser verify the generated web portal is working correctly overall. Formatting should be good and links should generally work. Links to directories will require an extra step of clicking through to that directory’s file ‘index.html’. If desired, stop here or make a backup of the subtree. If desired, test the subtree at a different location and expect hyperlink redirection to the build location.

(4) Run the command to add ‘index.html’ to href targets that refer to directories. This will eliminate the requirement to click through webpages of directory contents.

(5) Adjust the ugly bash command for the conversion of paths within the build subtree from absolute to relative paths by assigning the built tree root path (as it was during the hugo build operation) to the variable rootprefix at the start of the command. Do not end the absolute value path with a forward slash unless you want to take a chance. One may also add one pair of parenthesis around the command to isolate the command’s assignments of shell variables.

(6) Run the prepared command to convert to relative local paths.

(7) Similarly, adjust and the command for the adjustment from absolute to relative paths in script references by assigning the correct absolute path to variable rootprefix. A pair of parenthesis may be added.

(8) Run the prepared command to adjust paths in script references.

(9) Run without modification the command to make two final adjustments to the top-level file ‘index.html’.

(10) Run the command to remove build content that is not web portal content.

(11) Check the results with a web browser.

(12) Check the results moved or copied to a different location with a web browser. If it works, you might want to create a compressed bundle or archive of it.

Step 1: Go to the top-level directory of the tutorial build subtree. A date of build download in the name might be desirable. Identify and verify the absolute path to the top-level and current directory.

cd \<tutorial build home with relearn theme files in the correct location\>

pwd

Step 2: Less than perfect but styled correctly.

hugo -b '/home/abyss/Downloads/ardour-7-tutorial-20230916' -s '.' -d '.'

Step 3: Browser check.

Step 4: Add index.html to href values that refer to local directories.

find . -type f -name index.html -execdir sed -Ei 's%(href="/?([^/:]+/)*[[:alnum:]_.-]+/)(">)%\1index.html\3%' '{}' \; ; find . -type f -name index.html -execdir sed -Ei 's%(href="/?([^/:]+/)*[[:alnum:]_-]+)(">)%\1/index.html\3%' '{}' \;

Steps 5 and 6: Replace absolute URL/href references with root prefix with relative local URL/href references. ADJUST rootprefix assignment. Any trailing forward slash is superfluous and stripped, even for the untested root directory (‘/’).

rootprefix=/home/abyss/Downloads/ardour-7-tutorial-20230916 ; rootprefix=${rootprefix%/} ; for f in $(find -type f -name index.html); do rootref=$(grep -m 1 -P '="'${rootprefix}'(/[[:alnum:]_.?=-]+)*"' $f | sed -E 's%.*="('${rootprefix}'(/[[:alnum:]_.?=-]+)*)".*%\1%'); while [ "$rootref" ] ; do reltopref=$(echo $rootref|sed -E 's%^'${rootprefix}'%./%'); relref=$(python3 -c 'import os.path; print ( os.path.relpath("'${reltopref}'", os.path.dirname("'$f'")))') ; if [[ "${relref}" != '' && "${relref}" != .* ]] then relref="./${relref}" ; fi ; echo $rootref from $f ; echo ' ->' $relref ; rootref_escaped=$(echo $rootref|sed -E 's%\?%\\?%g'); sed -Ei 's%="'${rootref_escaped}'"%="'${relref}'"%g' $f; rootref=$(grep -m 1 -P '="'${rootprefix}'(/[[:alnum:]_.?=-]+)*"' $f | sed -E 's%.*="('${rootprefix}'(/[[:alnum:]_.?=-]+)*)".*%\1%'); done; done

Steps 7 and 8: Adjust paths in script references. ADJUST rootprefix assignment. Any trailing forward slash is superfluous and stripped, even for the untested root directory (‘/’).

rootprefix=/home/abyss/Downloads/ardour-7-tutorial-20230916 ; rootprefix=${rootprefix%/} ; rootprefix_escaped=$(echo $rootprefix|sed -E 's%([^/])/$%\1%'|sed -E 's%^/([^/])%\1%'|sed -E 's%/%\\\\/%g') ; for f in $(find -type f -name index.html); do sed -Ei 's%'${rootprefix_escaped}'%.%g' $f; done

Step 9 :Run the command to make two final adjustments to the top-level file ‘index.html’. ADJUST rootprefix assignment. Any trailing forward slash is superfluous and stripped, even for the untested root directory (‘/’).

rootprefix=/home/abyss/Downloads/ardour-7-tutorial-20230916 ; rootprefix=${rootprefix%/} ; sed -Ei 's%(url=)'${rootprefix}'/?%\1./%' index.html ; sed -Ei 's%(<title>)'${rootprefix}'/?%\1./%' index.html

Step 10: Remove build content that is not web portal content. The tutorial web portal content is the top-level file ‘index.html’, the two-letter language subdirectories, and subdirectories ‘css’, ‘js’, and ‘webfonts’. The files ‘LICENSE’ and ‘README.md’ are pertinent documentation of the tutorial. I am not familiar with the utility of the XML files, file ‘.gitmodules’, file ‘.hugo_build.lock’, and subdirectory ‘.github’.

rm -rv archetypes config.toml content fonts images layouts resources static themes

Steps 11 and 12: Check the results. If the results are satisfactory, consider making a backup archive file. A date in the name of the archive file may be appropriate.

—Abyss

EDIT: Fix URLs for OP and formatting – Seablade

[Piergi]

Alternatively you can use wget -mkEpnp http://example.org to make a local mirror of a website, including images and css sheets and so on.

The full command would be

wget --mirror --convert-links --adjust-extension --page-requisites 
--no-parent http://example.org

I haven’t tried it in this form recently, but I do have mirrored a couple of websites in the past with wget.

[x42 (Robin Gareus)]

The manual is directly accessible including instructions how to host it locally and how to create a PDF: GitHub - Ardour/manual: Mirror of the Ardour manual

–

PS. Is there a reason why you do not use https:// links and obfuscate them in your original post?

[abyss]

Piergi, that’s the very smart way. One minute verses two days = why I’m not a real programmer. I just tried the long options form with Home :: Ardour tutorial and got the perfect English version with highest index.html file under subdirectory ‘en’. I just tried the same with https://prokoudine.github.io/ardour-tutorial/en/ and got the perfect English version (essentially same content) with top level files ‘index.html’ and ‘en.html’. Great to know! That’s what I’ll do any next time.

EDIT: Fixed URLs – Seablade

[abyss]

Robin, I wanted a local copy of the tutorial. I got Ardour manual 2023-02-22 in PDF from you, thanks. I obfuscated the link protocol because my original attempt to post was blocked for having more than two URLs. Apparently, my status is not high enough for more than two URLs. I decided to obfuscate them all.

[x42 (Robin Gareus)]

@abyss

Apparently, my status is not high enough for more than two URLs.

Ah OK. yeah that is a SPAM filter, and will change with time (see Understanding Discourse Trust Levels). I can edit your post if you don’t object.

[abyss]

Robin, it’s up to you. You are a key figure here and for good reason from what I can tell. I defer to your judgement on any improvements you wish to make. My approach is a bit complicated compared to using wget as Piergi suggested. I wish I would have thought to look at the documentation of curl or wget. Those programs are presumably awesome. I have barely used both. I’m not sure my original post is worthy of further consideration. I don’t want to send unsuspecting people the wrong way. Hopefully, they will read further down.

[seablade]

I went ahead and fixed the URLs, while your approach is different, there is nothing wrong with it, and the links are useful to people wanting to read your thoughts.

Seablade

[abyss]

On 28 September 2023 I realized I failed to include the image file ‘./images/Ardour6.png’ in my tutorial zip file at https://thoal.us/rsrcs/ardour-7-tutorial-20230916.zip. The image file depicts a screen shot of Ardour 6 and is used on the tutorial’s home page for each language. Also on 28 September 2023, I have revised the aforesaid zip file without changing the URL and the previous instructions to include a new step 7 and a revised step 11 (was step 10). I do not plan to maintain the URL for the zip file indefinitely. The wget program can be used to download a localized copy of the tutorial as shown by Piergi.

# Step 1: Go to the top-level directory of the tutorial build subtree.
#         A date of build download in the name might be desirable.
#         Identify and verify the absolute path to the top-level and current directory.
cd <tutorial build home with relearn theme files in the correct location>
pwd

# Step 2: Less than perfect but styled correctly.
#         ***ADJUST the path value after the -b option.***
hugo -b '/home/abyss/Downloads/ardour-7-tutorial-20230916' -s '.' -d '.'

# Step 3: Browser check.
# Step 4: Add index.html to href values that refer to local directories.
find . -type f -name index.html -execdir sed -Ei 's%(href="/?([^/:]+/)*[[:alnum:]_.-]+/)(">)%\1index.html\3%' '{}' \; ; find . -type f -name index.html -execdir sed -Ei 's%(href="/?([^/:]+/)*[[:alnum:]_-]+)(">)%\1/index.html\3%' '{}' \;

# Steps 5 and 6: Replace absolute URL/href references with
#                root prefix with relative local URL/href references.
#                ***ADJUST rootprefix assignment. Any trailing
#                   forward slash is superfluous and stripped, even
#                   for the untested root directory (‘/’).***
rootprefix=/home/abyss/Downloads/ardour-7-tutorial-20230916 ; rootprefix=${rootprefix%/} ; for f in $(find -type f -name index.html); do rootref=$(grep -m 1 -P '="'${rootprefix}'(/[[:alnum:]_.?=-]+)*"' $f | sed -E 's%.*="('${rootprefix}'(/[[:alnum:]_.?=-]+)*)".*%\1%'); while [ "$rootref" ] ; do reltopref=$(echo $rootref|sed -E 's%^'${rootprefix}'%./%'); relref=$(python3 -c 'import os.path; print ( os.path.relpath("'${reltopref}'", os.path.dirname("'$f'")))') ; if [[ "${relref}" != '' && "${relref}" != .* ]] then relref="./${relref}" ; fi ; echo $rootref from $f ; echo '  ->' $relref ; rootref_escaped=$(echo $rootref|sed -E 's%\?%\\?%g'); sed -Ei 's%="'${rootref_escaped}'"%="'${relref}'"%g' $f; rootref=$(grep -m 1 -P '="'${rootprefix}'(/[[:alnum:]_.?=-]+)*"' $f | sed -E 's%.*="('${rootprefix}'(/[[:alnum:]_.?=-]+)*)".*%\1%'); done; done

# Step 7 (NEW): Fix static source links to the images subdirectory.
#               ***ADJUST rootprefix assignment. Any trailing forward
#                  slash is superfluous and stripped, even for the untested
#                  root directory (‘/’).***
for img in $(find ./images -type f) ; do imgsuffix="$(echo $img|sed -E 's%.*(/images/([^/]+/)*[[:alnum:]_.-]+)$%\1%')" ; echo Checking for path values ending with $imgsuffix ; for f in $(find -type f -name index.html) ; do if [ -n "$(grep -m 1 -P '="(/[[:alnum:]_-]+)*'${imgsuffix}'[[:alnum:]_.?=-]*' $f)" ] ; then relref=$(python3 -c 'import os.path; print ( os.path.relpath("'${img}'", os.path.dirname("'$f'")))') ; if [[ "${relref}" != '' && "${relref}" != .* ]] then relref="./${relref}" ; fi ; echo Processing $f to target $relref ; sed -Ei 's%="(/[[:alnum:]_-]+)*'${imgsuffix}'((\?[[:alnum:]_.=-]*)?)"%="'${relref}'\2"%g' $f ; fi ; done ; done

# Steps 8 and 9: Adjust paths in script references.
#                ***ADJUST rootprefix assignment. Any trailing
#                   forward slash is superfluous and stripped, even
#                   for the untested root directory (‘/’).***
rootprefix=/home/abyss/Downloads/ardour-7-tutorial-20230916 ; rootprefix=${rootprefix%/} ; rootprefix_escaped=$(echo $rootprefix|sed -E 's%([^/])/$%\1%'|sed -E 's%^/([^/])%\1%'|sed -E 's%/%\\\\/%g') ; for f in $(find -type f -name index.html); do sed -Ei 's%'${rootprefix_escaped}'%.%g' $f; done

# Step 10: Run the command to make two final adjustments
#          to the top-level file ‘index.html’.
#          ***ADJUST rootprefix assignment. Any trailing
#             forward slash is superfluous and stripped, even
#             for the untested root directory (‘/’).***
rootprefix=/home/abyss/Downloads/ardour-7-tutorial-20230916 ; rootprefix=${rootprefix%/} ; sed -Ei 's%(url=)'${rootprefix}'/?%\1./%' index.html ; sed -Ei 's%(<title>)'${rootprefix}'/?%\1./%' index.html

# Step 11 (REVISED): Remove build content that is not web portal content.
#                    The tutorial web portal content is the top-level file ‘index.html’,
#                    the two-letter language subdirectories, and subdirectories ‘css’, ‘js’,
#                   ‘images’, and ‘webfonts’. The files ‘LICENSE’ and ‘README.md’
#                   are pertinent documentation of the tutorial. I am not familiar with
#                   the utility of the XML files, file ‘.gitmodules’, file ‘.hugo_build.lock’,
#                   and subdirectory ‘.github’.
rm -rv archetypes config.toml content fonts layouts resources static themes

# Steps 12 and 13: Check the results. If the results are satisfactory, consider making a backup archive file. A date in the name of the archive file may be appropriate. I used the tutorial download date.

—Abyss