1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
|
#! /bin/bash
# Prepare all Gnuastro webpages in a temporary directory, move the updated
# files to the destination directory (local CVS checkout) and commit the
# changes to the gnu.org/software/gnuastro webpage. Finally, delete the
# temporary directory. See below for setting up the CVS checkout for the
# first time. NOTE: This script is defined to be run in Gnuastro's 'doc/'
# directory. It should not be called from anywhere else.
#
# # IMPORTANT: do not end the destination directory with a '/'.
# ./forwebpage /destination/directory
#
# The temporary directory will be named '/destination/directory_tmp'.
#
# This script will first run gendocs.sh on the Texinfo source which creates
# the standrard GNU webpage style documentation page. Then it does some
# modifications to the HTMLs produced:
#
# 1. Add a CSS sytlesheet.
# 2. Add MathJax.
# 3. Add a "GNU Astronomy Utilities manual" title on the top.
# 4. Add a link to read in different formats in the bottom.
# 5. If MathJax was used in a page, add a link to Javascript.html
# 6. Add a link to the main Gnuastro webpage on the bottom.
# 7. Remove the border from cartouche in the HTML.
#
# After making all these changes, it copies all the necessry files in
# in the folder that will be linked to the GNU servers and it will run
# CVS to upload them there.
#
#
# NOTE FOR FIRST TIME
# -------------------
#
# The GNU webpage is version controlled by CVS and operates based on
# it. CVS is no longer popular anymore, but the commands below should
# be enough for the initial setup. Afterwards, you can just run this
# script.
#
# 1. Add 'export CVS_RSH=ssh' to your ~/.bashrc
#
# 2. Choose the top directory to keep your local copy of the webpage
# (TOPWEBCHECKOUT). Note that especially because of MathJax,
# there are a HUGE number of files and since everything is
# generated from the single gnuastro.texi file, there is no need
# to take up your backup space. So you can put that directory in
# some directory that is not backed up, it can be anywhere.
#
# 3. Make a directory to keep the copy of the webpage.
# $ mkdir $TOPWEBCHECKOUT
#
# 4. Set the CVSROOT environment variable, just replace SAVANNAHID
# with your Savannah ID, it will use the key you have registered
# on Savannah for authentication.
# $ export CVSROOT=:ext:SAVANNAHID@cvs.sv.gnu.org:/web/gnuastro
#
# 5. Checkout a copy of the webpage:
# $ cvs checkout ./
#
#
# New pages
# ---------
#
# When a new page is added, after all the "cvs commit: Examining ..."
# reports, you will see a line for each new file starting with a
# '?'. Assume FILES is a string of all these files (that have a '?' in
# the CVS commit of this script). Run these commands to go into your
# local checkout and add those files to the repository.
#
# $ cd $TOPWEBCHECKOUT/gnuastro
# $ cvs add FILES
# $ cvs commit -m "New file added"
#
#"
#
# Original author:
# Mohammad Akhlaghi <mohammad@akhlaghi.org>
# Contributing author(s):
# Copyright (C) 2016-2023 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/>.
# Initial settings:
set -o nounset # Stop if a variable is not set.
set -o errexit # Stop if a program returns false.
# For the permissions of the output:
umask 002
# Set the temporary directory name:
tmpdir=$1_tmp
# Top CVS (webpage checkout) copy
topwebcheckout=$1
# Set the title value
booktitle="GNU Astronomy Utilities"
# Get the version of the manual:
version=$(awk '$2=="VERSION" {print $3}' version.texi)
# If the temporary directory already exists, warn the user and abort.
# gendocs.sh will write everything there and we want everything there to be
# freshly created.
if [ -d $tmpdir ]; then
echo; echo "$tmpdir exists!"
echo "Please delete it or specify another directory."
echo; echo "To delete it you can run: 'rm -rf $tmpdir'"
exit 1
fi
# The date that is printed on the manual is generated by looking at the
# modification time of gnuastro.texi, not '../configure' (which was used to
# generate the version number). This can cause confusion, since the version
# number (coming from the commit) will have a different date in the
# revision history. To avoid this, here we check if the '../configure'
# modification date is similar to that on 'gnuastro.texi' or not. If it
# isn't a warning error is printed to let the user know, so they take the
# appropriate action.
cdate=$(../bootstrapped/build-aux/mdate-sh ../configure)
tdate=$(../bootstrapped/build-aux/mdate-sh ./gnuastro.texi)
if [ "$cdate" != "$tdate" ]; then
cat <<EOF
Different ../configure and ./gnuastro.texi modification dates
=============================================================
The version number printed on the manual was generated with ../configure,
however the date (that is printed beside the version number) comes from the
last modification date of ./gnuastro.texi. This can cause confusion if it
is put on the webpage like this!
So please resolve this conflict!
If everything is OK and "autoconf -f" or bootstrapping was done today, you
can run "touch ./gnuastro.texi" to give it the current modification date. If
not, please regenerate ./configure (with autoconf -f) and run "make
distcheck" (to see if everything is working), then "touch
./gnuastro.texi" to upload the documentation to the webpage.
The webpage is the official place for the manual and it is very important
that it does not cause confusions for readers who are not too familiar with
the inner workings of these scripts.
EOF
exit 1
fi
# This is run to make sure if all the GNU Build System files (like
# stamp-vti) are up to date.
make
# Run gendocs.sh to generate all the files:
../bootstrapped/build-aux/gendocs.sh --email bug-gnuastro@gnu.org gnuastro \
"$booktitle" --html " " -o $tmpdir \
-I ../bootstrapped/doc \
-I ../bootstrapped/build-aux
# Delete all the temporary files that gendocs.sh left behind
rm -f gnuastro.aux gnuastro.cp gnuastro.cps gnuastro.fn gnuastro.ky \
gnuastro.log gnuastro.pg gnuastro.toc gnuastro.tp gnuastro.vr \
gnuastro.vrs gnuastro.fns gnuastro.tps
# Copy the two necessary files in the manual directory:
cp javascript.html style.css fonts.css $tmpdir/
# Get the current month to put under all the pages.
thismonth=$(date +"%B %Y")
# The "Internal Field Separator" (IFS) is used to split words and lines
# after expansions. In the process of correcting the HTMLs, we need to
# remove any field separator for the script to work correctly, so we set
# IFS to nothing (''). However, later on we will be needing the default
# values in finding the proper files that have been updated, so we keep the
# old value in a variable to reset it again later.
OLDIFS=$IFS
IFS=''
# Make the proper corrections to the HTML files:
echo
echo %%%%% Correcting the HTMLs %%%%%
# Correct the address of the '(dir)' links on the top pages of both
# HTML outputs. In the $tmpdir/gnuastro.html, it is 'dir.html#top'
# which should be change to index.html. In
# $tmpdir/html_node/index.html, it is '../dir/index.html' which
# should become ../index.html
cat $tmpdir/gnuastro.html | sed s/dir\.html\#Top/index.html/g > tmp.txt
mv tmp.txt $tmpdir/gnuastro.html
cat $tmpdir/html_node/index.html | sed -e 's/\/dir\//\//g' > tmp.txt
mv tmp.txt $tmpdir/html_node/index.html
if [ -f tmp.html ]; then rm tmp.html; fi
for file in $tmpdir/gnuastro.html $tmpdir/html_node/*.html
do
if grep -q '\\(\|$$' "$file";
then hasjavascript="yes"
else hasjavascript="no"
fi
if [ "$file" != $tmpdir/gnuastro.html ] && [ "$file" != $tmpdir/html_node/index.html ];
then addtitle="yes"
else addtitle="no"
fi
while read -r line; do
# Actions that must be done before a given line:
if [ "$line" = "</head>" ]; then
if [ "$file" = $tmpdir/gnuastro.html ]; then
cssbase="./"
jsbase="../"
else
cssbase="../"
jsbase="../../"
fi
echo "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">" >> tmp.html
echo "<link rel=\"stylesheet\" type=\"text/css\" href=\""$cssbase"fonts.css\">" >> tmp.html
echo "<link rel=\"stylesheet\" type=\"text/css\" href=\""$cssbase"style.css\">" >> tmp.html
if [ $hasjavascript = "yes" ]; then
echo "<script src=\""$jsbase"MathJax/MathJax.js?config=TeX-AMS_HTML\"></script>" >> tmp.html
echo "" >> tmp.html
fi
fi
if [ "$line" = "</body>" ]; then
# Put a blank line to finish the main body of the page.
echo "<hr>" >> tmp.html
# Add a notice in case Javascript is disabled.
if [ $hasjavascript = "yes" ]; then
echo "" >> tmp.html
echo "<noscript>" >> tmp.html
echo "<table class=\"cartouche\" style=\"background-color:#FF9912;\"><tr><td><p>" >> tmp.html
echo "<b>Warning:</b> This page uses <a href=\"http://www.mathjax.org/\">MathJax</a>" >> tmp.html
echo "to render TeX equations. MathJax requires JavaScript for the rendering." >> tmp.html
echo "However, scripts are disabled." >> tmp.html
echo "<br /><br />" >> tmp.html
echo "To see the equations, you can either use <a href=\"https://www.gnu.org/software/librejs/\">LibreJS</a>" >> tmp.html
echo "to allow trusted scripts, or get the full manual in <a href=\""$cssbase"gnuastro.pdf\">PDF</a>." >> tmp.html
echo "</p></td></tr></table>" >> tmp.html
echo "</noscript>" >> tmp.html
echo "" >> tmp.html
fi
# Add "Read in other formats":
echo "<p class=\"bottom-links\"><a href=\"https://www.gnu.org/software/gnuastro/manual/index.html\">Read in other formats</a>.</p>" >> tmp.html
# If there is any Javascript in the page, then let the users know.
if [ $hasjavascript = "yes" ]; then
echo "<p class=\"bottom-links\"><a href=\"https://www.gnu.org/software/gnuastro/manual/javascript.html\" rel=\"jslicense\">JavaScript license information</a></p>" >> tmp.html
fi
# Put a link to the main Gnuastro webpage.
echo "<p class=\"bottom-links\"><a href=\"https://www.gnu.org/software/gnuastro/index.html\">GNU Astronomy Utilities</a> $version manual, $thismonth.</p>" >> tmp.html
fi
#Do any modifications to the line:
temp1=${line:0:5}
if [ "$temp1" = "<tabl" ]; then
temp2=$(echo "$line" | sed -e "s/class=\"cartouche\" border=\"1\"/class=\"cartouche\"/")
line=$temp2
fi
# Add the line:
echo $line >> tmp.html
# Actions after a given line:
if [ "$temp1" = "<body" ]; then
# Add a title.
if [ $addtitle = "yes" ]; then
echo "<h2>$booktitle</h2>" >> tmp.html
echo "<hr>" >> tmp.html
fi
fi
done < "$file"
mv tmp.html "$file"
done
echo %%%%% DONE %%%%%
# Copy 'gnuastro.en.html' page into 'index.html'. Then copy the other
# necessary webpage files.
cp gnuastro.en.html $topwebcheckout/gnuastro/gnuastro.html
cp gnuastro.fr.html gnuastro.translist $topwebcheckout/gnuastro/
# 'index.html' must be just a symbolic to 'gnuastro.html'. In case this is
# the first time, CVS might have downloaded a full file and not the
# link. To be safe, we'll just delete index.html and build a new symbolic
# link.
rm -f $topwebcheckout/gnuastro/index.html
ln -s $topwebcheckout/gnuastro/gnuastro.html $topwebcheckout/gnuastro/index.html
# Copy the generated files to the proper directory. Note that the majority
# of the HTML files in 'html_node' have not changed, so CVS doesn't check
# for the file contents, and so will update everything that is copied,
# therefore we only want to copy the files that have actually changed. But
# first, reset the IFS variable to its default value.
#
# Note that gendocs automatically puts a version number in the comments of
# the generated HTML files. This creates a difference even if
IFS=$OLDIFS
echo; echo; echo; echo "diff results:"
for filename in $(find $tmpdir/ -type f -print)
do
# realpath is part of GNU Coreutils.
relname=$(realpath $filename --relative-to=$tmpdir)
if ! diff $filename $topwebcheckout/gnuastro/manual/$relname \
-I '<!-- This book documents version'; then
cp $filename $topwebcheckout/gnuastro/manual/$relname;
echo "$relname:"
echo " -- Copied to for upload"
fi
done
# Remove the temporary manual directory, since it isn't needed any more.
rm -rf $tmpdir
# Go into the top CVS directory, and commit the new changes to the GNU
# server.
cd $topwebcheckout/gnuastro/
cvs commit -m "Update"
|