#4905 Documentation - --include requires absolute paths

[Palmer Ralph]

Federico Bruni wrote :

Should we say explicitly in the doc that -I or --include option requires absolute path(s)?
Paragraph to be modified is in Usage 1.2:

-I, --include=directory

Add directory to the search path for input files.

Multiple -I options may be given. The search will start in the first defined directory, and if the file to be included is not found the search will continue in subsequent directories.

Perhaps a warning like "~ cannot be used, use absolute path" may be also helpful.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

$ ~/.local/bin/lilypond --include=~/Documenti/spartiti/ly Aggressive-Lady.ly
GNU LilyPond 2.19.43
Processing Aggressive-Lady.ly' Parsing... Aggressive-Lady.ly:2:10: error: cannot find file:myStyle.ly'
(search path: /home/fede/.local/lilypond/usr/share/lilypond/current/fonts/svg/:/home/fede/.local/lilypond/usr/share/lilypond/current/fonts/type1/:/home/fede/.local/lilypond/usr/share/lilypond/current/fonts/otf/:/home/fede/.local/lilypond/usr/share/lilypond/current/scm:/home/fede/.local/lilypond/usr/share/lilypond/current/ps:/home/fede/.local/lilypond/usr/share/lilypond/current/ly:~/Documenti/spartiti/ly:') \include "myStyle.ly" Aggressive-Lady.ly:13:19: error: unknown escaped string:\I'

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

[David Kastrup]

~ is neither an absolute not a relative path, it is a shell shorthand for some shells. Programs need to interpret it explicitly unless it starts an unquoted word:

echo ~ -> /home/myself
echo "~" -> ~
xxx=~ && echo "$xxx" -> /home/myself
xxx="~" && echo "$xxx" -> ~
xxx="~" && echo $xxx -> ~
xxx=--include=~ && echo $xxx -> --include=~

So if you want to use a home-relative directory, you need to write something like
-I ~ and must not quote the ~ and cannot use --include=.

Unless LilyPond were to use something like wordexp(3) but since LilyPond usually is called from a shell already, that would result in having to quote special characters twice. So I am not really in favor of it.