[gnuastro-commits] master 7e90562: Installed scripts: New executables written in Bash

[Mohammad Akhlaghi]

branch: master
commit 7e90562c32692670ab4b149cf16f2ffc9376d789
Author: Mohammad Akhlaghi <address@hidden>
Commit: Mohammad Akhlaghi <address@hidden>

    Installed scripts: New executables written in Bash
    
    From this commit, Gnuastro also installs scripts for higher-level usage of
    the programs. In particular, here, a script is added which uses the Fits
    program to classify different FITS files into the same night.
---
 Makefile.am                 |   2 +-
 NEWS                        |  12 ++
 bin/script/Makefile.am      |  50 ++++++++
 bin/script/sort-by-night.in | 278 ++++++++++++++++++++++++++++++++++++++++++++
 configure.ac                |   1 +
 doc/Makefile.am             |   7 +-
 doc/gnuastro.texi           | 222 ++++++++++++++++++++++++++++++++++-
 7 files changed, 567 insertions(+), 5 deletions(-)

diff --git a/Makefile.am b/Makefile.am
index bdca796..4dda3e6 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -118,7 +118,7 @@ SUBDIRS = bootstrapped/lib $(MAYBE_GNULIBCHECK) lib 
$(MAYBE_ARITHMETIC)    \
   $(MAYBE_COSMICCAL) $(MAYBE_CROP) $(MAYBE_FITS) $(MAYBE_MATCH)            \
   $(MAYBE_MKCATALOG) $(MAYBE_MKNOISE) $(MAYBE_MKPROF) $(MAYBE_NOISECHISEL) \
   $(MAYBE_SEGMENT) $(MAYBE_STATISTICS) $(MAYBE_TABLE) $(MAYBE_TEMPLATE)    \
-  $(MAYBE_WARP) doc tests
+  $(MAYBE_WARP) bin/script doc tests
 
 
 
diff --git a/NEWS b/NEWS
index 289ad44..ae93c29 100644
--- a/NEWS
+++ b/NEWS
@@ -109,6 +109,18 @@ GNU Astronomy Utilities NEWS                          -*- 
outline -*-
    --descending: When called with `--sort', will arrange the output rows in
      descending order.
 
+  Installed scripts:
+   With this release, Gnuastro also installs Bash scripts for common
+   higher-level usage of (possibly multiple) programs. These scripts have a
+   `astscript-*' name, to easily show up on the command-line as Gnuastro
+   executables with the other Gnuastro programs, but are identifiable from
+   them. They support options just like the programs (which can be listed
+   with `--help'). Please see the new "Installed scripts" chapter of the
+   book for more.
+   - astscript-sort-by-night: New Gnuastro executable, using Gnuastro's
+     Fits program to identify files with dates in the same night (possibly
+     spanning two calendar dates).
+
   Library:
     GAL_BLANK_LONG: new macro for the `long' type blank value.
     GAL_BLANK_ULONG: new macro for the `unsigned long' type blank value.
diff --git a/bin/script/Makefile.am b/bin/script/Makefile.am
new file mode 100644
index 0000000..485c7fa
--- /dev/null
+++ b/bin/script/Makefile.am
@@ -0,0 +1,50 @@
+## Process this file with automake to produce Makefile.inx
+##
+## Original author:
+##     Mohammad Akhlaghi <address@hidden>
+## Contributing author(s):
+## Copyright (C) 2019, Free Software Foundation, Inc.
+##
+## Gnuastro is free software: you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation, either version 3 of the License, or
+## (at your option) any later version.
+##
+## Gnuastro is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Gnuastro. If not, see <http://www.gnu.org/licenses/>.
+
+
+
+
+
+## List of programs (scripts in this directory) to install under the
+## `prefix/bin' directory (`bin_SCRIPTS'), files necessary to distribute
+## with the tarball (`EXTRA_DIST') and output files (to be cleaned with
+## `make clean).
+bin_SCRIPTS = astscript-sort-by-night
+
+EXTRA_DIST = sort-by-night.in
+
+CLEANFILES = $(bin_SCRIPTS)
+
+
+
+
+
+## Command to do basic substitutions (anything surrounded by an `@').
+do_subst = sed -e 's,address@hidden@],$(VERSION),g' \
+               -e 's,address@hidden@],$@,g'
+
+
+
+
+
+## Rules to build the scripts
+astscript-sort-by-night: sort-by-night.in Makefile
+       $(do_subst) < $(srcdir)/sort-by-night.in > $@
+       chmod +x $@
diff --git a/bin/script/sort-by-night.in b/bin/script/sort-by-night.in
new file mode 100644
index 0000000..11cd127
--- /dev/null
+++ b/bin/script/sort-by-night.in
@@ -0,0 +1,278 @@
+#!/bin/bash
+
+# Separate input datasets into multiple nights, run with `--help', or see
+# description under `print_help' (below) for more.
+#
+# Original author:
+#     Mohammad Akhlaghi <address@hidden>
+# Contributing author(s):
+# Copyright (C) 2019, Free Software Foundation, Inc.
+#
+# Gnuastro is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# Gnuastro is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+# more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with Gnuastro. If not, see <http://www.gnu.org/licenses/>.
+
+
+# Exit the script in the case of failure
+set -e
+
+
+
+
+
+# Default option values (can be changed with options on the
+# command-line).
+hdu=1
+hour=9
+copy=0
+link=0
+quiet=0
+key=DATE
+prefix=./
address@hidden@
address@hidden@
+
+
+
+
+
+# Output of `--usage' and `--help':
+print_usage() {
+    cat <<EOF
+$scriptname: run with '--help' for list of options
+EOF
+}
+
+print_help() {
+    cat <<EOF
+Usage: $scriptname [OPTION] /path/to/data/\*.fits
+
+This script is part of GNU Astronomy Utilities $version.
+
+This script will look into a HDU/extension for a header keyword in the
+given FITS files and interpret the value as a date. The inputs will be
+separated by "night"s. It will then print a list of all the input files
+along with the following two columns: night number and file number in that
+night (sorted by time). With '--link' a symbolic link (one for each input)
+will be made with names including the night classifier. With '--copy'
+instead of a link, a copy of the inputs will be made.
+
+For more information, please run any of the following commands. In
+particular the first contains a very comprehensive explanation of this
+script's invocation: expected input(s), output(s), and a full description
+of all the options.
+
+     Inputs/Outputs and options:           $ info $scriptname
+     Full Gnuastro manual/book:            $ info gnuastro
+
+If you couldn't find your answer in the manual, you can get direct help from
+experienced Gnuastro users and developers. For more information, please run:
+
+     $ info help-gnuastro
+
+$scriptname options:
+ Input:
+  -h, --hdu=STR           HDU/extension of all input FITS files.
+  -k, --key=STR           Header keyword specifying date to use.
+  -H, --hour=FLT          Hour in next day to be included in night.
+
+ Output:
+  -l, --link              list of inputs with night and file number.
+  -c, --copy              Copy the files, don't make symbolic links.
+  -p, --prefix=STR        Prefix for outputs of '--copy' and '--link'.
+
+ Operating mode:
+  -h, --help              Print this help list.
+      --cite              BibTeX citation for this program.
+  -q, --quiet             Don't print the list.
+  -V, --version           Print program version.
+
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+
+GNU Astronomy Utilities home page: http://www.gnu.org/software/gnuastro/
+
+Report bugs to address@hidden
+EOF
+}
+
+
+
+
+
+# Output of `--version':
+print_version() {
+    cat <<EOF
+$scriptname (GNU Astronomy Utilities) $version
+Copyright (C) 2015-2019, Free Software Foundation, Inc.
+License GPLv3+: GNU General public license version 3 or later.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written/developed by Mohammad Akhlaghi
+EOF
+}
+
+
+
+
+
+# Functions to check option values and complain if necessary.
+function on_off_option_error() {
+    cat <<EOF
+$scriptname: '$1' doesn't take any values.
+EOF
+    exit 1
+}
+
+function check_v() {
+    if [ x"$2" = x ]; then
+        echo "$scriptname: option '$1' requires an argument."
+        echo "Try '$scriptname --help' for more information."
+        exit 1;
+    fi
+}
+
+
+
+
+
+# Separate command-line arguments from options. Then put the option
+# value into the respective variable.
+#
+# Each option has two lines because we want to process both these formats:
+# `--name=value' and `--name value'. The former (with `=') is a single
+# command-line argument, so we just need to shift the counter by one. The
+# latter (without `=') is two arguments, so we'll need two shifts.
+while [[ $# -gt 0 ]]
+do
+    case $1 in
+        # Input parameters.
+        -h=*|--hdu=*)     hdu="${1#*=}";    check_v $1 "$hdu"; shift;;
+       -h|--hdu)         hdu="$2";         check_v $1 "$hdu"; shift;shift;;
+        -k=*|--key=*)     key="${1#*=}";    check_v $1 "$key"; shift;;
+       -k|--key)         key="$2";         check_v $1 "$key"; shift;shift;;
+        -H=*|--hour=*)    hour="${1#*=}";   check_v $1 "$hour"; shift;;
+       -H|--hour)        hour="$2";        check_v $1 "$hour"; shift;shift;;
+
+        # Output parameters
+       -l|--link)        link=1;                 shift;;
+       -l=*|--link=*)    on_off_option_error --link;;
+       -c|--copy)        copy=1;                 shift;;
+       -c=*|--copy=*)    on_off_option_error --copy;;
+        -p=*|--prefix=*)  prefix="${1#*=}"; check_v $1 "$prefix"; shift;;
+       -p|--prefix)      prefix="$2";      check_v $1 "$prefix"; shift;shift;;
+
+       # Non-operating options.
+       -q|--quiet)       quiet=1;                shift;;
+       -?|--help)        print_help; exit 0;;
+        -V|--version)     print_version; exit 0;;
+        --cite)           astfits --cite; exit 0;;
+
+        # Unrecognized option:
+        -*) echo "$scriptname: unknown option '$1'"; exit 1;;
+
+       # No option: assumed to be input FITS file.
+       *) inputs="$1 $inputs"; shift;;
+    esac
+done
+
+
+
+
+
+# Basic sanity checks on arguments.
+if [ x"$inputs" = x ]; then
+    echo "$scriptname: no input FITS files."
+    echo "Run with '--help' for more information on how to run."
+    exit 1
+fi
+
+if [ $copy = 1 ] && [ $link = 1 ]; then
+    echo "$scriptname: '--copy' and '--link' cannot be called together"
+    exit 1
+fi
+
+
+
+
+
+# Find the night number (including until 9:00 a.m of the following
+# day) of each image.
+#
+# To do this, we'll convert the date into Unix epoch time (seconds
+# since 1970-01-01,00:00:00) and keep that with the filename.
+list=$(for f in $inputs; do
+          astfits $f --datetosec=$key --hdu=$hdu -q      \
+              | awk -vh=$hour                            \
+                     '{d=int($1/86400); print "'$f'", $1, \
+                      int($1)%86400<(h*3600) ? d-1 : d }'
+       done)
+
+
+
+
+
+# To see the result of the step above, uncomment the next line. You
+# can use a similar line to inspect the steps for later variables also
+# (just changing the variable name). IMPORTANT NOTE: Just don't forget
+# the double-quotes around the variable name, otherwise the lines
+# won't be separated.
+#echo "$list"; exit 1
+
+
+
+
+
+# Get the uniqe nights from the previous step.
+unique=$(echo "$list" | awk '{print $3}' | sort | uniq | cat -n)
+
+
+
+
+
+# Find the FITS files of every unique day and sort them by observing
+# time within that day. We'll also initialize the night-counter to 1.
+counter=1
+echo "$unique" | while read l; do
+
+    # Find all input files (and their Unix epoch time) that corr
+    daynum_to=$(echo $l | awk '{print $1}')
+    daynum_from=$(echo $l | awk '{print $2}')
+    in_this_day=$(echo "$list" \
+                     | awk -vf=$daynum_from -vt=$daynum_to \
+                           '$3==f {print $1, $2}' \
+                     | sort -nk2 \
+                     | cat -n \
+                     | awk -vd=$counter '{print $2,d,$1}')
+
+    # Make a link to each file (containing the day number and image
+    # number in that day).
+    echo "$in_this_day" | while read L; do
+
+        # Set the necessary numbers.
+        infile=$(echo $L | awk '{print $1}')
+        night_num=$(echo $L | awk '{print $2}')
+        exposure_num=$(echo $L | awk '{print $3}')
+
+        # Make the outputs
+        outfile=$prefix"n"$night_num-$exposure_num.fits
+        if   [ $copy = 1 ]; then   cp $infile $outfile
+        elif [ $link = 1 ]; then   ln -fs $infile $outfile
+        else                       echo "$infile $night_num $exposure_num"
+        fi
+
+    done
+
+    # Increment the night-counter.
+    ((counter++))
+done
diff --git a/configure.ac b/configure.ac
index 9318393..ee6654a 100644
--- a/configure.ac
+++ b/configure.ac
@@ -804,6 +804,7 @@ AC_CONFIG_FILES([Makefile
                  bin/table/Makefile
                  bin/match/Makefile
                  bin/mkprof/Makefile
+                 bin/script/Makefile
                  bin/mknoise/Makefile
                  bin/segment/Makefile
                  bin/convertt/Makefile
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8929b31..6cdeef6 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -137,7 +137,7 @@ dist_man_MANS = $(MAYBE_ARITHMETIC_MAN) 
$(MAYBE_BUILDPROG_MAN)          \
   $(MAYBE_CROP_MAN) $(MAYBE_FITS_MAN) $(MAYBE_MATCH_MAN)                \
   $(MAYBE_MKCATALOG_MAN) $(MAYBE_MKNOISE_MAN) $(MAYBE_MKPROF_MAN)       \
   $(MAYBE_NOISECHISEL_MAN) $(MAYBE_SEGMENT_MAN) $(MAYBE_STATISTICS_MAN) \
-  $(MAYBE_TABLE_MAN) $(MAYBE_WARP_MAN)
+  $(MAYBE_TABLE_MAN) $(MAYBE_WARP_MAN) man/astscript-sort-by-night.1
 
 
 ## See if help2man is present or not. When help2man doesn't exist, we don't
@@ -203,6 +203,11 @@ man/astnoisechisel.1: $(top_srcdir)/bin/noisechisel/args.h 
 $(ALLMANSDEP)
        $(MAYBE_HELP2MAN) -n "detect signal in a noisy image"              \
                          --libtool $(toputildir)/noisechisel/astnoisechisel
 
+man/astscript-sort-by-night.1: $(top_srcdir)/bin/script/sort-by-night.in   \
+                               $(ALLMANSDEP)
+       $(MAYBE_HELP2MAN) -n "Sort input FITS files by night"              \
+                         --libtool $(toputildir)/script/astscript-sort-by-night
+
 man/astsegment.1: $(top_srcdir)/bin/segment/args.h  $(ALLMANSDEP)
        $(MAYBE_HELP2MAN) -n "segmentation based on signal structure"      \
                          --libtool $(toputildir)/segment/astsegment
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index d86077d..43c1b8d 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -99,6 +99,8 @@ License''.
 * Warp: (gnuastro)Warp. Warp a dataset to a new grid.
 * astwarp: (gnuastro)Invoking astwarp. Options to Warp.
 
+* astscript-sort-by-night: (gnuastro)Invoking astscript-sort-by-night. Options 
to this script
+
 @end direntry
 
 
@@ -203,6 +205,7 @@ sub-component to a title is present.
 * Data analysis::               Analyze images.
 * Modeling and fittings::       Make and fit models.
 * High-level calculations::     Physical calculations.
+* Installed scripts::           Higher-level usage of (multiple) programs.
 * Library::                     Gnuastro's library of useful functions.
 * Developing::                  The development environment.
 * Gnuastro programs list::      List and short summary of Gnuastro.
@@ -547,6 +550,14 @@ Invoking CosmicCalculator
 * CosmicCalculator input options::  Options to specify input conditions.
 * CosmicCalculator specific calculations::  Requesting specific outputs.
 
+Installed scripts
+
+* Sort FITS files by night::
+
+Sort FITS files by night
+
+* Invoking astscript-sort-by-night::  Inputs and outputs to this script.
+
 Library
 
 * Review of library fundamentals::  Guide on libraries and linking.
@@ -10488,7 +10499,8 @@ continue with the rest of actions.
 @item -s STR
 @itemx --datetosec STR
 @cindex Unix epoch time
address@hidden Epoch time, Unix
address@hidden Time, Unix epoch
address@hidden Epoch, Unix time
 Interpret the value of the given keyword in the FITS date format (most
 generally: @code{YYYY-MM-DDThh:mm:ss.ddd...}) and return the corresponding
 Unix epoch time (number of seconds that have passed since 00:00:00
@@ -21740,7 +21752,7 @@ were of integer types.
 
 
 
address@hidden High-level calculations, Library, Modeling and fittings, Top
address@hidden High-level calculations, Installed scripts, Modeling and 
fittings, Top
 @chapter High-level calculations
 
 After the reduction of raw data (for example with the programs in @ref{Data
@@ -22304,8 +22316,212 @@ redshift based on the input parameters.
 
 
 
address@hidden Installed scripts, Library, High-level calculations, Top
address@hidden Installed scripts
+
+Gnuastro's programs (introduced in previous chapters) are designed to be
+highly modular and thus mainly contain lower-level operations on the
+data. However, in many contexts, higher-level operations (for example a
+sequence of calls to multiple Gnuastro programs, or a special way of
+running a program and using the outputs) are also very similar between
+various projects.
+
+To facilitate data analysis on these higher-level steps also, Gnuastro also
+installs some scripts on your system with the (@code{astscript-}) prefix
+(in contrast to the other programs that only have the @code{ast}
+prefix). In this chapter, these scripts and their usage details are
+described.
+
address@hidden GNU Bash
+Like all of Gnuastro's source code, these scripts are also heavily
+commented. They are written in GNU Bash, which doesn't need compilation (so
+they are actually human-readable), and is the same language that is mainly
+used when typing on the command-line. Because of these factors, Bash is
+much more widely known and used than C (the language of other Gnuastro
+programs). They also do higher-level operations, so customizing these
+scripts for a special project will be more common than the programs. You
+can always inspect them (to customize, check, or educate your self) with
+this command (just replace @code{emacs} with your favorite text editor):
+
address@hidden
+$ emacs $(which astscript-NAME)
address@hidden example
+
+These scripts also accept options and are in many ways similar to the
+programs (see @ref{Common options}) with some minor differences:
+
address@hidden
address@hidden
+Currently they don't accept configuration files themselves. However, the
+configuration files of the Gnuastro programs they call are indeed parsed
+and used by those programs.
+
+As a result, they don't have the following options: @option{--checkconfig},
address@hidden, @option{--lastconfig}, @option{--onlyversion},
address@hidden, @option{--setdirconf} and @option{--setusrconf}.
+
address@hidden
+They don't directly allocate any memory, so there is no
address@hidden
+
address@hidden
+They don't have an independent @option{--usage} option: when called with
address@hidden, they just recommend running @option{--help}.
+
address@hidden
+The output of @option{--help} is not configurable like the programs (see
address@hidden).
+
address@hidden itemize
+
address@hidden
+* Sort FITS files by night::
address@hidden menu
+
address@hidden Sort FITS files by night,  , Installed scripts, Installed scripts
address@hidden Sort FITS files by night
+
address@hidden Calendar
+FITS images usually contain (several) keywords for preserving important
+dates. In particular, for lower-level data, this is usually the observation
+date and time (for example, stored in the @code{DATE-OBS} keyword
+value). When analyzing observed datasets, many calibration steps (like the
+dark, bias or flat-field), are commonly calculated on a per-observing-night
+basis.
+
+However, the FITS standard's date format (@code{YYYY-MM-DDThh:mm:ss.ddd})
+is based on the western (Gregorian) calendar. Dates that are stored in this
+format are complicated for automatic processing: a night starts in the
+final hours of one calendar day, and extends to the early hours of the next
+calendar day. As a result, to identify datasets from one night, we commonly
+need to search for two dates. However calendar peculiarites can make this
+identification very difficult. For example when an observation is done on
+the night separating two months (like the night starting on March 31st and
+going into April 1st), or two years (like the night starting on December
+31st 2018 and going into January 1st, 2019). To account for such
+situations, it is necessary to keep track of how many days are in a month,
+and leap years, and etc.
+
address@hidden Unix epoch time
address@hidden Time, Unix epoch
address@hidden Epoch, Unix time
+Gnuastro's @file{astscript-sort-by-night} script is created to help in such
+important scenarios. It uses @ref{Fits} to convert the FITS date format
+into the Unix epoch time (number of seconds since 00:00:00 of January 1st,
+1970), using the @option{--datetosec} option. The Unix epoch time is a
+single number (integer, if not given in sub-second precision), enabling
+easy comparison and sorting of dates after January 1st, 1970.
+
address@hidden
+* Invoking astscript-sort-by-night::  Inputs and outputs to this script.
address@hidden menu
+
address@hidden Invoking astscript-sort-by-night,  , Sort FITS files by night, 
Sort FITS files by night
address@hidden Invoking astscript-sort-by-night
+
+This script will read a FITS date formatted value from the given keyword,
+and classify the input FITS files into individual nights. This script can
+be used with the following general template:
+
address@hidden
+$ astscript-sort-by-night [OPTION...] FITS-files
address@hidden example
+
address@hidden
+One line examples:
+
address@hidden
+## Use the DATE-OBS keyword
+$ astscript-sort-by-night --key=DATE-OBS /path/to/data/*.fits
+
+## Make links to the input files with the `img-' prefix
+$ astscript-sort-by-night --link --prefix=img- /path/to/data/*.fits
address@hidden example
+
+This script will look into a HDU/extension (@option{--hdu}) for a keyword
+(@option{--key}) in the given FITS files and interpret the value as a
+date. The inputs will be separated by "night"s (9:00a.m to next day's
+8:59:59a.m, spanning two calendar days, exact hour can be set with
address@hidden).
+
+The output is a list of all the input files along with the following two
+columns: night number and file number in that night (sorted by time). With
address@hidden a symbolic link will be made (one for each input). The
+link's name is composed of a prefix (@option{--prefix}) and also contains
+the night number, and number of file in that night (sorted by time). When
address@hidden is used instead of a link, a copy of the inputs will be
+made instead of linking.
+
+Below you can see one example where all the @file{target-*.fits} files in
+the @file{data} directory should be separated by observing night according
+to the @code{DATE-OBS} keyword value in their second extension (number
address@hidden, recall that HDU counting starts from 0). You can see the output
+after the @code{ls} command. The outputs can be placed in a different
+(already existing) directory by including that directory's name in the
address@hidden value, for example @option{--prefix=sorted/img-} will put
+them all under the @file{sorted} directory.
+
address@hidden
+$ astscript-sort-by-night -pimg- -h1 -kDATE-OBS data/target-*.fits
+$ ls
+img-n1-1.fits img-n1-2.fits img-n3-1.fits ...
address@hidden example
+
+This script can be configured like all Gnuastro's programs (through
+command-line options, see @ref{Common options}), with some minor
+differences that are described in @ref{Installed scripts}. The particular
+options to this script are listed below:
+
address@hidden @option
address@hidden -h STR
address@hidden --hdu=STR
+The HDU/extension to use in all the given FITS files. All of the given FITS
+files must have this extension.
+
address@hidden -k STR
address@hidden --key=STR
+The keyword name that contains the FITS date format to classify/sort by.
+
address@hidden -h FLT
address@hidden --hour=FLT
+The hour that defines the next ``night''. By default, all times before
+9:00a.m are considered to belong to the previous calendar night. If a
+sub-hour value is necessary, it should be given in units of hours, for
+example @option{--hour=9.5} corresponds to 9:30a.m.
+
address@hidden -l
address@hidden --link
+Create a symbolic link for each input FITS file, but with a standard naming
+convention, including a possible prefix, night identifier, and a unique
+counter for each file (sorted by time). This option cannot be used with
address@hidden
+
address@hidden -c
address@hidden --copy
+Make a copy of each input FITS file with a standard naming convention,
+including a possible prefix, night identifier, and a unique counter for
+each file (sorted by time). This option cannot be used with
address@hidden
+
address@hidden -p STR
address@hidden --prefix=STR
+Prefix to append before the night-identifier of each newly created link or
+copy (with the @option{--copy} or @option{--link}
+options). @option{--prefix} can be used to store the files in another
+directory relative to the directory this script is being run (it must
+already exist).
address@hidden table
+
+
+
+
+
+
+
+
+
 
address@hidden Library, Developing, High-level calculations, Top
address@hidden Library, Developing, Installed scripts, Top
 @chapter Library
 
 Each program in Gnuastro that was discussed in the prior chapters (or any