Blame view

mkdocktb 8.17 KB
12927b0c   Mario Lang   Imported Upstream...
1
2
3
4
5
#!/bin/bash -p
###############################################################################
# BRLTTY - A background process providing access to the console screen (when in
#          text mode) for a blind person using a refreshable braille display.
#
ec859a60   samuel thibault   New upstream vers...
6
# Copyright (C) 1995-2018 by The BRLTTY Developers.
12927b0c   Mario Lang   Imported Upstream...
7
8
9
10
#
# BRLTTY comes with ABSOLUTELY NO WARRANTY.
#
# This is free software, placed under the terms of the
ec859a60   samuel thibault   New upstream vers...
11
12
13
# GNU Lesser General Public License, as published by the Free Software
# Foundation; either version 2.1 of the License, or (at your option) any
# later version. Please see the file LICENSE-LGPL for details.
12927b0c   Mario Lang   Imported Upstream...
14
#
ca6019f1   Mario Lang   Imported Upstream...
15
# Web Page: http://brltty.com/
12927b0c   Mario Lang   Imported Upstream...
16
17
18
19
#
# This software is maintained by Dave Mielke <dave@mielke.cc>.
###############################################################################

ca6019f1   Mario Lang   Imported Upstream...
20
21
defaultOutputRoot="doc-ktb"

12927b0c   Mario Lang   Imported Upstream...
22
. "`dirname "${0}"`/prologue.sh"
ca6019f1   Mario Lang   Imported Upstream...
23
24
25
26
27
addProgramOption s string.directory sourceRoot "top-level directory of source tree" "the location of this script"
addProgramOption b string.directory buildRoot "top-level directory of build tree" "the source tree"
addProgramOption o string.directory outputRoot "top-level directory of output tree" "${defaultOutputRoot}"
addProgramOption k flag keepFiles "don't remove intermediate files"
parseProgramArguments "${@}"
12927b0c   Mario Lang   Imported Upstream...
28
29
30
31
32

set -e
umask 022
shopt -s nullglob

ca6019f1   Mario Lang   Imported Upstream...
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
[ -n "${sourceRoot}" ] || sourceRoot="$(dirname "${0}")"
verifyInputDirectory "${sourceRoot}"
sourceRoot="$(cd "${sourceRoot}" && pwd)"

[ -n "${buildRoot}" ] || buildRoot="${sourceRoot}"
buildRoot="$(cd "${buildRoot}" && pwd)"

[ -n "${outputRoot}" ] || outputRoot="${defaultOutputRoot}"
verifyOutputDirectory "${outputRoot}"

unset HOME
export XDG_CONFIG_HOME=/
export XDG_CONFIG_DIRS=/

readonly newLine=$'\n'

declare -a tocLines

addTocLine() {
   local line="${1}"

   tocLines[${#tocLines[*]}]="${line}"
}

addTocEntry() {
   local title="${1}"
   local anchor="${2}"

   addTocLine "<LI><A HREF=\"#${anchor}\">${title}</A></LI>"
}

a80ccd3b   samuel thibault   Imported Upstream...
64
declare -a documentLines
ca6019f1   Mario Lang   Imported Upstream...
65

a80ccd3b   samuel thibault   Imported Upstream...
66
67
addLine() {
   local line="${1}"
12927b0c   Mario Lang   Imported Upstream...
68

a80ccd3b   samuel thibault   Imported Upstream...
69
70
71
   documentLines[${#documentLines[*]}]="${line}"
}

ca6019f1   Mario Lang   Imported Upstream...
72
73
74
75
76
77
addAnchor() {
   local anchor="${1}"

   addLine "<A NAME=\"${anchor}\"></A>"
}

a80ccd3b   samuel thibault   Imported Upstream...
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
beginDocument() {
   local title="${1}"

   headerLevel=0

   addLine "<HTML>"
   addLine "<HEAD>"
   addLine "<TITLE>${title}</TITLE>"
   addLine "</HEAD>"
   addLine "<BODY>"
}

endDocument() {
   local file="${1}"

   addLine "</BODY>"
   addLine "</HTML>"
ca6019f1   Mario Lang   Imported Upstream...
95
   addTocLine "<HR>"
12927b0c   Mario Lang   Imported Upstream...
96

ca6019f1   Mario Lang   Imported Upstream...
97
98
99
100
101
   local docCount="${#documentLines[*]}"
   local docIndex=0

   local tocCount="${#tocLines[*]}"
   local tocIndex=0
a80ccd3b   samuel thibault   Imported Upstream...
102
103

   exec 3>"${file}"
ca6019f1   Mario Lang   Imported Upstream...
104
105
106
107
108
109
110
111
112
113
114
115
116
117
      while ((docIndex < tocStart))
      do
         echo >&3 "${documentLines[docIndex++]}"
      done

      while ((tocIndex < tocCount))
      do
         echo >&3 "${tocLines[tocIndex++]}"
      done

      while ((docIndex < docCount))
      do
         echo >&3 "${documentLines[docIndex++]}"
      done
a80ccd3b   samuel thibault   Imported Upstream...
118
   exec 3>&-
12927b0c   Mario Lang   Imported Upstream...
119
120
121
122
123
}

beginSection() {
   local title="${1}"

ca6019f1   Mario Lang   Imported Upstream...
124
125
126
127
   local anchor="${title,,?}"
   anchor="${anchor//[^a-zA-Z_0-9]/-}"
   addAnchor "${anchor}"

12927b0c   Mario Lang   Imported Upstream...
128
   headerLevel=$((headerLevel + 1))
a80ccd3b   samuel thibault   Imported Upstream...
129
   addLine "<H${headerLevel}>${title}</H${headerLevel}>"
ca6019f1   Mario Lang   Imported Upstream...
130
131
132
133
134
135
136
137

   if ((headerLevel == 1))
   then
      tocStart="${#documentLines[*]}"
      addTocLine "<UL>"
   else
      addTocEntry "${title}" "${anchor}"
   fi
12927b0c   Mario Lang   Imported Upstream...
138
139
140
}

endSection() {
ca6019f1   Mario Lang   Imported Upstream...
141
   ((headerLevel > 1)) || addTocLine "</UL>"
12927b0c   Mario Lang   Imported Upstream...
142
143
144
145
146
147
148
149
150
   headerLevel=$((headerLevel - 1))
}

beginLayoutList() {
   layoutListed=false
}

endLayoutList() {
   ! "${layoutListed}" || {
a80ccd3b   samuel thibault   Imported Upstream...
151
      addLine "</UL>"
12927b0c   Mario Lang   Imported Upstream...
152
153
154
   }
}

a80ccd3b   samuel thibault   Imported Upstream...
155
156
beginLayoutEntry() {
   local prefix="${1}"
ca6019f1   Mario Lang   Imported Upstream...
157
   local outputExtension="${2}"
a80ccd3b   samuel thibault   Imported Upstream...
158
159
160

   local layout="${inputFile##*/}"
   layout="${layout%.*}"
a80ccd3b   samuel thibault   Imported Upstream...
161

ca6019f1   Mario Lang   Imported Upstream...
162
   outputFile="${outputRoot}/${prefix}-${layout}.${outputExtension}"
a80ccd3b   samuel thibault   Imported Upstream...
163
164
165
}

endLayoutEntry() {
12927b0c   Mario Lang   Imported Upstream...
166
167
   local category="${1}"

ca6019f1   Mario Lang   Imported Upstream...
168
   exec 4<"${outputFile%.*}.${plainTextExtension}"
12927b0c   Mario Lang   Imported Upstream...
169
170
171
172
173
   local description
   read -r -u 4 description
   exec 4<&-

   description="${description} "
c100d13a   Mario Lang   Imported Upstream...
174
   description="${description#*: }"
12927b0c   Mario Lang   Imported Upstream...
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
   [ -z "${category}" ] || description="${description#${category} }"
   description="${description% }"

   local prefix="All Models"
   [ -z "${description}" ] || {
      if [ "${description}" = "${description#(}" ]
      then
         prefix=""
      else
         prefix="${prefix} "
      fi
   }
   description="${prefix}${description}"

   "${layoutListed}" || {
      layoutListed=true
a80ccd3b   samuel thibault   Imported Upstream...
191
      addLine "<UL>"
12927b0c   Mario Lang   Imported Upstream...
192
193
   }

a80ccd3b   samuel thibault   Imported Upstream...
194
   addLine "<LI><A HREF=\"${outputFile##*/}\">${description}</A>"
12927b0c   Mario Lang   Imported Upstream...
195
196
}

ca6019f1   Mario Lang   Imported Upstream...
197
198
listKeyTable() {
   local prefix="${1}"
12927b0c   Mario Lang   Imported Upstream...
199

ca6019f1   Mario Lang   Imported Upstream...
200
201
202
   local input="${prefix}-${inputFile##*/}"
   local output="${outputFile%.*}"
   local name="${output##*/}"
12927b0c   Mario Lang   Imported Upstream...
203

ca6019f1   Mario Lang   Imported Upstream...
204
205
206
207
208
   local command=( "${keyTableLister}" -D"${buildRoot}/lib" -T"${sourceRoot}/${tablesSubdirectory}" )
   "${command[@]}" -l "${input}" >"${output}.${plainTextExtension}" || {
      rm -f "${output}.${plainTextExtension}"
      return 1
   }
12927b0c   Mario Lang   Imported Upstream...
209

ca6019f1   Mario Lang   Imported Upstream...
210
211
   "${command[@]}" -r "${input}" >"${output}.${reStructuredTextExtension}"
   sed -e "2a\\${newLine}* \`Help Screen Version <${name}.${plainTextExtension}>\`_" -i "${output}.${reStructuredTextExtension}"
12927b0c   Mario Lang   Imported Upstream...
212

ca6019f1   Mario Lang   Imported Upstream...
213
214
215
   rst2html --config "${sourceRoot}/docutils.conf" "${output}.${reStructuredTextExtension}" "${output}.${hypertextExtension}"
   "${keepFiles}" || rm "${output}.${reStructuredTextExtension}"
}
c100d13a   Mario Lang   Imported Upstream...
216

12927b0c   Mario Lang   Imported Upstream...
217
driversSubdirectory="Drivers/Braille"
a80ccd3b   samuel thibault   Imported Upstream...
218
driversDirectory="${sourceRoot}/${driversSubdirectory}"
12927b0c   Mario Lang   Imported Upstream...
219
220

tablesSubdirectory="Tables"
a80ccd3b   samuel thibault   Imported Upstream...
221
tablesDirectory="${sourceRoot}/${tablesSubdirectory}"
12927b0c   Mario Lang   Imported Upstream...
222

ca6019f1   Mario Lang   Imported Upstream...
223
224
225
brailleSubdirectory="Input"
keyboardSubdirectory="Keyboard"

12927b0c   Mario Lang   Imported Upstream...
226
227
228
229
braillePrefix="brl"
keyboardPrefix="kbd"

plainTextExtension="txt"
ca6019f1   Mario Lang   Imported Upstream...
230
reStructuredTextExtension="rst"
12927b0c   Mario Lang   Imported Upstream...
231
232
233
hypertextExtension="html"
keyTableExtension="ktb"

ca6019f1   Mario Lang   Imported Upstream...
234
235
236
237
keyTableLister="${buildRoot}/Programs/brltty-ktb"
make -C "${keyTableLister%/*}" -s "${keyTableLister##*/}"

documentTitle="Key Binding Lists"
a80ccd3b   samuel thibault   Imported Upstream...
238
beginDocument "${documentTitle}"
12927b0c   Mario Lang   Imported Upstream...
239
240
beginSection "${documentTitle}"

ca6019f1   Mario Lang   Imported Upstream...
241
242
243
244
245
246
247
248
beginSection "Computer Keyboard Bindings"
addLine "In order to use one of these keyboard tables,"
addLine "you need to explicitly specify it in one of the following ways:"
addLine "<UL>"
addLine "<LI>Use BRLTTY's <TT>-k</TT> (or <TT>--keyboard-table=</TT>) command line option."
addLine "<LI>Use the <TT>keyboard-table</TT> configuration file (<TT>brltty.conf</TT>) directive."
addLine "</UL>"

12927b0c   Mario Lang   Imported Upstream...
249
beginLayoutList
ca6019f1   Mario Lang   Imported Upstream...
250
set -- "${tablesDirectory}/${keyboardSubdirectory}/"*".${keyTableExtension}"
12927b0c   Mario Lang   Imported Upstream...
251
252
for inputFile
do
ca6019f1   Mario Lang   Imported Upstream...
253
254
   beginLayoutEntry "${keyboardPrefix}" "${hypertextExtension}"
   listKeyTable "${keyboardPrefix}" || continue
a80ccd3b   samuel thibault   Imported Upstream...
255
   endLayoutEntry
12927b0c   Mario Lang   Imported Upstream...
256
257
done
endLayoutList
a80ccd3b   samuel thibault   Imported Upstream...
258
addLine "<HR>"
12927b0c   Mario Lang   Imported Upstream...
259
260
endSection

ca6019f1   Mario Lang   Imported Upstream...
261
262
263
264
265
266
beginSection "Braille Device Bindings"
addLine "The driver automatically selects the appropriate key table for the device model being used."
addLine "Click on the driver's name for general information about it."
addLine "Click on the device model for its key bindings."

addTocLine "<LI><UL>"
a80ccd3b   samuel thibault   Imported Upstream...
267
addLine "<DL>"
ca6019f1   Mario Lang   Imported Upstream...
268

12927b0c   Mario Lang   Imported Upstream...
269
270
271
for driverDirectory in "${driversDirectory}/"*
do
   [ -d "${driverDirectory}" ] || continue
a80ccd3b   samuel thibault   Imported Upstream...
272

12927b0c   Mario Lang   Imported Upstream...
273
274
275
276
277
278
   driverName="${driverDirectory##*/}"
   driverCode="$(sed -n '/^DRIVER_CODE *=/s/^.*= *\([^ ]*\).*$/\1/p' "${driverDirectory}/Makefile.in")"

   header="${driverName}"
   inputFile="${driverDirectory}/README"
   [ ! -f "${inputFile}" ] || {
a80ccd3b   samuel thibault   Imported Upstream...
279
      outputFile="${outputRoot}/${braillePrefix}-${driverCode}.${plainTextExtension}"
12927b0c   Mario Lang   Imported Upstream...
280
281
282
      cp -a -- "${inputFile}" "${outputFile}"
      header="<A HREF=\"${outputFile##*/}\">${header}</A>"
   }
ca6019f1   Mario Lang   Imported Upstream...
283
284
285
286

   anchor="${braillePrefix}-${driverCode}"
   addTocEntry "${driverName}" "${anchor}"
   addAnchor "${anchor}"
a80ccd3b   samuel thibault   Imported Upstream...
287
   addLine "<DT>${header}<DD>"
12927b0c   Mario Lang   Imported Upstream...
288
289

   beginLayoutList
ca6019f1   Mario Lang   Imported Upstream...
290
   set -- "${tablesDirectory}/${brailleSubdirectory}/${driverCode}/"*".${keyTableExtension}"
12927b0c   Mario Lang   Imported Upstream...
291
292
293
294
   if [ "${#}" -gt 0 ]
   then
      for inputFile
      do
ca6019f1   Mario Lang   Imported Upstream...
295
296
         beginLayoutEntry "${braillePrefix}-${driverCode}" "${hypertextExtension}"
         listKeyTable "${braillePrefix}-${driverCode}" "${hypertextExtension}" || continue
a80ccd3b   samuel thibault   Imported Upstream...
297
         endLayoutEntry "${driverName}"
12927b0c   Mario Lang   Imported Upstream...
298
299
      done
   else
ca6019f1   Mario Lang   Imported Upstream...
300
      set -- "${tablesDirectory}/${brailleSubdirectory}/${driverCode}/"*".${plainTextExtension}"
12927b0c   Mario Lang   Imported Upstream...
301
302
      for inputFile
      do
ca6019f1   Mario Lang   Imported Upstream...
303
         beginLayoutEntry "${braillePrefix}-${driverCode}" "${plainTextExtension}"
12927b0c   Mario Lang   Imported Upstream...
304
         cp -a -- "${inputFile}" "${outputFile}"
a80ccd3b   samuel thibault   Imported Upstream...
305
         endLayoutEntry "${driverName}"
12927b0c   Mario Lang   Imported Upstream...
306
307
308
309
310
      done
   fi

   endLayoutList
done
ca6019f1   Mario Lang   Imported Upstream...
311

a80ccd3b   samuel thibault   Imported Upstream...
312
addLine "</DL>"
ca6019f1   Mario Lang   Imported Upstream...
313
314
addTocLine "</UL></LI>"

a80ccd3b   samuel thibault   Imported Upstream...
315
addLine "<HR>"
12927b0c   Mario Lang   Imported Upstream...
316
317
318
endSection

endSection
a80ccd3b   samuel thibault   Imported Upstream...
319
endDocument "${outputRoot}/index.${hypertextExtension}"
12927b0c   Mario Lang   Imported Upstream...
320
exit 0