From ff34366fdef70c871a3ad6a40aa839de1da41e5e Mon Sep 17 00:00:00 2001
From: Anthony Scemama <scemama@users.sourceforge.net>
Date: Mon, 8 Jul 2013 23:40:40 +0200
Subject: [PATCH] Improved documentation Version:1.2.21

Version:1.2.20
---
 Makefile             |  10 +++++++++
 README               |  52 ++++++++++++++++++++++++++-----------------
 example/Makefile     |   2 +-
 example/uvwt.irp.f   |  16 ++++---------
 man/.gitignore       |   1 +
 man/Makefile         |  12 ++++++++++
 man/irpf90.rst       |  36 ++++++++++++++++++++++++++++++
 man/irpman.rst       |  32 ++++++++++++++++++++++++++
 man/man1/irpf90.1.gz | Bin 899 -> 1320 bytes
 man/man1/irpman.1.gz | Bin 583 -> 662 bytes
 src/command_line.py  |  49 +++++++++++++++++++++++-----------------
 src/version.py       |   2 +-
 12 files changed, 158 insertions(+), 54 deletions(-)
 create mode 100644 Makefile
 create mode 100644 man/.gitignore
 create mode 100644 man/Makefile
 create mode 100644 man/irpf90.rst
 create mode 100644 man/irpman.rst

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..98226fd
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,10 @@
+.PHONY: all src man
+
+all: src man
+
+src:
+	$(MAKE) -C $@
+
+man:
+	$(MAKE) -C $@
+
diff --git a/README b/README
index dc5cef5..789b34a 100644
--- a/README
+++ b/README
@@ -1,35 +1,47 @@
-+==============================================================================+
-|                                  IRPF90                                      |
-+==============================================================================+
+======
+IRPF90
+======
 
-Dependencies:
--------------
+Dependencies
+------------
 
-- GNU make (3.81 recommended)
+- GNU make (>= 3.81 recommended)
 - Python > 2.3
-- Any Fortran 90 compiler (gfortran, for example)
+- Any Fortran 90 compiler (Intel recommended, for example)
 
-Installing IRPF90:
-------------------
+Installing IRPF90
+-----------------
 
-- As the super-user, run
-./irpf90.install
+${IRPF90_HOME} is the location of your irpf90 directory::
+
+  cd ${IRPF90_HOME}
+  make
+  cat << EOF >> ${HOME}/.bash_profile
+  export PYTHONPATH=${IRPF90_HOME}/src:${PYTHONPATH}
+  export PATH=${IRPF90_HOME}/bin:${PATH}
+  EOF
 
 
-Using IRPF90:
--------------
+Using IRPF90
+------------
+
+In an empty directory, run::
+
+  irpf90 --init
 
-In an empty directory, run:
-irpf90 -init
 This command creates a new Makefile suitable for most irpf90 projects.
 Now you can start to program using irpf90.
 
 
-Web Site:
+Web Site
+--------
+
 http://irpf90.ups-tlse.fr
 
-Author:
-Anthony Scemama, LCPQ-IRSAMC, CNRS-Universite Paul Sabatier
-scemama@irsamc.ups-tlse.fr
-http://irpf90.ups-tlse.fr/index.php?title=Anthony_Scemama
+Author
+------
+
+| Anthony Scemama, LCPQ-IRSAMC, CNRS-Universite Paul Sabatier
+| scemama@irsamc.ups-tlse.fr
+| http://scemama.mooo.com
 
diff --git a/example/Makefile b/example/Makefile
index 67c451e..0a69231 100644
--- a/example/Makefile
+++ b/example/Makefile
@@ -1,4 +1,4 @@
-IRPF90 = irpf90  -a -d
+IRPF90 = ~/irpf90/bin/irpf90  -a -d
 FC     = gfortran
 FCFLAGS= -O2
 
diff --git a/example/uvwt.irp.f b/example/uvwt.irp.f
index a2198a2..32803b2 100644
--- a/example/uvwt.irp.f
+++ b/example/uvwt.irp.f
@@ -12,22 +12,14 @@ END_PROVIDER
 
 BEGIN_PROVIDER [ integer, u1 ]
   integer :: fu
-  u1 = fu(d1,d2)
-  integer :: n, m
-  n=3
-  do i=1,n
-    print *,  i
-  enddo
-  m=2
-  do i=1,m
-    print *,  i
-  enddo
-! PROVIDE u2
+! u1 = fu(d1,d2)
+  u1 = d1+d2+1
 END_PROVIDER
 
 BEGIN_PROVIDER [ integer, u2 ]
   integer :: fu
-  u2 = fu(d3,d4)
+! u2 = fu(d3,d4)
+  u2 = d3+d4+1
 END_PROVIDER
 
 integer function fu(x,y)
diff --git a/man/.gitignore b/man/.gitignore
new file mode 100644
index 0000000..178be68
--- /dev/null
+++ b/man/.gitignore
@@ -0,0 +1 @@
+options.rst
diff --git a/man/Makefile b/man/Makefile
new file mode 100644
index 0000000..841432f
--- /dev/null
+++ b/man/Makefile
@@ -0,0 +1,12 @@
+RST2MAN=rst2man -d -t
+
+default: man1/irpman.1.gz man1/irpf90.1.gz
+
+options.rst: ../src/command_line.py
+	python ../src/command_line.py > options.rst
+
+man1/irpf90.1.gz: irpf90.rst options.rst
+	rm -f $@ ; $(RST2MAN) --title="IRP Fortran 90" irpf90.rst man1/irpf90.1 ; gzip man1/irpf90.1
+
+man1/irpman.1.gz: irpman.rst
+	rm -f $@ ; $(RST2MAN) --title="IRP man" irpman.rst man1/irpman.1 ; gzip man1/irpman.1
diff --git a/man/irpf90.rst b/man/irpf90.rst
new file mode 100644
index 0000000..949c9c6
--- /dev/null
+++ b/man/irpf90.rst
@@ -0,0 +1,36 @@
+======
+IRPF90
+======
+
+----------------------------------------------------------
+Fortran programming using Implicit Reference to Parameters
+----------------------------------------------------------
+
+:Author: Anthony Scemama scemama@irsamc.ups-tlse.fr
+:Version: 1.20
+:Manual section: 1
+
+SYNOPSIS
+========
+
+  irpf90 [options]
+
+DESCRIPTION
+===========
+
+irpf90  provides  a programming environment which simplifies Fortran
+programming, via the Implicit Reference to Parameters (IRP) method.
+For  more  details,  read the tutorial ditributed with the package
+or visit http://irpf90.ups-tlse.fr
+
+OPTIONS
+=======
+
+.. include:: options.rst
+
+SEE ALSO
+========
+
+* irpman
+* http://irpf90.ups-tlse.fr
+
diff --git a/man/irpman.rst b/man/irpman.rst
new file mode 100644
index 0000000..e68254c
--- /dev/null
+++ b/man/irpman.rst
@@ -0,0 +1,32 @@
+======
+IRPman
+======
+
+----------------------------------------------------
+Developper's documentation in the irpf90 environment
+----------------------------------------------------
+
+:Author: Anthony Scemama scemama@irsamc.ups-tlse.fr
+:Version: 1.20
+:Manual section: 1
+
+SYNOPSIS
+========
+
+  irpman variable
+
+DESCRIPTION
+===========
+
+irpman is a documentation environment for IRPF90.  Every IRP
+variable (described with a BEGIN_PROVIDER ...  END_PROVIDER block)
+has  an  associated  manual  page.  When  a provider contains a
+documentation block (BEGIN_DOC ... END_DOC), the text entered inside
+the block is displayed in the manual page of the variable.
+
+SEE ALSO
+========
+
+* irpf90
+* http://irpf90.ups-tlse.fr
+
diff --git a/man/man1/irpf90.1.gz b/man/man1/irpf90.1.gz
index 181036cf393def4601fceac84a5a122294d7efb9..1342fca6f0e8255fa10eb82049f5491493b24c5e 100644
GIT binary patch
literal 1320
zcmV+@1=so?iwFpxG}}=C18H(_W;rk}F#wfTZExE)5dO|zaSbw{!(zpDP;4_WU|#Gt
z0$RtgoDV}46tqNHL?lupDZ4KE<9A2Nw&FP0`XLTq?)AC5hYI2g_{0@dd@W!tlrY?h
z6f&brFd}lMPMk0zU5c+RU;+DZ5YcJ`!~WnV?)87gzu#au7`+?9!}2y@ELh$_xR}5H
zy$=JpxPXg6Fzn;M3l>CoFdKiGvi3Ue!Fz3-p%{!_8(x-Dt)aH`8<tfe6X{?fGK@kc
z0-T09M=60}Sqvyp28?yXlB=FnsZg$0h>a+qPnW3}(CtE0=;ISNYpGZqUk)IS)o0Ww
z{m~<9ROs-Wt^Iu?Jvt-zs^%l>v6q+q$1{h6bBDu67PNVUv&nR}WC2zzILQg26C)PD
zA_B?|S1(X`HNsOU&giy?{xW#QxwdZ9h6xX|eVnkEdilo23paS9i}VM<e6`xWCN?Fu
zKWY&Z_z{KLCyGrR{XM&%M`6T*CSm9Y{loeuc*mrvGHmeAx^hx0i>{8?99L**GL3E*
z;d~k1&sboqy&}!SMyA37@Mp6j)J7VuN<wv;%OnRYX;3nWvh6Ujj=~jeBnOv^|C}dy
zi&ObC;3n5;z|a;zsf_?gh2yfYSAeX*Q*X@GP8-P!NToA!RTC*}rOW+g#giwb6owWy
z(xS&W3*(=1=c>{5b(3IFS2pgs!ipd>aW?l@+<O>KKwaY9U&s^_bRYNPUMe!F1e^GO
z7SY*o3}jUZkW?xHB8AnC0wJ3D621rPkhBOf8yxNN)*iQ37{|tmlN%JXFpi?>V%b%K
zFay4_xV~aWlzJo12puh_he%iTx?|Yy16U$L3NZ(r`5=?p7^<eNS4P(kv%1b|l~CVY
zw_RY^Ru%=U5LzQuL%<$s^siEGa9_Ksc5Isqg)M^Rq+UV%#aHQQ$)UA<1>CZ&Kx^E3
z6SwmRaI&PTArdK0tVNGLvR0*&+PX~*<H}?qI>|LB-m6aw5}kH6^Hwt#MaAZn1xiT^
zet(dXt&~*Ku@HZ-#pE|M)?$=OBNFVqT>!V(i{zLy><C^L4xh3oK~Vu>(ln_kk*T=Z
zv8^^w6x&`Ohouu+v2TS!t`!^8FK}b{&bCicqRR>mn^s?Lgk|K!3fF*mNu4(S7=D-?
z+A*MMWa2Bwu|w1k_W!sUf?r_hR0Z#cVLdtE&1&ZataMFP-E~4N+Yn1^Kg_2Au-T9q
zop8@H*Qx02I{NAWY(dk5Lf`kjWxua#S<nJT6f^RIm%_vu*76`m?X;IX8rH4hBp1mO
zvK@<Zy|qY9NHIX{SITcb8hk)^)WJslQzMG$(L{A<DuK=tVQrJ2_0+dNqYo1*E^^ks
z>sizF0X$fd)dgfkS$@jaR5cQ}EYS+ti?RWmQ{UUf$m-d^nl=EXzjO*5t`)H#73oa<
z;mu@vd+EF2%_Ll09<ABd8qTwI5{Xi<=&;20C~DNkhbPrgXkA$fo3&qGKFUfY$YRMJ
zJxu&$mR#$>={m{TMB1uAY@64BDA3Vczzt!A0>sQn3(RlG0X6J_G}oAnA}+vZ17GKw
z$gJb4Ze7)?#tO83*KCfRaTMRQ;u}20n(yn_ZiyNi`agLDqv;gJAEWz|=X4J7+f@xi
zdKB?7?w<Ug7v-6Y@x$`&e!<2HUpKXbC=n$uIW~j;|EDyTmkHU}oA93$$1h%dQBs{C
e9~KrnS@}=qt&zyIftSP&&VK=mP{2M<3jhFrFMFW?

literal 899
zcmV-}1AP1+iwFqT?7K<;18H(_W;rk}F#v^CQE%fm41U+IAo6q@5?^m`hZTppY1$fS
z6T@~e6w5FuHkAmCB}0;v%YOYx+3DJ?!+<2VDC*<KkED`R50Dl4-PbGl0+SLu`048E
z>jWlg0%eV@Y$Ywo1MaK~P8uLj+XZcnp8&vS0<#}yV4PKo-$YVAz%qSW2<<vWzMI+W
z$<EoGlWnWb4tmeOS=$|StpgOO(4najf`wd?7Y1}bqLt6fRbFPLNN!*N6~Ap%w#ut)
zwcM!UcM;ug7v;RjqET$r&EQGf9QLRi^dR3cKy%d2nifrf(_Ytm@S5o;jb3~}c?w4@
zA?)#gS;HsN>j$94-ZlwiL2DgCgF)(ppMpc#M5NFM>$E&Tql44iK41eU9rkgvll6<-
zVKSsQq)Q@HdHhm}o0*=%Y^IG4l&8q(Nm%+%jK}NVInJ%o4r>Z?W|AlCUWN#RJ_*c;
zOo-w%sAPW#@FZVQ=>txMGy_dO#gbj1NFio*VIi4?^d4R0kvm(X_mGz5qNu<J!e^Cz
z0+}K_?Z*ZJdXrmETP#UykNClvH*p${)8Mw>ahS9Y`bcgNEeTXa)KCS$s(1POe(P)>
zw877+H#G<TJhp@rCw(};mb7--u=qrZ&r*ETNJr~FbUpV68fq9SF3Ujm#P6gvy-FCd
zNh}X1Bs6+5#5`X^&@GpdlxaX4PZ8tRc;szr9bB{I-#Ek0VK+)R7za^_VC>+_CSmd}
zSM?us6Igpx{Q(p)jq2=}D|>rUTSHxF*x>if*Vj&W?}fg-K1yoK?MR3kgXqHFMkaI{
zjoddEGf;je@ccBeJr9#o<bPy$|5468V-tn$ZGOC_$?<;d{EPFEosTqJRK8dLLFv)T
zbsw90n3!~3J**0m7$s6eqiD{T8x5}g@bXJfP3seHdsic=MKKMAZz54TLQIN9zACD0
zc@H=1`*I=*?C53ylGL;C9A5T>?ULv}U**q5cK=X`@lL&P`;uHuVQ#y#)4P3u&8OPN
zixys)%@<GUQ%X+Df`)wSE(o<HHHMK*Z_3r<x>`Iw!*T_`rbUr1tLLA`GRM0GJjNaq
zkJ)^&EElopNyMvo@aUr)xp=F>NjjVY&-mH)Knw0)4#$}}Y_uQmB+x<hhQ<YI8gXhK
ZB4y~t;{SjTqr<<W{{^gs6Aoww0073{wyyvH

diff --git a/man/man1/irpman.1.gz b/man/man1/irpman.1.gz
index cd005fa77834836308953225389ee7530c246256..60fb2f15c8c42c8beca7559839420e823dc2cacb 100644
GIT binary patch
literal 662
zcmV;H0%`ppiwFoYC)-f~18H(_ZDDRMF#wfR-*4J55PtVxaYCEcYQs&as;xYYm8^|4
z0!rwnX+e`oOtF^Ok!|Ss?{{{fbQB)?5XHW`@4KHqns;EtBsA=S!vmLGGs{a@XjOye
znboVpa?Q&r|7$6s<o3x#$v*Ug@G|cPAMyKym;Tii+)r;PA#{2NaXJ|d5(uHwflf$!
z0scCKW_OSbMiD`EjgIp!4EdT@s%f}>XP{KYs^-!%E0hEw!7e!n-7KyH;Bqarl1`1G
zP^m#1+e4PFkR=Mcm1BayDN7zYZOR*^?TG0IAxWOU2_etrFGSQ{G$Sp<36F8@^sROO
zh}}u#jC9FMWiUG;437zWGeWm{#K|y9ri5az=s`}<Xx=9j(hOX7czRKllMx=4;s|zI
z(f8pA=gQdrHcYrrc5y-)dHa^*g&WkUs(fWJPj<W8#wPjWYZ)<t*8o;NQ5@gwXEL5-
zaYksHFa$JsI$zQ&g5&B&d(E_9^NJI?FU|ghM8hb%N#n^h9w&sFW``37*ugt^Hu<nn
z+P$r>*8v5H)?9DgmF&F1S;<YI#T?)0qp(Zl`V!s7$?r)z{vHpb6exATWVn~iD^>hC
zCrf4kFaTi2s6zN>j-xMEtOCCw5cgxrodM3BT8olvC=>=MB*skskJ*#LS?hc_zVUvY
zTRfkC@bB8<R>9o-hQVnuNJyN#g<>5_VVa6<yw)SO(fD<x7GAVVeA}ETg2A_Je9)W;
z<Y)60^hmo(o=fsYoWEUK+w?CkS}k2QChywHaJta>Vsg;7!Tt1ZoRWdGOC>ju6})CO
w1JnLL3vF0kIF22KAJF~goNs)0t*DI4$LI2>1y+H2OI%<706VGlWtRm20OOHI6951J

literal 583
zcmV-N0=WGjiwFqh?7K<;18H(_ZDDRMF#v5+VQbqk5dE%Sarn#H(Ta56%Ep+Jc!{C0
zgYB*a0z<LSwU{FrNlur4zmvRdWgYl~<a>JW?!DvH8q#9Bi8Hu^sKfz2%x3oyL@|f5
z#-lh2x)9<h6f|gSBL^q7iU43A!R`B7P)4_{KQUgeA&WN&lV<Sv{Vgo<guNaHH18}l
zx*m_HobU`F6}S$8u<iW}P@SaF%9jIAxy$lxnU;*t;Wr)Ix9Le3DGojE+kyq$GAS2D
zx~<YYqxyV;QWc~H@sHvw4QRFTgMYoBah9CWoc#?h^l&xJdcX!=r0a-ko~+XB`?kox
zrOTuM&gosY{QKk3>-xtvbb@ph2y1mMg`@Y>&nS8r#4~dC)FBmNF#04LG*D}5PO7)P
z20FN!RG0a}3xXG<^Ysn$&N=+)XeNh-REUEJgQL?^n!k~D=*2lyL*-Q~pj-coT_)y}
zo$+I}&I@u~wJcVy)9QTL1Nda8!<W&bvE1s>)JQ(kTngQ1##<RUq9WPmMU`eNm_M${
zh!r?!<KQqpTW~sbB1YmiJm44kc2}gUb;YJYfa0*;gF8OEfrTE<Mm~2A_E)tI>j{54
zTO^x!6B8)&Js-@4q1H#VQ*!aV%pV@B<Y5O{4o`7W#96ib7#5&GGQYQAF*wH_(nXS$
z3AEB1;`yqMe59{61hKkxFT&srCEUPSk3biA!QRXH$tVbE9j(piXt5m|Rmd2P&)8?(
VNFT2KuR6R{{{@BNxKo}30073ECF}qI

diff --git a/src/command_line.py b/src/command_line.py
index 00c27fa..4aba685 100644
--- a/src/command_line.py
+++ b/src/command_line.py
@@ -31,21 +31,21 @@ import re
 
 description = "IRPF90 Fortran preprocessor."
 options = {}
-options['d'] = [ 'debug'        , 'Activate debug', 0 ]
-options['v'] = [ 'version'      , 'Print version of irpf90', 0 ]
-options['a'] = [ 'assert'       , 'Activate assertions', 0 ]
+options['d'] = [ 'debug'        , 'Activates debug. The name of the current subroutine/function/provider will be printed on the standard output when entering or exiting a routine, as well as the CPU time passed inside the routine.', 0 ]
+options['v'] = [ 'version'      , 'Prints version of irpf90', 0 ]
+options['a'] = [ 'assert'       , 'Activates ASSERT statements. If absent, remove ASSERT statements.', 0 ]
 options['h'] = [ 'help'         , 'Print this help', 0 ]
-options['i'] = [ 'init'         , 'Initialize current directory', 0 ]
-options['D'] = [ 'define'       , 'Define variable', 1 ]
-options['o'] = [ 'checkopt'     , 'Show where optimization may be required', 0 ]
-options['p'] = [ 'preprocess'   , 'Preprocess file', 1 ]
-options['g'] = [ 'profile'      , 'Generate profile code', 0 ]
-options['t'] = [ 'touch'        , 'Display which entities are touched', 1 ]
-options['m'] = [ 'memory'       , 'Debug memory info', 0 ]
-options['z'] = [ 'openmp'       , 'Automatic openMP tasks (may not work)', 0 ]
-options['l'] = [ 'align'        , 'Align arrays using compiler directives. Sets the $IRP_ALIGN variable', 1 ]
-options['s'] = [ 'substitute'   , 'Substitute values for loop max values', 1 ]
-options['r'] = [ 'no_directives', 'Ignore compiler directives !DEC$ and !DIR$', 0 ]
+options['i'] = [ 'init'         , 'Initialize current directory. Creates a default Makefile and the temporary working directories.', 0 ]
+options['D'] = [ 'define'       , 'Defines a variable identified by the IRP_IF statements.', 1 ]
+options['o'] = [ 'checkopt'     , 'Shows where optimization may be required', 0 ]
+options['p'] = [ 'preprocess'   , 'Prints a preprocessed file to standard output. Useful for  debugging files containing shell scripts.', 1 ]
+options['g'] = [ 'profile'      , 'Activates profiling of the code.', 0 ]
+options['t'] = [ 'touch'        , 'Display which entities are touched when touching the variable given as an argument.', 1 ]
+options['m'] = [ 'memory'       , 'Print memory allocations/deallocations.', 0 ]
+#options['z'] = [ 'openmp'       , 'Automatic openMP tasks (may not work)', 0 ]
+options['l'] = [ 'align'        , 'Align arrays using compiler directives and sets the $IRP_ALIGN variable. For example, --align=32 aligns all arrays on a 32 byte boundary.', 1 ]
+options['s'] = [ 'substitute'   , 'Substitute values in do loops for generating specific optimized code.', 1 ]
+options['r'] = [ 'no_directives', 'Ignore all compiler directives !DEC$ and !DIR$', 0 ]
 options['n'] = [ 'inline'       , 'all|providers|builders : Force inlining of providers or builders', 1 ]
 options['u'] = [ 'unused'       , 'Print unused providers', 0 ]
 
@@ -135,12 +135,7 @@ Options:
     t = t.replace("$EXE",self.executable_name)
     t = t.replace("$DESCR",description)
     print t
-    sorted = options.keys()
-    sorted.sort()
-    for o in sorted:
-     print "  -%s , --%15s : %s"%(o,options[o][0].ljust(15),options[o][1])
-     if options[o][2] == 1:
-       print "                           Requires an argument"
+    print_options()
     print ""
     print "Version : ", version
     print ""
@@ -195,3 +190,17 @@ do_$LONG = property(fget=do_$LONG)
 
 
 command_line = CommandLine()
+
+def print_options():
+  keys = options.keys()
+  keys.sort()
+  import subprocess, threading
+  for k in keys:
+    description = options[k][1]
+    p1 = subprocess.Popen(["fold", "-s", "-w", "40"],stdout=subprocess.PIPE,stdin=subprocess.PIPE)
+    description = p1.communicate(description)[0]
+    description = description.replace('\n','\n'.ljust(27))
+    print ("-%s, --%s"%(k,options[k][0])).ljust(25), description+'\n'
+
+if __name__ == '__main__':
+  print_options()
diff --git a/src/version.py b/src/version.py
index a7c3fc0..ea274a4 100644
--- a/src/version.py
+++ b/src/version.py
@@ -1 +1 @@
-version = "1.2.18"
+version = "1.2.20"