New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
extract_rst.sh in trunk/ADM/DOC_SCRIPTS – NEMO

source: trunk/ADM/DOC_SCRIPTS/extract_rst.sh @ 8624

Last change on this file since 8624 was 2246, checked in by rblod, 14 years ago

fcm with nemo_v3_3_beta

  • Property svn:eol-style set to native
  • Property svn:executable set to *
  • Property svn:keywords set to Id
File size: 6.4 KB
Line 
1#! /bin/sh
2set -x
3#+
4#
5# ==========
6# extract.sh
7# ==========
8#
9# -----------------------------------------
10# extract ReStructuredText from source file
11# -----------------------------------------
12#
13# SYNOPSIS
14# ========
15#
16# ``extract_rst.sh -i filein -l language -o fileout``
17#
18# DESCRIPTION
19# ===========
20#
21# ``extract_rst.sh`` extracts ReST comments from the file given in argument
22#
23# -i  input file
24# -o  output file (ReST)
25# -l  language
26#
27# Comment block (start, end) identification depends on language :
28#
29#  *F90*
30#   FORTRAN source free form
31#  *fortran*
32#   FORTRAN source fixed form
33#  *sh*
34#   shell scripts
35#  *IDL*
36#   IDL source
37#  *xml*
38#   XML and XSL
39#  *dot*
40#   graphviz files
41#  *php*
42#   PHP files
43#  *matlab*
44#   matlab or octave files
45#
46# EXAMPLES
47# ========
48#
49# To extract ReST comments of this shell script::
50#
51#  $ extract_rst.sh -i extract_rst.sh -l sh -o extract_rst.sh.rst
52#  iii : rst lines of extract_rst.sh are in extract_rst.sh.rst
53#
54# You can produce HTML file from this new file::
55#
56#  $ rst2html.py --input-encoding=ISO-8859-15 extract_rst.sh.rst \
57#    /usr/temp/${LOGNAME}/extract_rst.sh.html
58#
59# You can produce PDF file from this new file::
60#
61#  $ rst2newlatex.py --input-encoding=ISO-8859-15 extract_rst.sh.rst \
62#    /usr/temp/${LOGNAME}/extract_rst.sh.tex
63#  $ pdflatex extract_rst.sh.tex
64#
65# Of course beware of consistency of path on links.
66#
67# CAUTIONS
68# ========
69#
70# Becaue of poor implementation of Standard FORTRAN in cpp (prepocessing)
71# within gfortran and g95, ReST comments might induce trouble in
72# FORTRAN sources.
73#
74# For example following line is pointed out be gfortran with
75# ``error: unterminated comment``.
76# This is because ``/*`` is the beginning of a C style comment !!
77# ::
78#
79#      !    **MEAN** = sum( *X*\ (:) )/*ntime*
80#
81#
82#
83# One can modify this ReST line with
84# ::
85#
86#      !    **MEAN** = sum( *X*\ (:) ) / *ntime*
87#
88# TODO
89# ====
90#
91# check parameters
92#
93# log
94#
95# add perl
96#
97# SEE ALSO
98# ========
99#
100# ReStructuredText_
101#
102# .. _ReStructuredText: http://docutils.sourceforge.net/rst.html
103#
104# Docutils_
105#
106# .. _Docutils: http://docutils.sourceforge.net/
107#
108# EVOLUTIONS
109# ==========
110#
111# $Id$
112#
113# - fplod 2009-04-20T08:13:37Z aedon.locean-ipsl.upmc.fr (Darwin)
114#
115#   * add CAUTIONS paragraph to warn about possible FORTRAN compiling problem
116#
117# - fplod 2009-04-03T14:53:18Z aedon.locean-ipsl.upmc.fr (Darwin)
118#
119#   * usage of tr instead of sed to remove ``\r``
120#     due to difference between ``/sw/bin/sed`` and ``/usr/bin/sed`` (the last
121#     one do not work coorectly on ``\r`` interpertation ie: remove the first occurence of
122#     ``r``)
123#
124# - fplod 2009-02-10T10:46:23Z aedon.locean-ipsl.upmc.fr (Darwin)
125#
126#   * add language fortran for FORTRAN source in fixed form
127#
128# - fplod 2009-01-05T11:41:33Z aedon.locean-ipsl.upmc.fr (Darwin)
129#
130#   * remove \\r (CRLF) from file before awk and sed (otherwise ReST block
131#     was not found in "ISO-8859 text, with CRLF line terminators" files
132#
133# - fplod 2008-12-22T10:37:37Z aedon.locean-ipsl.upmc.fr (Darwin)
134#
135#   * add matlab (octave)
136#
137# - fplod 2008-09-17T13:40:37Z aedon.locean-ipsl.upmc.fr (Darwin)
138#
139#   * add php language
140#
141# - fplod 2008-09-08T09:34:04Z aedon.locean-ipsl.upmc.fr (Darwin)
142#
143#   * add F90 language
144#
145# - fplod 2008-08-08T08:28:30Z aedon.locean-ipsl.upmc.fr (Darwin)
146#
147#   * add KML files (with other XML files)
148#   * add parameters ``-i`` ``-l`` ``-o``
149#
150# - fplod 200807
151#
152#   * creation
153#
154#-
155#
156system=$(uname)
157case "${system}" in
158   AIX|IRIX64)
159      echo " www : no specific posix checking"
160   ;;
161   *)
162      set -o posix
163   ;;
164esac
165unset system
166#
167command=$(basename ${0})
168log_date=$(date -u +"%Y%m%dT%H%M%SZ")
169log=/tmp/$(basename ${command} .sh).log.${log_date}
170#
171usage=" Usage : ${command} -i filein -l language -o fileout"
172#
173minargcount=6
174#echo " narg ${#}"
175if [ ${#} -lt ${minargcount} ]
176then
177   echo "eee : not enought arguments"
178   echo "${usage}"
179   exit 1
180fi
181#
182# default
183# n.a.
184#
185while [ ! -z "${1}" ]
186do
187   case ${1} in
188      -i)
189         filein=${2}
190         shift
191      ;;
192      -o)
193         fileout=${2}
194         shift
195      ;;
196      -l)
197         language=${2}
198         shift
199      ;;
200      -h)
201         echo "${usage}"
202         exit 0
203      ;;
204      *)
205         echo "eee : unknown option ${1}"
206         echo "${usage}"
207         exit 1
208      ;;
209   esac
210   # next flag
211   shift
212done
213#
214set -u
215#
216# ++ check param
217#
218case "${language}" in
219   fortran)
220      awkblockstart="^C\+$"
221      awkblockend="^C-$"
222      sedblockstart="^C+$"
223      sedblockend="^C-$"
224      comment="^C"
225   ;;
226   F90)
227      awkblockstart="^!\+$"
228      awkblockend="^!-$"
229      sedblockstart="^!+$"
230      sedblockend="^!-$"
231      comment="^!"
232   ;;
233   IDL)
234      awkblockstart="^;\+$"
235      awkblockend="^;-$"
236      sedblockstart="^;+$"
237      sedblockend="^;-$"
238      comment="^;"
239   ;;
240   xml)
241      awkblockstart="^<!--rst$"
242      awkblockend="-->$"
243      sedblockstart="^<!--rst$"
244      sedblockend="-->$"
245      comment=""
246   ;;
247   sh)
248      # iii : awk '/^\#\+/,/^\#\-/' $file
249      awkblockstart="^\#\+$"
250      awkblockend="^\#\-$"
251      sedblockstart="^#+"
252      sedblockend="^#-"
253      comment="^#"
254   ;;
255   dot|php)
256      awkblockstart="^\/\*rst$"
257      awkblockend="*\/"
258      sedblockstart="^\/\*rst$"
259      sedblockend="^\*\/"
260      comment=""
261   ;;
262   matlab)
263      awkblockstart="^%\+$"
264      awkblockend="^%-$"
265      sedblockstart="^%+$"
266      sedblockend="^%-$"
267      comment="^%"
268   ;;
269   *)
270      echo "eee : ${language} not implemented"
271      exit 1
272   ;;
273esac
274#
275# just in case suppress \r at the end of lines
276tr -d '\r' < ${filein} > /tmp/${$}_0
277#
278# put rst blocks in one temporary file
279#awk '/^;+/,/^;-/' a.pro | sed -e "/^;+$/d" -e "/^;-$/d" -e "s/^;//"
280cmdawk="awk '/${awkblockstart}/,/${awkblockend}/' /tmp/${$}_0 > /tmp/${$}_1" #++
281eval ${cmdawk}
282if [ ! -s /tmp/${$}_1 ]
283then
284   rm /tmp/${$}_0 /tmp/${$}_1
285   echo "iii : no rst comments in ${filein}"
286   exit 1
287fi
288#
289# suppress begin and end of each block
290sedcmd="sed -e \"/${sedblockstart}/d\" -e \"/${sedblockend}/d\" /tmp/${$}_1 > /tmp/${$}_2"
291eval ${sedcmd}
292#
293# suppress comment at the beginning of each line
294if [ "${comment}" != "" ]
295then
296   sedcmd="sed -e \"s/${comment}//\" /tmp/${$}_2 > /tmp/${$}_3"
297   eval ${sedcmd}
298   # suppress first blank
299   cp /tmp/${$}_3 /tmp/${$}_2
300   sed -e "s/^ //" /tmp/${$}_2 > /tmp/${$}_3
301   cp /tmp/${$}_3 ${fileout}
302else
303   cp /tmp/${$}_2 ${fileout}
304fi
305#
306echo "iii : rst lines of ${filein} are in ${fileout}"
307#
308# clean
309rm /tmp/${$}_0 /tmp/${$}_1 /tmp/${$}_2 /tmp/${$}_3 2> /dev/null
310#
311# exit
312exit 0
Note: See TracBrowser for help on using the repository browser.