foamCreateManpage 5.56 KB
Newer Older
1
2
3
4
5
#!/bin/sh
#------------------------------------------------------------------------------
# =========                 |
# \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
#  \\    /   O peration     |
6
#   \\  /    A nd           | Copyright (C) 2018-2019 OpenCFD Ltd.
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
#    \\/     M anipulation  |
#------------------------------------------------------------------------------
# License
#     This file is part of OpenFOAM, licensed under GNU General Public License
#     <http://www.gnu.org/licenses/>.
#
# Script
#     foamCreateManpage
#
# Description
#     Query OpenFOAM applications with -help-man to generate manpage content.
#
#------------------------------------------------------------------------------
defaultOutputDir="$WM_PROJECT_DIR/doc/man1"

usage() {
    exec 1>&2
    while [ "$#" -ge 1 ]; do echo "$1"; shift; done
    cat<<USAGE

Usage: ${0##*/} [OPTION] [appName .. [appNameN]]
options:
29
30
  -dir=DIR          Input directory to process
  -output=DIR       Write to alternative output directory
31
32
  -pdf              Process as nroff man content and pass to ps2pdf
  -gz | -gzip       Compress manpage output
33
  -version=VER      Specify an alternative version
34
35
36
37
38
39
40
  -h | -help        Print the usage

Query OpenFOAM applications with -help-man for their manpage content
and redirect to corresponding directory location.
Default input:  \$FOAM_APPBIN only.
Default output: $defaultOutputDir

41
Uses the search directory if individual applications are specified.
42

43
Copyright (C) 2018-2019 OpenCFD Ltd.
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
USAGE
    exit 1
}

# Report error and exit
die()
{
    exec 1>&2
    echo
    echo "Error encountered:"
    while [ "$#" -ge 1 ]; do echo "    $1"; shift; done
    echo
    echo "See '${0##*/} -help' for usage"
    echo
    exit 1
}

61
62
63
64
65
66
67
68
69
# Get the option's value (argument), or die on missing or empty argument
# $1 option
# $2 value
getOptionValue()
{
   [ -n "$2" ] || die "'$1' option requires an argument"
   echo "$2"
}

70
71
#-------------------------------------------------------------------------------
searchDirs="$FOAM_APPBIN"
72
unset sedFilter outputDir outputType
73
74
75
76
77
78
79

while [ "$#" -gt 0 ]
do
    case "$1" in
    -h | -help*)
        usage
        ;;
80
81
82
83
    -dir=*)
        searchDirs="${1#*=}"
        [ -d "$searchDirs" ] || die "directory not found '$searchDirs'"
        ;;
84
    -dir)
85
        searchDirs=$(getOptionValue "$@")
86
87
88
89
        [ -d "$searchDirs" ] || die "directory not found '$searchDirs'"
        shift
        ;;
    -gz | -gzip)
90
91
92
93
        outputType="gz"
        ;;
    -pdf)
        outputType="pdf"
94
        ;;
95
96
97
98
    -version=*)
        version="${1#*=}"
        sedFilter='s/OpenFOAM-[^\"]*/OpenFOAM-'"$version/"
        ;;
99
    -version)
100
        version=$(getOptionValue "$@")
101
102
103
        sedFilter='s/OpenFOAM-[^\"]*/OpenFOAM-'"$version/"
        shift
        ;;
104
105
106
    -output=*)
        outputDir="${1#*=}"
        ;;
107
    -output)
108
        outputDir=$(getOptionValue "$@")
109
110
111
112
113
114
115
116
117
118
119
120
        shift
        ;;
    -*)
        die "unknown option: '$1'"
        ;;
    *)
        break
        ;;
    esac
    shift
done

121
: "${outputDir:=$defaultOutputDir}"
122
123

# Verify that output is writeable
124
if [ -e "$outputDir" ]
125
126
127
128
then
    [ -d "$outputDir" ] && [ -w "$outputDir" ] || \
        die "Cannot write to $outputDir" "Not a directory, or no permission?"
else
129
    mkdir -p "$outputDir" 2> /dev/null || \
130
131
132
        die "Cannot create directory: $outputDir"
fi

133
134
echo "Generating manpages from OpenFOAM applications" 1>&2
echo 1>&2
135

136
137
138
# Use a tmp file so that we confirm that the content was
# generated and looks somewhat like a manpage (has a SYNOPSIS)
tmpFile="$outputDir/${0##*/}-tmp$$"
139
140
trap "rm -fv $tmpFile >/dev/null; exit 0" EXIT TERM INT

141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163

# Any special filter requirements?
# Default extension is "1" for manpage
outputExt="1"

case "$outputType" in
    pdf)
        outputExt="pdf"
        command -v groff  > /dev/null || die "Missing program: groff"
        command -v ps2pdf > /dev/null || die "Missing program: ps2pdf"
        ;;
    gz)
        outputExt="1.gz"
        command -v gzip   > /dev/null || die "Missing program: gzip"
    ;;
esac


#-------------------------------------------------------------------------------

# Get nroff man content from application, store in tmp file for checking
# and output / filter
# 1 = application
164
165
166
process()
{
    local appName="$1"
167
    local outFile="$outputDir/${appName##*/}"
168
169
170

    rm -f "$outFile"*;

171
    "$appName" -help-man | sed -e "${sedFilter}" 2>/dev/null >| "$tmpFile"
172

173
    # Check that it looks ok
174
175
    if grep -F -q "SYNOPSIS" "$tmpFile" 2>/dev/null
    then
176
177
178
179
180
181
182
183
184
185
186
187
188
        case "$outputType" in
        pdf)
            groff -man "$tmpFile" | ps2pdf - "$outFile.$outputExt"
            ;;

        gz)
            gzip -c "$tmpFile" >| "$outFile.$outputExt"
            ;;

        *)
            \cp -f "$tmpFile" "$outFile.$outputExt"
            ;;
        esac
189

190
        echo "$outFile.$outputExt" 1>&2
191
    else
192
        echo "Problem with ${appName##*/}" 1>&2
193
194
195
    fi
}

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
#------------------------------------------------------------------------------

# Default to standard search directories
[ "$#" -gt 0 ] || set -- ${searchDirs}

for item
do
    if [ -d "$item" ]
    then
        # Process directory for applications - sort with ignore-case
        echo "[directory] $item" 1>&2
        choices="$(find $item -maxdepth 1 -executable -type f | sort -f 2>/dev/null)"
        for appName in $choices
        do
            process $appName
        done
    elif command -v "$item" > /dev/null 2>&1
    then
        process $item
    else
        echo "No such file or directory: $item" 1>&2
    fi
done

echo 1>&2
echo "Done" 1>&2


# -----------------------------------------------------------------------------