# abctab2ps - Frequently Asked Questions

## Contents

1 Installation
1.1 Compiling with "make" does not work on MacOs X
1.2 I cannot start abctab2ps on Win32 from another location than the installation directory
1.3 The DOS shell on Win32 is a pain to use. Are there alternatives?
1.4 "make install" stops with an error on Unix
1.5 "make rpm" does not work on Linux
1.6 I have installed the MacOs X binary package and cannot find the documentation.
1.7 Can abctab2ps do any harm to my system?
2 Usage
2.1 When called without filename, abctab2ps seems to hang
2.2 How do I enter frets above the 9th?
2.3 The letters in French tablature are too small
2.4 How can I change the default paper size of abctab2ps?
2.5 How can I get more notes on a staff?
2.6 Voice and meter change are ignored
2.7 I cannot create proper abc files with notepad on Win32
2.8 abctab2ps cannot process files that have been created on a Macintosh
2.9 Some abc files that worked fine with abctab2ps 1.3 now produce incorrect output
2.10 Ties across line breaks are not displayed
2.11 Can I add footnotes to the music text?
2.12 How can I add advisory accidentals?
3 Utilities
3.1 Can I convert StringWalker or Fronimo files into abc format?
3.2 How do I embed the output of abctab2ps in other publishing software?
3.3 Can I create PDF files with abctab2ps?
4 Licensing Terms
4.1 Are there any usage/distribution restrictions?
4.2 How does the "GNU General Public License" apply to abctab2ps?
4.3 Is the Postscript output of abctab2ps also covered by the GPL?
4.4 May I redistribute the fonts seperately from abctab2ps?

## 1 Installation

#### 1.1 Compiling with "make" does not work on MacOs X

Make sure that you have installed the developer's CD that ships with MacOs X. Although the developer's CD contains the GNU C compiler, its name is cc rather than gcc before version 10.2 of MacOS X. In that case you must edit the Makefile (with vi or TextEdit) and change the line "CC=gcc" into "CC=cc". Then "make" should work.

#### 1.2 I cannot start abctab2ps on Win32 from another location than the installation directory

Solution A:
• Put the abctab2ps binary into a directory in your search path (eg. C:\Windows). If you do not know how your search path is set you can find it out with the DOS command "path".
• On Windows 9x add the following line to autoexec.bat
set ABCTABFONTS=\path\to\your\abctabfonts
• On Windows NT add a new environment variable ABCTABFONTS in the register card "Umgebung" under "Start/Einstellungen/System" (sorry, I do not know the menu entries in the english version of Windows NT) and set it to the full path of the abctab2ps font directory.
Solution B:
• Put the following DOS script as abctab2ps.bat into a directory in your search path (eg. C:\Windows):

@echo off
set ABCTABFONTS=\path\to\your\abctabfonts
\full\path\to\abctab2ps.exe %*
Solution A is more robust with respect to the invocation of abctab2ps from GUI's. In order to avoid troubles with the DOS shell, your paths to abctab2ps and to the fonts should not contain spaces and should not contain Umlauts.

#### 1.3 The DOS shell on Win32 is a pain to use. Are there alternatives?

If you are used to the conveniences of some other shell like bash, ksh, zsh or tcsh, you should try to install your favourite shell on Win32.

Even for the crappy DOS shell there are some tricks that can make your life a lot easier:

• On Windows 9x, command line editing is turned off by default. To enable it, add the line
doskey /insert
to autoexec.bat and reboot.
• The following registry trick adds a right click option for directories in the "Explorer" so that that you can open a DOS shell in an arbitrary directory with a right mouse click:
• Create a new sub-key called "CommandPrompt" under HKEY_CLASSES_ROOT/Directory/shell
• Change the value of "default" within the key equal to the text you would like on the right click menu, eg. "DOS shell here"
• Create another new sub-key under the newly created key and name it "command" as in HKEY_CLASSES_ROOT/Directory/shell/CommandPrompt/command
• Change the value of "default" within this key to
command.com /k cd "%1"
(on Windows NT use cmd.exe instead of command.com)
Note that the registry trick adding a right click option on directories for opening a shell prompt in that directory also works with other shells. You only need to use a different command in the last "default" value, eg. for bash:

C:\path\to\sh.exe -c 'cd "%L" && exec /bin/bash --login'

#### 1.4 "make install" stops with an error on Unix

Since version 1.2.0, the default font location has moved from /usr/local/lib/abctab2ps to /usr/local/share/abctab2ps. Moreoever, versions before 1.2.0 required the environment variable ABCTABFONTS in order to find their fonts. This is no longer required because abctab2ps now looks in some default locations when ABCTABFONTS is unset (see man page for details).

This means however, that when you install a new version of abctab2ps over an old version and forget to unset ABCTABFONTS, abctab2ps will still use the old fonts. If the install script recognizes this situation, it will stop with an error.

Solution: uninstall the old version first and do no longer set the environment variable ABCTABFONTS.

#### 1.5 "make rpm" does not work on Linux

First, you need to install the ESP Package Manager (epm).

Second, rpm writes the resulting packages in a central directory which is configured as "topdir" in /usr/lib/rpmrc or /etc/rpmrc. Thus you must make sure that you can write to that directory. The easiest way to do so is with a chmod 1777 on that directory (the leading "1", which sets the "sticky bit", is strongly recommended on a multi user system for security reasons).

#### 1.6 I have installed the MacOs X binary package and cannot find the documentation.

The man page (describes abctab2ps' command line options) can be read with man abctab2ps. The users' guide, this FAQ's and the examples are installed under /usr/share/doc/abctab2ps.

#### 1.7 Can abctab2ps do any harm to my system?

Some string processing routines in abctab2ps are written so poorly that a "buffer overflow" may occur. D.J. Bernstein and Limin Wang have proven for abctab2ps 1.6.3 that a malicious hacker could utilize this when an especially prepared abc file is opened with abctab2ps. Although the reported problems have been fixed in version 1.6.4, there might be other hidden buffer overflow bugs. To be on the safe side you should take care of two points:
• never run abctab2ps as a user with administrator privileges
• before running abctab2ps on an abc file from an unknown source, check its content in an editor

## 2 Usage

#### 2.1 When called without filename, abctab2ps seems to hang

When called without an abc file as parameter, abctab2ps expects its input from stdin, that is from the terminal or from a pipe. You can stop abctab2ps' waiting for input with Ctrl-C (quits process) or Ctrl-D (closes stdin).

This is a useful feature, because you can pipe the output from another command directly into abctab2ps, eg.

abcselect -V 1,2 -Q 3-6 sample.abc | abctab2ps

#### 2.2 How do I enter frets above the 9th?

abctab2ps supports fret numbers and letters up to the 15th fret. The only quibble is that the letter "j" is not used in french tablature. Thus the 9th fret is "k" etc.

#### 2.3 The letters in French tablature are too small

The parameter tabfontsize (or command line option -tabsize) not only changes the font size of the tablature font but also the line distance between adjacent tablature lines. Try to set the parameter tabfontscale (see the section "Tablature/Format parameters" in the user's guide) greater than one, eg
%%tabfontscale 1.2

#### 2.4 How can I change the default paper size of abctab2ps?

Since version 1.3.0 the paper size is determined automatically on most Linux systems. The mechanism is adopted from libpaper and works as follows:
1. If the environment variable PAPERSIZE is set, the paper format ("a4", "letter") is taken from its value. The evaluation is not casesensitive.
2. Otherwise the paper format is read from /etc/papersize
3. .
4. The full path name of the papersize file can be overridden by the environment variable PAPERCONF.
5. If these methods do not yield a paper format, the default "a4" is used.

Warning: Before version 1.1.13 of libpaper the meaning of the variables PAPERSIZE and PAPERCONFIG were reversed (oh my!). abctab2ps adopted the new meaning of these variables with version 1.6.3. Older versions of abctab2ps still used the old convention. To avoid confusion it is best, not to use these environment variables at all.

In any case, you can always override the paper format with the command line option -paper or set the actual page dimensions explicitly with the parameters pageheight, staffwidth, leftmargin, topmargin, botmargin (see "Format fine tuning/Page layout parameters" in the user's guide).

If you generate PDF with ghostscript or ps2pdf and the first page is ok, but subsequent pages are clipped, you should try to give the papersize as a command line option to the conversion program, eg.

$ps2pdf -sPAPERSIZE=letter bla.ps #### 2.5 How can I get more notes on a staff? You might try the command line option "-a" (see the man page for details). This does not work very well though. If you have single staff lute tablature there is another more reliable way: reduce the default note length and decrease tabaddflags accordingly. Beware however, that this might mess up automatic bar numbering. #### 2.6 Voice and meter change are ignored A voice (V:) or meter (M:) field inside the tune body only applies to the current voice. If you have more than one voice, you must specify the key or meter change in each voice. #### 2.7 I cannot create proper abc files with notepad on Win32 notepad usually appends the extension "txt" to new files. By default this extension is hidden in the Explorer. Thus you see a file "bla.abc" in the Explorer, but its real name is "bla.abc.txt". There are two solutions: • Use a different editor. You can easily find free alternatives while searching for "win32" and "text editor" in your favorite search engine. • If you insist on notepad, put double quotes around the filename in the "Save As" dialog. #### 2.8 abctab2ps cannot process files that have been created on a Macintosh Note: This has been fixed since version 1.5.3. The Unix and Win32 version of abctab2ps expect the newline (\n) sign as line seperator while most Mac editors only use carriage return (\r). The following simple command converts each carriage return in the file "mac.abc" to newline:$ tr '\r' '\n' < mac.abc > unix.abc
Remark: In order to make this command work on Win32 you will need to install the GNU textutils forst; these are available either as a standalone packet for Win32 or as part of Cygwin (recommended).

#### 2.9 Some abc files that worked fine with abctab2ps 1.3 now produce incorrect output

abctab2ps 1.4.0 introduced multi bar rests which are notated with capital Z in abc. Older versions used both z and Z for normal rests.
Solution: replace all occurences of upper case Z in the music body of your abc file with lower case z.

#### 2.10 Ties across line breaks are not displayed

Note: This has been fixed since version 1.6.0

This happens when the line does not end with a bar line. As a workaround you can insert an invisible bar [|] at the end of the line.

#### 2.11 Can I add footnotes to the music text?

Footnotes are necessary for the critical report of editorial corrections. Use guitar chords in the music for footnote numbers and reference these in W: lines.

#### 2.12 How can I add advisory accidentals?

Use guitar chords with \#, \b, \=. This will print the accidentals above the notes.

## 3 Utilities

#### 3.1 Can I convert StringWalker or Fronimo files into abc format?

StringWalker and Fronimo use undocumented proprietary binary file formats which can be read only with the respective programs. So if you have such a file without the corresponding program, you are at a loss.

However, if you know the person who has created the files, there is a way out:

• If he is using StringWalker, ask him to directly export abc (works since StringWalker version 4.2)
• Otherwise, ask this person to export the tablature in Wayne Cripps' TAB format
• Convert this format with tab2abc into abc; tab2abc is available from the abctab2ps home page

#### 3.2 How do I embed the output of abctab2ps in other publishing software?

This depends on the publishing software you are using. Here are solutions for some programs:
• LaTeX supports the import of EPS (encapsulated postscript). To generate EPS, use abctab2ps' command line option -E.
• Pdftex cannot directly import EPS images. It accepts however images in bitmap formats (eg. PNG) and in PDF. Although PNG can be generated from postscript with ghostscript, this is not recommended due to a heavy quality loss. It is better to convert the EPS output to PDF, eg. with epstopdf which is shipped with most TeX distributions.
• Microsoft Word only accepts images in bitmap formats, which is inadequate for use with abctab2ps.
• Unix WYSIWIG text processors like Applixware support the import of EPSI files. This variant of EPS includes a low quality bitmap of the graphics, which the word processor uses for its online display. EPSI can be generated from postscript with the program ps2psi (comes with ghostscript).

#### 3.3 Can I create PDF files with abctab2ps?

abctab2ps creates postscript files, which can be converted to PDF with a number of third party programs. One option is to use ghostscript and some wrapper script like ps2pdf (comes with ghostscript) or epstopdf.

Beware however, that PDF has a number of disadvantages compared to Postscript:

• PDF does not supports type3 outline fonts. This means that the tablature fonts are converted to bitmap fonts and look rather poor in Acrobat Reader.
• Unlike EPS ("Encapsulated PostScript"), there is no encapsulated PDF format. Thus PDF files are difficult to embedd in other documents.
• In most cases PDF files are considerably larger even than uncompressed postscript files. Compared to gzipped postscript, PDF files are approximately five to ten times larger.
• While there is a great deal of free postscript manipulation software available, even the most primitive PDF software is generally very expensive.

## 4 Licensing Terms

#### 4.1 Are there any usage/distribution restrictions?

abctab2ps can be used without any restrictions. Moreover you are allowed to make and distribute as many copies of abctab2ps as you like.

#### 4.2 How does the "GNU General Public License" apply to abctab2ps?

The "GNU General Public License" (GPL) guarantees the free usage and redistribution of abctab2ps. Moreover it demands that the distribution of modified versions of abctab2ps are distributed again under the terms of the GPL.

That said, there are however two exceptions from the GPL in the abctab2ps licensing terms (see subsequent questions for more explanation):

• The postscript output is not considered a derived work.
• The tablature fonts are copyrighted by their creators.

#### 4.3 Is the Postscript output of abctab2ps also covered by the GPL?

According to the GPL this would be the case, because the Postscript output contains code from abctab2ps and thus is a "derived work" in the sense of the GPL (this is the so called "infectious character" of the GPL).

This would mean a serious restriction to the usability of abctab2ps, and therefore the postscript output of abctab2ps is explicitly excluded from the scope of the GPL in the abctab2ps licensing terms (see the file LICENSE in the abctab2ps distribution).

Thus you are free to distribute the abctab2ps output files at terms of your choice.

#### 4.4 May I redistribute the fonts seperately from abctab2ps?

The tablature fonts are copyrighted by their creators (see the font files for details), who have granted permission to use them with abctab2ps. If you want to use or distribute them seperately, you must ask the copyright owners for permission.

Last changed 2006-01-16