Debian Codegraph @

docs/manual/make_docs

raw
1 #!/bin/sh
2
3 use_chapters="1"
4 source_xml_dir="chapters/"
5 format=""
6 format_flag=""
7 xsl=""
8 clean="yes"
9 paramtables="yes"
10 targetopt=""
11 base_path=$PWD
12 chapter_mask="*.xml"
13 mod_chapter_mask="mod_*.xml"
14 bookstub="userguide"
15 bookname="magics_"$bookstub
16 bookid="Magics_$bookstub"
17 bookidopt=""
18 netvalid="--nonet"
19 targetdocopt=""
20 targetopt=""
21 verboseopt="-q"
22 verbose="0"
23
24
25 # first check whether the required xsl links are in the xsl directory.
26
27 if [[ ! -d xsl/docbook-base || ! -d xsl/docbook-xsl ]]
28 then
29 echo ""
30 echo "ERROR: Symbolic links xsl/docbook-base and xsl/docbook-xsl MUST exist before document generation can begin"
31 echo ""
32 exit 1
33 fi
34
35
36 for arg;do
37 if [[ $arg = "-h" || $arg = "-help" || $arg = "--help" ]]
38 then
39 echo ""
40 echo "make_docs"
41 echo "Possible options:"
42 echo " -html : resultant output in HTML"
43 echo " -pdf : resultant output in PDF"
44 echo " -noclean : do not remove temporary files after build"
45 echo " -notables : do not generate new parameter tables"
46 echo " -netvalid : validate using Internet connection for DTDs, etc"
47 echo " -v : verbose output"
48 echo " -v2 : very verbose output"
49 echo " -targets : generate link targets"
50 echo " -book=<name> : only generate the specified book (name, no extension or path)"
51 echo " - default is magics_userguide"
52 echo " - possible values are:"
53 echo "`ls books`"
54 echo ""
55 exit
56 fi
57
58 if [[ $arg = "-html" ]]
59 then
60 format="html"
61 format_flag="html"
62 xsl="xsl/html.xsl"
63 use_chapters="0"
64 source_xml_dir="books/"
65 fi
66
67 if [[ $arg = "-pdf" ]]
68 then
69 format="pdf"
70 format_flag="pdf"
71 xsl="xsl/pdf.xsl"
72 fi
73
74 if [[ $arg = "-noclean" ]]
75 then
76 clean="no"
77 echo "-noclean: will not delete temporary files"
78 fi
79
80 if [[ $arg = "-notables" ]]
81 then
82 paramtables="no"
83 fi
84
85 if [[ $arg = "-netvalid" ]]
86 then
87 netvalid=""
88 fi
89
90 if [[ $arg = "-v" ]]
91 then
92 verboseopt="-v"
93 extra_fop_flags=""
94 extra_xslt_flags=""
95 verbose="1"
96 fi
97
98 if [[ $arg = "-v2" ]]
99 then
100 extra_fop_flags="-d"
101 extra_xslt_flags="-v"
102 verbose="1"
103 fi
104
105 if [[ $arg = "-targets" ]]
106 then
107 targetopt="-T ../targets/${bookname}_${format}_target.db"
108 fi
109
110 if [[ ${arg:0:6} = "-book=" ]]
111 then
112 bookname=${arg:6:40} # substring, starting at index 6 (0 is first), length 40
113 echo "Processing book _${bookname}_"
114 bookid="M${arg:7:40}" # change magics into Magics
115
116 # perform some clever sleight-of-hand here - newer versions of xsl stylesheets seem to have a problem
117 # when processing the book - therefore we have the option here to actually use the chapter instead.
118
119 if [[ $use_chapters = "1" ]]
120 then
121
122 # bookname is something like 'magics_drivers' - the corresponding chapter would just be 'drivers'
123 bookname=${bookname:7:40} # substring, starting at index 7 (0 is first), length 40
124 fi
125 fi
126 done
127
128
129 if [[ $arg = "" ]]
130 then
131 echo "No output format set - use 'make_docs -h' for help"
132 exit
133 fi
134
135
136 # if the book does not exist, then exit gracefully
137 #if [[ ! -a books/$bookname.xml ]]
138 #then
139 # echo ""
140 # echo "ERROR - book 'books/$bookname.xml' does not exist."
141 # echo "- did you mean '-book=magics_$bookname'?"
142 # echo ""
143 # exit
144 #fi
145
146
147
148 # create any directories that do not already exist
149
150 mkdir -p paramtables
151 mkdir -p publish/html
152 mkdir -p publish/pdf
153 mkdir -p publish/html/images/c
154 mkdir -p publish/html/images/fortran
155 mkdir -p publish/html/images/magml
156 mkdir -p publish/html/images/python
157 mkdir -p publish/html/images/diagrams
158
159
160 # read the most up-to-date Magics++ version information
161 # - we want MAGICS_PACKAGE_VERSION and MAGICS_PACKAGE_COPYRIGHT_PERIOD.
162
163 . ../../version.sh
164
165
166 # generate parameter tables?
167
168 if [[ $paramtables = "yes" ]]
169 then
170 tools/generate_param_tables.pl
171 tools/generate_magml_tables.pl
172 fi
173
174
175 mod_bookname="mod_$bookname"
176
177 if [[ $use_chapters -eq "0" ]] # using a 'book' instead of a 'chapter'
178 then
179 # we're going to make modified copies of the source xml chapter files,
180 # so we create a copy of the book file and replace the chapter references with
181 # references to the modified chapter files.
182 # For example, chapters/intro.xml will become chapters/mod_intro.xml.
183
184 sed "s/chapters\/\(.*\).xml/chapters\/mod_\1.xml/g" books/$bookname.xml > tempbook.xml
185 mv tempbook.xml books/$mod_bookname.xml
186
187 # for the purpose of generating nice olink text in the PDF documents, we need
188 # for each book to have a title. However, this will be the same as the chapter
189 # title and so we should get rid of it when actually generating the PDFs.
190
191 if [[ $targetopt = "" ]]
192 then
193 sed "s/<title>[^<]*<\/title>//g" books/$mod_bookname.xml > tempbook.xml
194 mv tempbook.xml books/$mod_bookname.xml
195 fi
196
197 chmod u+w books/$mod_bookname.xml
198 fi
199
200
201 # we're going to mess around with the source xml files a little, so let's
202 # make backups of them before we begin... we'll move them back once we're finished.
203
204 for chapfile in chapters/$chapter_mask
205 do
206 bname=`basename $chapfile .xml`
207 modchapfile="chapters/mod_$bname.xml"
208
209 cp -p $chapfile $modchapfile
210 chmod u+w $modchapfile
211 done
212
213
214
215 # trying to get XSL to put figures at the top of a new page has proved
216 # not-entirely-possible and very time-consuming. Let's do it here instead...
217 #
218 #figure_plain="<figure>"
219 #figure_with_break="<\?pagebreak\?><figure>"
220 #slash_figure_plain="<\/figure>"
221 #slash_figure_with_break="<\/figure><\?pagebreak\?>"
222 #
223 #
224 #if [[ $format = "pdf" ]]
225 #then
226 # for chapfile in chapters/$mod_chapter_mask
227 # do
228 # sed "s/$figure_plain/$figure_with_break/g" $chapfile > temp1.xml
229 # sed "s/$slash_figure_plain/$slash_figure_with_break/g" temp1.xml > temp2.xml
230 # mv temp2.xml $chapfile
231 # rm -f temp1.xml
232 # done
233 #fi
234
235
236
237
238 # xxe and xerces have different opinions on how to handle relative includes
239 # so we keep the include paths in the format that xxe likes while we're editing
240 # and then switch them to 'xerces mode' before publishing.
241 # We will then switch them back afterwards (see later in the script).
242
243 # for chapfile in chapters/$mod_chapter_mask
244 # do
245 # sed 's/xxxinclude href="..\/examples/include href="examples/g' $chapfile > temp1.xml
246 # sed 's/xxxinclude href="..\/paramtables/include href="paramtables/g' temp1.xml > temp2.xml
247 # sed 's/xxxinclude href="..\/phrases/include href="phrases/g' temp2.xml > temp3.xml
248 # mv temp3.xml $chapfile
249 # rm -f temp1.xml temp2.xml
250 # done
251
252
253 # we want to dynamically insert the publication date. We do this with a search/replace
254 # operation. <pubdate>auto</pubdate> is replaced with <pubdate>...</pubdate> where
255 # '...' is the current date.
256
257 today=`date +"%d %B %Y"`
258
259 sed "s/<pubdate>auto<\/pubdate>/<pubdate>$today<\/pubdate>/g" phrases/chapterinfo.xml > phrases/chapterinfo_mod.xml
260 cp phrases/chapterinfo_mod.xml phrases/chapterinfo_temp.xml
261 sed "s/MAGICS_VERSION/$MAGICS_PACKAGE_VERSION/g" phrases/chapterinfo_temp.xml > phrases/chapterinfo_mod.xml
262 cp phrases/chapterinfo_mod.xml phrases/chapterinfo_temp.xml
263 sed "s/MAGICS_COPYRIGHT_PERIOD/$MAGICS_PACKAGE_COPYRIGHT_PERIOD/g" phrases/chapterinfo_temp.xml > phrases/chapterinfo_mod.xml
264
265
266 # we also need a corresponding appendixinfo element for any appendices
267
268 sed "s/chapterinfo/appendixinfo/g" phrases/chapterinfo_mod.xml > phrases/appendixinfo_mod.xml
269
270
271 # we also want to dynamically insert the date into the footer of each HTML page,
272 # done by altering the stylesheet
273
274 if [[ $format = "html" ]]
275 then
276 this_month=`date +"%B %Y"`
277 sed "s/autodate/$this_month/g" xsl/ecmwf_html-custom.xsl > xsl/ecmwf_html-custom_mod.xsl
278 fi
279
280
281 # If publishing the whole user guide as one book, then some of the cross-references
282 # will be wrong. The source chapters refer to the individual books,
283 # but for the user guidee we want them to refer to the one book ('userguide').
284
285 if [[ $bookname = "magics_userguide" ]]
286 then
287 for chapfile in chapters/$mod_chapter_mask
288 do
289 sed 's/<olink targetdoc="Magics_[^"]*" /<olink targetdoc="Magics_userguide" /g' $chapfile > temp1.xml
290 mv temp1.xml $chapfile
291 done
292 fi
293
294
295 # The same thing as above applies when we publish the book of new features
296
297 #if [[ $bookname = "magics_new_features" ]]
298 #then
299 # for chapfile in chapters/$mod_chapter_mask
300 # do
301 # sed 's/<olink targetdoc="Magics_[^"]*" /<olink targetdoc="Magics_new_features" /g' $chapfile > temp1.xml
302 # mv temp1.xml $chapfile
303 # cp $chapfile xxxx.xml
304 # done
305 #fi
306
307
308
309 # for the HTML version, we only have one book, whereas for PDF, we split into one book
310 # per chapter. This causes problems with 'olink'ing because our cross-references have to
311 # say which book they refer to. The source chapters refer to the individual books,
312 # but for HTML we want them to refer to the one book ('userguide').
313
314 #if [[ $format = "html" ]]
315 #then
316 # for chapfile in chapters/$mod_chapter_mask
317 # do
318 # sed 's/<olink targetdoc="Magics_[^"]*" /<olink targetdoc="Magics_userguide" /g' $chapfile > temp1.xml
319 # mv temp1.xml $chapfile
320 # done
321 #fi
322
323
324
325 # generate the documents from the XML
326
327
328
329
330 # set the parameters for xsltproc
331
332 source_xml_file="$source_xml_dir${mod_bookname}.xml" # OR "$source_xml_dir$mod_bookname"
333 bname=`basename $source_xml_file .xml`
334 fo_file="$source_xml_dir$bname.fo"
335
336 #database_document_param="--stringparam target.database.document ../targets/olinkdb-${format_flag}.xml"
337 current_docid_param="--stringparam current.docid ${bookid}"
338 fop_extensions_param="--stringparam fop1.extensions 1"
339 xsl_param="xsl/${format_flag}.xsl"
340 source_xml_param="$source_xml_file"
341 out_fo_param="-o $fo_file"
342 out_pdf_file="${source_xml_dir}$bname.pdf"
343
344
345 # if we are not generating a target file, then we will be using one.
346
347 if [[ $targetopt = "" ]]
348 then
349 target_options="--stringparam target.database.document ../targets/olinkdb-${format}.xml"
350 else
351 target_options="--stringparam collect.xref.targets only --stringparam targets.filename ../targets/magics_${bookname}_${format}_target.db"
352 fi
353
354
355
356 # xml -> fo
357 command="xsltproc $netvalid $extra_xslt_flags $out_fo_param $target_options $current_docid_param $fop_extensions_param --xinclude $xsl_param $source_xml_param"
358
359 if [[ verbose -eq "1" ]]
360 then
361 echo "Executing: $command"
362 fi
363
364 $command
365
366
367 # fo -> pdf
368
369 if [[ -e $fo_file && $targetopt = "" ]]
370 then
371 command="fop $extra_fop_flags $fo_file -pdf $out_pdf_file"
372
373 if [[ verbose -eq "1" ]]
374 then
375 echo "Executing: $command"
376 fi
377
378 $command
379 else
380 if [[ $targetopt = "" ]]
381 then
382 echo "ERROR: Intermediate .fo file '$fo_file' was not produced. Will not generate PDF"
383 fi
384 fi
385
386
387
388
389 # /usr/local/apps/docbook/bin/docbookx2html -o $format_flag -t $base_path/$xsl $mod_bookname.xml
390 #tools/docbookx2html $verboseopt -o $format_flag -t $base_path/$xsl $targetopt $bookidopt $targetdocopt "books/$mod_bookname.xml"
391
392 # xxe and xerces have different opinions on how to handle relative includes
393 # - see above. We are now converting the links back to 'xxe mode'.
394
395 #for chapfile in chapters/*.xml
396 #do
397 # sed 's/include href="examples/include href="..\/examples/g' $chapfile > temp1.xml
398 # sed 's/include href="paramtables/include href="..\/paramtables/g' temp1.xml > temp2.xml
399 # mv temp2.xml $chapfile
400 # rm -f temp1.xml
401 # rm -f temp2.xml
402 #done
403
404
405
406 ## figures at the top of a new page - reversal of above procedure
407 #
408 #if [[ $format = "pdf" ]]
409 #then
410 # for chapfile in chapters/*.xml
411 # do
412 # sed "s/$figure_with_break/$figure_plain/g" $chapfile > temp.xml
413 # echo "s/$figure_with_break/$figure_plain/g"
414 # mv temp.xml $chapfile
415 # done
416 #fi
417
418
419
420 # now we've finished messing around with the source xml files, so let's
421 # restore them to their original versions
422
423 #for chapfile in chapters/$chapter_mask
424 #do
425 # cp -p $chapfile.orig $chapfile
426 #done
427
428
429 # if not just creating the target database...
430
431 if [[ $targetopt = "" ]]
432 then
433
434 # for HTML, move into place
435
436 if [[ $format = "html" ]]
437 then
438 echo "Inserting links to index.html"
439 cd books
440 for htmlpage in *.html
441 do
442 sed "s/<a href=\"index.html\"><\/a>/<a href=\"index.html\">Contents<\/a>/g" "$htmlpage" > "../publish/html/$htmlpage"
443 rm -f $htmlpage
444 done
445 cd ..
446
447 #mv books/*.html publish/html
448 fi
449
450
451 # for PDF, rename and move into place
452
453 if [[ $format = "pdf" ]]
454 then
455 final_pf_dest=publish/pdf/magics_$bookname.pdf
456 mv $out_pdf_file $final_pf_dest
457 echo ""
458 echo "GENERATED PDF is in '$final_pf_dest'"
459 echo ""
460 fi
461
462 # for PDF, convert the PostScript into PDF, then move into place
463
464 # if [[ $format = "pdf" ]]
465 # then
466 # ps2pdf books/$mod_bookname.ps
467 # mv $mod_bookname.pdf publish/pdf/$bookname.pdf
468 # fi
469
470 fi
471
472
473 # for HTML, we store all our images in './images' (relative to the html)
474 # so we copy all images to that directory now
475
476 if [[ $format = "html" ]]
477 then
478 echo "Copying images to publish/html/images..."
479
480 cp -p -v diagrams/*.gif publish/html/images/diagrams
481 cp -p -v diagrams/*.png publish/html/images/diagrams
482 cp -p -v examples/manual/c/png/*.png publish/html/images/c
483 cp -p -v examples/manual/fortran/png/*.png publish/html/images/fortran
484 cp -p -v examples/manual/magml/png/*.png publish/html/images/magml
485 cp -p -v examples/manual/python/png/*.png publish/html/images/python
486 # cp -p -v examples/tutorial/c/png/*.png publish/html/images/c
487 cp -p -v examples/tutorial/fortran/png/*.png publish/html/images/fortran
488 cp -p -v examples/tutorial/magml/png/*.png publish/html/images/magml
489 chmod u+w publish/html/images/*.gif
490 chmod u+w publish/html/images/*/*.gif
491 chmod u+w publish/html/images/*.png
492 chmod u+w publish/html/images/*/*.png
493 fi
494
495
496 # clean up temporary files
497
498 if [[ $clean = "yes" ]]
499 then
500 tools/clean
501 fi
502