[gnuastro-commits] master a57cbe3: Book: added notice on single-quotes for PDF outputs

[Mohammad Akhlaghi]

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

    Book: added notice on single-quotes for PDF outputs
    
    Until now, we hadn't explicitly mentioned reminded readers that the printed
    single quote in PDF manual is the wrong character to write or to
    copy-paste.
    
    With this commit, a cartouche box has been added on top of the first AWK
    command in the manual where they occur to remind unsuspecting new
    users. Also an explanation has been added in the "Conventions" section of
    the first chapter.
    
    This issue was reported by Sepideh Eskandarlou.
---
 doc/gnuastro.texi | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 41c5d64..79964a2 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -1401,6 +1401,10 @@ When it is a last character in a line (the next 
character is a new-line characte
 
 @end itemize
 
+This is not a convention, but a bi-product of the PDF building process of the 
manual:
+In the PDF version of this manual, a single quote (or apostrophe) character in 
the commands or codes is shown like this: @code{'}.
+Single quotes are sometimes necessary in combination with commands like 
@code{awk} or @code{sed}, or when using Column arithmetic in Gnuastro's own 
Table (see @ref{Column arithmetic}).
+Therefore when typing (recommended) or copy-pasting (not recommented) the 
commands that have a @code{'}, please correct it to the single-quote (or 
apostrophe) character, otherwise the command will fail.
 
 
 @node Acknowledgments,  , Conventions, Introduction
@@ -2243,6 +2247,15 @@ The second row is the coverage range along RA and Dec 
(compare with the outputs
 We can thus simply subtract the second from the first column and multiply it 
with the difference of the fourth and third columns to calculate the image area.
 We'll also multiply each by 60 to have the area in arc-minutes squared.
 
+@iftex
+@cartouche
+@noindent
+@strong{Single quotes in PDF format:} in the PDF version of this manual, a 
single quote (or apostrophe) character in the commands or codes is shown like 
this: @code{'}.
+Single quotes are sometimes necessary in combination with commands like 
@code{awk} or @code{sed} (like the command below), or when using Column 
arithmetic in Gnuastro's own Table (see @ref{Column arithmetic}).
+Therefore when typing (recommended) or copy-pasting (not recommented) the 
commands that have a @code{'}, please correct it to the single-quote (or 
apostrophe) character, otherwise the command will fail.
+@end cartouche
+@end iftex
+
 @example
 astfits flat-ir/xdf-f160w.fits --skycoverage --quiet \
         | awk 'NR==2@{print ($2-$1)*60*($4-$3)*60@}'