foamCreateManpage 5.22 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
  -dir DIR          Directory to process
30
  -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
34
35
36
37
38
39
40
  -version VER      Specify an alternative version
  -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
61
62
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
}

#-------------------------------------------------------------------------------
searchDirs="$FOAM_APPBIN"
63
unset sedFilter outputDir outputType
64
65
66
67
68
69
70

while [ "$#" -gt 0 ]
do
    case "$1" in
    -h | -help*)
        usage
        ;;
71
    -dir)
72
73
74
75
76
77
        [ "$#" -ge 2 ] || die "'$1' option requires an argument"
        searchDirs="$2"
        [ -d "$searchDirs" ] || die "directory not found '$searchDirs'"
        shift
        ;;
    -gz | -gzip)
78
79
80
81
        outputType="gz"
        ;;
    -pdf)
        outputType="pdf"
82
        ;;
83
    -version)
84
85
86
87
88
        [ "$#" -ge 2 ] || die "'$1' option requires an argument"
        version="$2"
        sedFilter='s/OpenFOAM-[^\"]*/OpenFOAM-'"$version/"
        shift
        ;;
89
    -output)
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
        [ "$#" -ge 2 ] || die "'$1' option requires an argument"
        outputDir="$2"
        shift
        ;;
    -*)
        die "unknown option: '$1'"
        ;;
    *)
        break
        ;;
    esac
    shift
done

: ${outputDir:=$defaultOutputDir}

# Verify that output is writeable
107
if [ -e "$outputDir" ]
108
109
110
111
then
    [ -d "$outputDir" ] && [ -w "$outputDir" ] || \
        die "Cannot write to $outputDir" "Not a directory, or no permission?"
else
112
    mkdir -p "$outputDir" 2> /dev/null || \
113
114
115
        die "Cannot create directory: $outputDir"
fi

116
117
echo "Generating manpages from OpenFOAM applications" 1>&2
echo 1>&2
118

119
120
121
# 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$$"
122
123
trap "rm -fv $tmpFile >/dev/null; exit 0" EXIT TERM INT

124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# 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
147
148
149
process()
{
    local appName="$1"
150
    local outFile="$outputDir/${appName##*/}"
151
152
153

    rm -f "$outFile"*;

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

156
    # Check that it looks ok
157
158
    if grep -F -q "SYNOPSIS" "$tmpFile" 2>/dev/null
    then
159
160
161
162
163
164
165
166
167
168
169
170
171
        case "$outputType" in
        pdf)
            groff -man "$tmpFile" | ps2pdf - "$outFile.$outputExt"
            ;;

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

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

173
        echo "$outFile.$outputExt" 1>&2
174
    else
175
        echo "Problem with ${appName##*/}" 1>&2
176
177
178
    fi
}

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

# 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


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