[gnuastro-commits] master 281aae1: Book: added another useful example for --keyvalue

[Mohammad Akhlaghi]

branch: master
commit 281aae13b3a746f29f93636d2ce13152e90c0e87
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Book: added another useful example for --keyvalue
    
    Recently the '--keyvalue' option was added to the Fits program. However,
    all the examples had a simple '*.fits' which is only good for the files in
    the current directory.
    
    With this commit, a new paragraph has been added to the description of this
    option with an example of using the 'find' program for searching all FITS
    files in the sub-directories of a certain directory.
---
 doc/gnuastro.texi | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index b0daca5..02be9c2 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -8978,6 +8978,15 @@ image-b.fits
 Note that @option{--colinfoinstdout} is necessary to use column names in the 
subsequent @command{asttable} command.
 Also, with the @option{-cFILENAME} option, we are asking Table to only print 
the final file names (we don't need the sizes any more).
 
+The commands with multiple files above used @file{*.fits}, which is only 
useful when all your FITS files are in the same directory.
+However, in many cases, your FITS files will be scattered in multiple 
sub-directories of a certain top-level directory, or you may only want those 
with more particular file name patterns.
+A more powerful way to list the input files to @option{--keyvalue} is to use 
the @command{find} program in Unix-like operating systems.
+For example, with the command below you can search all the FITS files in all 
the sub-directories of @file{/TOP/DIR}.
+
+@example
+astfits $(find /TOP/DIR/ -name "*.fits") --keyvalue=NAXIS2
+@end example
+
 @item -O
 @itemx --colinfoinstdout
 Print column information (or metadata) above the column values when writing 
keyword values to standard output with @option{--keyvalue}.