autodescribe.1

.\" -*- nroff -*-
.TH AUTODESCRIBE 1 "2024-01-10" "autodescribe version 8-dev"
.SH NAME
autodescribe \- automatically extract descriptions from files
.SH SYNOPSIS
.B autodescribe
[
.B \-l
]
[
.B \-e
program ]
[
.B \-q
]
[
.B \-t
type ]
file1
[
.I file2 ...
]
.SH DESCRIPTION
.B autodescribe
attempts to extracts a meaningful title from a given file that describes it.
When supported by the file type, it generally uses a formal title or
description metadata attribute. If not, it tries to synthesize a description
from a comment or other text within the file. When relying on the latter
heuristic, the result is not always perfect. When titles are available in
multiple languages, the one matching the current locale is generally returned.
.LP
The file names and descriptions are output on stdout by default, using
shell-compatible quoting for each. Using the \-e option, they can also be used
as arguments to an optional user-defined program called for each file, which
can be used to update a list of file descriptions, rename the files, insert the
data into a database, update an extended filesystem attribute for each file or
perform any other function.
.LP
Many file formats require a special program to extract the metadata. If the
required program is not found, an error message like \(lqcommand not found\(rq
is displayed.
.LP
It currently supports the following file types:
.LP
.RS
.\" This section comes from: ./autodescribe -l | sed -e a.LP -e 's/^\./\\\&./'
3mf (3-D Manufacturing format)
.LP
abw (AbiWord document)
.LP
ac (autoconf source code)
.LP
aiff (Audio Interchange File Format)
.LP
amf (Additive Manufacturing File)
.LP
apk (Android Package Kit)
.LP
appdata (Appdata metainfo file)
.LP
arj (ARJ archive)
.LP
asciidoc (AsciiDoc text)
.LP
asm (assembly language source)
.LP
aup (Audacity Project file)
.LP
avi (Audio Video Interleave file)
.LP
cbm (Commodore disk image)
.LP
c (C source code)
.LP
cmake (CMake build file)
.LP
cue (CD cue index file)
.LP
dar (Disk Archiver archive)
.LP
deb (Debian package)
.LP
desktop (XDG desktop entry file)
.LP
dll (Microsoft Windows PE dynamic link library)
.LP
docbook (DocBook document)
.LP
docx (Microsoft Office document)
.LP
ebook (E-book formats, epub, azw, fbz, etc.)
.LP
egg (Python egg package)
.LP
exe (Microsoft Windows PE executable)
.LP
first_line (first line of text file)
.LP
flac (FLAC audio file)
.LP
flatpakref (Flatpak Reference File)
.LP
fodf (Open Document Format flat file)
.LP
gcode (G-code machine control file)
.LP
gif (GIF image)
.LP
gnumeric (Gnumeric spreadsheet)
.LP
gpx (GPX GPS track)
.LP
html (HTML text)
.LP
ics (iCalendar entry)
.LP
iso (ISO-9660 CD-ROM image)
.LP
jar (Java jar)
.LP
jpeg (JPEG JFIF image)
.LP
kdenlive (Kdenlive file)
.LP
kra (Krita image)
.LP
lsm (Linux Software Map)
.LP
lzh (lzh/lha archive with desc.sdi comment)
.LP
man (man page)
.LP
mantxt (plain text version of man page)
.LP
md (Markdown text)
.LP
mkv (Matroska video)
.LP
mlt (mlt video file)
.LP
mov (QuickTime video)
.LP
mp3 (MPEG-1 layer 3 audio)
.LP
mp4 (MPEG-4 video)
.LP
mscx (MuseScore music score)
.LP
mscz (MuseScore music score compressed)
.LP
odf (Open Document Format)
.LP
ogg (Ogg media file)
.LP
otf (OpenType font/TrueType font)
.LP
pam (Portable Arbitrary Map image)
.LP
pascal (Pascal source code)
.LP
patch (git format-patch)
.LP
pcap (Pcap network capture file)
.LP
pc (pkg-config library file)
.LP
pctmpl (pkg-config library file template)
.LP
pdf (Portable Document Format)
.LP
plist (Apple property list)
.LP
png (PNG image)
.LP
pnm (pbm/pgm/ppm Portable Any Map image)
.LP
psfont (PostScript font)
.LP
ps (PostScript source code)
.LP
pyproject.toml (Python project definition)
.LP
py (Python source code)
.LP
rpm (rpm package)
.LP
rss (Really Simple Syndication)
.LP
sh (shell script)
.LP
sla (Scribus document)
.LP
slob (Sorted List of Blobs dictionary)
.LP
snap (Snap package)
.LP
spdx (Software Package Data Exchange)
.LP
stl (STL model file)
.LP
subject (news article or mail file)
.LP
svg (Scalable Vector Graphics image)
.LP
svgz (Compressed Scalable Vector Graphics image)
.LP
tbz2 (bzip2-compressed tar archive)
.LP
tellico (Tellico database file)
.LP
texi (Texinfo document)
.LP
tex (TeX document)
.LP
tgz (compressed tar archive)
.LP
tiff (TIFF image)
.LP
tlzip (lzip-compressed tar archive)
.LP
tlzma (lzma-compressed tar archive)
.LP
txz (xzip-compressed tar archive)
.LP
tzst (zstd-compressed tar archive)
.LP
uue (UUencoded file)
.LP
vbox (VirtualBox machine file)
.LP
vbproj (Microsoft Visual Basic project file)
.LP
vcproj (Microsoft Visual Studio project file)
.LP
wacz (Web Archive Collection Zipped)
.LP
warcgz (Compressed Web Archive Collection file)
.LP
wav (WAV audio)
.LP
whl (Python wheel package)
.LP
wml (Wireless Markup Language)
.LP
xbm (X bitmap image)
.LP
xcf (Gimp image)
.LP
xhb (Homebank file)
.LP
xpm (X pixmap image)
.LP
zip (zip archive)
.LP
zoo (zoo archive)
.LP
.\" End of mechanically-generated section
.RE
.\" ---------------------------------------------------------------------------
.SH OPTIONS
.TP
.BI \-e \ program
Run
.I program
once for each file. It is given two arguments; the file comment and the file
name. The program argument is subject to shell quoting so it can contain
multiple words.
.TP
.B \-l
List the types of files supported. The first word of each line is the type to
give the \-t option. Some types are actually families that support several file
extensions.
.TP
.BI \-t \ type
Use
.I type
as the file type instead of determining it from the file name. The value of
.I type
must come from the list shown with \-l.
.TP
.B \-q
Set quiet mode. Don't display anything except in case of error.
.\" ---------------------------------------------------------------------------
.SH EXAMPLES
To see the title of the PDF file
.IR foo.pdf ,
run:
.EX
autodescribe foo.pdf
.EE
.LP
To see only the files with titles that can be extracted, run:
.EX
autodescribe * 2>/dev/null
.EE
.LP
If the file
.IR foo.otf
is actually an OpenText file (and not an OpenType font file) run:
.EX
autodescribe -t odf foo.otf
.EE
.LP
If the file
.I foo.png
contains a description
.I Foo is gud
then this command would add that to an extended file attribute on the file if
run on a Linux system:
.EX
autodescribe -e 'setfattr -n user.xdg.comment -v' foo.png
.EE
This would end up running the command
.EX
setfattr -n user.xdg.comment -v 'Foo is gud' foo.png
.EE
.LP
This command would rename all the PDF files to their titles with a
.I .pdf
extension:
.EX
autodescribe -e 'renuniq -t %{DESC}%{EXT} -d' *.pdf
.EE
This relies on the
.I renuniq
program from https://github.com/dfandrich/renuniq/
.\" ---------------------------------------------------------------------------
.SH "EXIT STATUS"
.B autodescribe
always returns 0 unless no arguments were given when it returns 1. This is
subject to change in a future release.
.\" ---------------------------------------------------------------------------
.SH BUGS
.BR autodescribe 's
command-line option processing is very limited; the order which options appear
is significant and only one option may follow each dash. Its comment extraction
is in some cases built around a simple regex that may be easily fooled.
.\" ---------------------------------------------------------------------------
.SH AUTHOR
Daniel Fandrich <dan@coneharvesters.com>
.LP
See https://github.com/dfandrich/fileviewinfo/
.\" ---------------------------------------------------------------------------
.SH COPYRIGHT
.B autodescribe
is Copyright (c) 2021\(en2024 Dan Fandrich <dan@coneharvesters.com>.
Licensed under the MIT license (see LICENSE).