~ubuntu-branches/ubuntu/vivid/liblouisxml/vivid : revision 6

1

2

<head>

3

<title>Liblouisxml User's and Programmer's Manual</title>

4

5

6

7

8

9

<!--

10

This manual is for liblouisxml (version 2.0.0,

11

20 August 2009), an xml to Braille Translation Library.

12

13

This file may contain code borrowed from the Linux screenreader

14

15

BRLTTY Team.

16

17

18

19

Abilitiessoft, Inc. `www.abilitiessoft.com'.

20

21

This file is free software; you can redistribute it and/or modify

22

it under the terms of the GNU Lesser (or library) General Public

23

License (LGPL) as published by the Free Software Foundation;

24

either version 3, or (at your option) any later version.

25

26

This file is distributed in the hope that it will be useful, but

27

WITHOUT ANY WARRANTY; without even the implied warranty of

28

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

29

Lesser (or Library) General Public License LGPL for more details.

30

31

You should have received a copy of the GNU Lesser (or Library)

32

General Public License (LGPL) along with this program; see the

33

file COPYING. If not, write to the Free Software Foundation, 51

34

Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

35

-->

36

37

38

pre.display { font-family:inherit }

39

pre.format { font-family:inherit }

40

pre.smalldisplay { font-family:inherit; font-size:smaller }

41

pre.smallformat { font-family:inherit; font-size:smaller }

42

pre.smallexample { font-size:smaller }

43

pre.smalllisp { font-size:smaller }

44

span.sc { font-variant:small-caps }

45

span.roman { font-family:serif; font-weight:normal; }

46

span.sansserif { font-family:sans-serif; font-weight:normal; }

47

--></style>

48

</head>

49

<body>

50

<h1 class="settitle">Liblouisxml User's and Programmer's Manual</h1>

51

52

<h2>Table of Contents</h2>

53

<ul>

54

<li><a name="toc_Top" href="#Top">Liblouisxml User's and Programmer's Manual</a>

55

<li><a name="toc_Introduction" href="#Introduction">1 Introduction</a>

56

<li><a name="toc_Transcribing-with-the-xml2brl-program" href="#Transcribing-with-the-xml2brl-program">2 Transcribing with the xml2brl program</a>

57

<ul>

58

<li><a href="#Transcribing-Microsoft-Word-Files-with-msword2brl">2.1 Transcribing Microsoft Word Files with msword2brl</a>

59

</li></ul>

60

<li><a name="toc_Customization-Configuring-liblouisxml" href="#Customization-Configuring-liblouisxml">3 Customization: Configuring liblouisxml</a>

61

<ul>

62

<li><a href="#outputFormat">3.1 outputFormat</a>

63

<li><a href="#translation">3.2 translation</a>

64

65

<li><a href="#style">3.4 style</a>

66

<ul>

67

<li><a href="#style">3.4.1 style document</a>

68

<li><a href="#style">3.4.2 style arith</a>

69

<li><a href="#style">3.4.3 style attribution</a>

70

<li><a href="#style">3.4.4 style biblio</a>

71

<li><a href="#style">3.4.5 style blankLineBefore</a>

72

<li><a href="#style">3.4.6 style caption</a>

73

<li><a href="#style">3.4.7 style code</a>

74

<li><a href="#style">3.4.8 style contentsheader</a>

75

<li><a href="#style">3.4.9 style contents1</a>

76

<li><a href="#style">3.4.10 style contents2</a>

77

<li><a href="#style">3.4.11 style contents3</a>

78

<li><a href="#style">3.4.12 style contents4</a>

79

<li><a href="#style">3.4.13 style dedication</a>

80

<li><a href="#style">3.4.14 style directions</a>

81

<li><a href="#style">3.4.15 style dispmath</a>

82

<li><a href="#style">3.4.16 style disptext</a>

83

<li><a href="#style">3.4.17 style exercise1</a>

84

<li><a href="#style">3.4.18 style exercise2</a>

85

<li><a href="#style">3.4.19 style exercise3</a>

86

<li><a href="#style">3.4.20 style glossary</a>

87

<li><a href="#style">3.4.21 style graphLabel</a>

88

<li><a href="#style">3.4.22 style heading1</a>

89

<li><a href="#style">3.4.23 style heading2</a>

90

<li><a href="#style">3.4.24 style heading3</a>

91

<li><a href="#style">3.4.25 style heading4</a>

92

<li><a href="#style">3.4.26 style indexx</a>

93

<li><a href="#style">3.4.27 style list</a>

94

<li><a href="#style">3.4.28 style matrix</a>

95

<li><a href="#style">3.4.29 style music</a>

96

<li><a href="#style">3.4.30 style note</a>

97

<li><a href="#style">3.4.31 style para</a>

98

<li><a href="#style">3.4.32 style quotation</a>

99

<li><a href="#style">3.4.33 style section</a>

100

<li><a href="#style">3.4.34 style spatial</a>

101

<li><a href="#style">3.4.35 style stanza</a>

102

<li><a href="#style">3.4.36 style style1</a>

103

<li><a href="#style">3.4.37 style style2</a>

104

<li><a href="#style">3.4.38 style style3</a>

105

<li><a href="#style">3.4.39 style style4</a>

106

<li><a href="#style">3.4.40 style style5</a>

107

<li><a href="#style">3.4.41 style subsection</a>

108

<li><a href="#style">3.4.42 style table</a>

109

<li><a href="#style">3.4.43 style titlepage</a>

110

<li><a href="#style">3.4.44 style trnote</a>

111

<li><a href="#style">3.4.45 style volume</a>

112

</li></ul>

113

</li></ul>

114

<li><a name="toc_Connecting-with-the-xml-Document" href="#Connecting-with-the-xml-Document">4 Connecting with the xml Document - Semantic-Action Files</a>

115

<ul>

116

<li><a href="#Semantic-Actions-Overview">4.1 Overview</a>

117

<li><a href="#Semantic-Actions-in-detail">4.2 Semantic Actions in detail</a>

118

</li></ul>

119

<li><a name="toc_Special-Features" href="#Special-Features">5 Special Features</a>

120

<ul>

121

<li><a href="#Table-of-contents">5.1 Table of contents</a>

122

</li></ul>

123

<li><a name="toc_Implementing-Braille-Mathematics-Codes" href="#Implementing-Braille-Mathematics-Codes">6 Implementing Braille Mathematics Codes</a>

124

<li><a name="toc_Programming-with-liblouisxml" href="#Programming-with-liblouisxml">7 Programming with liblouisxml</a>

125

<ul>

126

<li><a href="#License">7.1 License</a>

127

<li><a href="#Overview">7.2 Overview</a>

128

<li><a href="#Files-and-Paths">7.3 Files and Paths</a>

129

<li><a href="#lbx_005fversion">7.4 lbx_version</a>

130

<li><a href="#lbx_005finitialize">7.5 lbx_initialize</a>

131

<li><a href="#lbx_005ftranslateString">7.6 lbx_translateString</a>

132

<li><a href="#lbx_005ftranslateFile">7.7 lbx_translateFile</a>

133

<li><a href="#lbx_005ftranslateTextFile">7.8 lbx_translateTextFile</a>

134

<li><a href="#lbx_005fbackTranslateFile">7.9 lbx_backTranslateFile</a>

135

136

</li></ul>

137

<li><a name="toc_Configuration-Settings-Index" href="#Configuration-Settings-Index">Configuration Settings Index</a>

138

<li><a name="toc_Semantic-Action-Index" href="#Semantic-Action-Index">Semantic Action Index</a>

139

<li><a name="toc_Function-Index" href="#Function-Index">Function Index</a>

140

<li><a name="toc_Program-Index" href="#Program-Index">Program Index</a>

141

</li></ul>

142

</div>

143

144

145

146

147

148

<h2 class="unnumbered">Liblouisxml User's and Programmer's Manual</h2>

149

150

This manual is for liblouisxml (version 2.0.0,

151

20 August 2009), an xml to Braille Translation Library.

152

153

This file may contain code borrowed from the Linux screenreader

154

155

<acronym>BRLTTY</acronym> Team.

156

157

158

159

Abilitiessoft, Inc. <a href="www.abilitiessoft.com">www.abilitiessoft.com</a>.

160

161

162

This file is free software; you can redistribute it and/or modify it

163

under the terms of the GNU Lesser (or library) General Public License

164

(LGPL) as published by the Free Software Foundation; either version 3,

165

or (at your option) any later version.

166

167

This file is distributed in the hope that it will be useful, but

168

WITHOUT ANY WARRANTY; without even the implied warranty of

169

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

170

Lesser (or Library) General Public License LGPL for more details.

171

172

You should have received a copy of the GNU Lesser (or Library) General

173

Public License (LGPL) along with this program; see the file COPYING.

174

If not, write to the Free Software Foundation, 51 Franklin Street,

175

Fifth Floor, Boston, MA 02110-1301, USA.

176

</blockquote>

177

178

179

180

<h2 class="chapter">1 Introduction</h2>

181

182

liblouisxml is a software component which can be incorporated into

183

software packages to provide the capability of translating any file in

184

the computer lingua franca xml format into properly transcribed

185

braille. This includes translation into grade two, if desired,

186

mathematical codes, etc. It also includes formatting according to a

187

built-in style sheet which can be modified by the user. The first

188

program into which liblouisxml has been incorporated is

189

<samp>xml2brl</samp>. This program will translate an xml or text file

190

into an embosser-ready braille file. It is not necessary to know xml,

191

because MSWord and other word processors can export files in this

192

format. If the word processor has been used correctly

193

<samp>xml2brl</samp> will produce an excellent braille file.

194

195

There is a Mac GUI application incorporating liblouisxml called

196

<samp>louis</samp>. For a link to it go to

197

<a href="www.abilitiessoft.com/downloads">www.abilitiessoft.com/downloads</a>. A similar Windows application

198

is in the works.

199

200

Users who want to generate Braille using <samp>xml2brl</samp> will be

201

interested in <a href="#Transcribing-with-the-xml2brl-program">Transcribing with the xml2brl program</a>. Those who

202

wish to change the output generated by liblouisxml should read

203

<a href="#Customization-Configuring-liblouisxml">Customization Configuring liblouisxml</a>. If you encounter a type

204

of xml file with which liblouisxml is not familiar you can learn how

205

to tell it how to process that file by reading <a href="#Connecting-with-the-xml-Document">Connecting with the xml Document</a>. If you wish to implement a new braille mathematics

206

code read <a href="#Implementing-Braille-Mathematics-Codes">Implementing Braille Mathematics Codes</a>. Finally,

207

computer programmers who wish to use liblouisxml in their software can

208

find the information they need in <a href="#Programming-with-liblouisxml">Programming with liblouisxml</a>.

209

210

You will also find it advantageous to be acquainted with the companion

211

library liblouis, which is a braille translator and back-translator

212

(see <a href="liblouis.html#Top">Overview</a>).

213

214

215

216

<h2 class="chapter">2 Transcribing with the xml2brl program</h2>

217

218

219

At the moment, actual transcription with liblouisxml is done with the

220

command-line (or console) program <samp>xml2brl</samp>. The line to type

221

is:

222

223

<pre class="example"> xml2brl [OPTIONS] [-f config-file] [infile] [outfile]

224

</pre>

225

The brackets indicate that something is optional. You will see that

226

nothing is required except the program name itself, <samp>xml2brl</samp>.

227

The various optional parts control how the program will behave, as

228

follows:

229

230

<dl>

231

<dt><samp>-h</samp><dd>This option causes <samp>xml2brl</samp> to print a help message

232

describing usage and exit.

233

234

<dt><samp>-l</samp><dd>This option will cause <samp>xml2brl</samp> and liblouisxml to print

235

error messages to <samp>xml2brl.log</samp> instead of stderr. The file will

236

be in the current directory. This option is particularly useful if

237

<samp>xml2brl</samp> is called by a GUI script or Web application.

238

239

<dt><samp>-f configfile</samp><dd>This specifies the configuration file which tells <samp>xml2brl</samp>

240

how to do the transcription. (It may be a list of file names separated

241

by commas.) This file specifies such things as the number of cells per

242

line, the number of lines per page, The translation tables to be used,

243

how paragraphs and headings are to be formatted, etc. If this part of

244

the command line is omitted, <samp>xml2brl</samp> assumes that the

245

configuration file is named <samp>default.cfg</samp>. If the configuration

246

file name contains a pathname <samp>xml2brl</samp> will consider this as

247

a path on which to look for files that it needs (see <a href="#Files-and-Paths">Files and Paths</a>). If no pathname is given the standard paths are searched and

248

finally the current directory.

249

250

<dt><samp>-Csetting=value</samp><dd>This option enables you to specify configuration settings on the

251

command line instead of changing the configuration file. You can use

252

as many <samp>-C</samp> options as you wish. Any settings can be specified

253

except those having to do with styles. The settings may be in any

254

order. They override any settings in <samp>canonical.cfg</samp> or in the

255

configuration file used by <samp>xml2brl</samp>.

256

257

<dt><samp>-b</samp><dd>back-translate. The input file must be a braille file, such as

258

<samp>.brf</samp>. The output file is a back-translation of this file. It

259

may be in either plain-text or xhtml (html), according to the setting

260

of <code>backFormat</code> in the <code>outputFormat</code> section of the

261

configuration file. Html files will contain page numbers and emphasis.

262

To get good html, the liblouis table must have the entry `<samp>space

263

\e 1b</samp>' so that it will pass through escape characters. The

264

<samp>html.sem</samp> file must also contain the line `<samp>pagenum

265

pagenum</samp>'. Text output files simply have a blank line between

266

paragraphs. Encoding of text files is controlled by the

267

<code>outputEncoding</code> setting. Html files are always in UTF-8.

268

269

<dt><samp>-r</samp><dd>Reformat. The input file must be a braille file, such as <samp>.brf</samp>.

270

The output is a braille file formatted according to the configuration

271

file. It is advisable to set backFormat to html, since this will

272

preserve print page numbers and emphasis. This program can be useful

273

for changing the line length and page length of a braille file, for

274

example, from 40 to 32 cells. It is also an excellent way to check the

275

accuracy of liblouis tables. The original page numbers at the tops and

276

bottoms of pages are discarded, and new ones are generated.

277

278

<dt><samp>-p</samp><dd>Poorly formatted input translation. Infile is any text file such as may

279

have been obtained by extracting the text in a pdf file. The input

280

file may also be an xml or html file which is so poorly formatted that

281

better braille can be obtained by ignoring the formatting.

282

<samp>xml2brl</samp> tries to guess paragraph breaks. The output is

283

generally reasonably formatted, that is, with reasonable paragraph

284

breaks.

285

286

<dt><samp>-t</samp><dd>The document is an h(t)ml file, not xhtml. This option is useful with

287

files downloaded from the Web in source form. Without it, the program

288

will first try to parse the file as an xml document, producing lots of

289

error messages. It will then try the html parser. With this option, it

290

goes directly to the html parser. See also the formatFor configuration

291

(see <a href="#formatFor-setting">formatFor setting</a>) file setting, which enables you to format

292

the braille output for viewing in a browser.

293

294

<dt><samp>infile</samp><dd>This is the name of the input file containing the material to be

295

transcribed. The file may be either an xml file or a text file. The

296

<samp>-b</samp>, <samp>-r</samp> and <samp>-p</samp> options discussed above

297

provide for other types of files and processing. Typical xml files are

298

those provided by <a href="www.bookshare.org">www.bookshare.org</a> or those derived from a

299

word processor by saving in xml format. If a text file is used

300

paragraphs and headings should be separated by blank lines. In such a

301

file there is no way to distinguish between paragraphs and headings,

302

so they will all be formatted as paragraphs, as specified by the

303

configuration file. However, if you want a blank line in the braille

304

transcription use two consecutive blank lines in the text file.

305

306

<dt><samp>outfile</samp><dd>This is the name of the output file. It will be transcribed as

307

specified by the configuration file and the <samp>-C</samp> configuration

308

settings.

309

The following paragraphs provide more information on both the input

310

and output files.

311

312

</dl>

313

314

<samp>xml2brl</samp> is set up so that it can be used in a "pipe". To do

315

this, omit both infile and outfile. Input is then taken from the

316

standard input unit.

317

318

The first file name encountered (a word not preceded by a minus sign)

319

is taken to be the input file and the second to be the output file. If

320

you wish input to be taken from stdin and still want to specify an

321

output file use two minus signs (`<samp>--</samp>') for the input file.

322

323

If only the program name is typed <samp>xml2brl</samp> assumes that the

324

configuration file is <samp>default.cfg</samp>, input is from the standard

325

input unit, and output is to the standard output unit.

326

327

328

329

<h3 class="section">2.1 Transcribing Microsoft Word Files with msword2brl</h3>

330

331

332

<pre class="example"> msword2brl infile outfile

333

</pre>

334

Infile must be a Microsoft Word file. The script first calls the

335

<samp>antiword</samp> program, so you must have this installed on your

336

machine. <samp>antiword</samp> is called with <samp>-x db</samp>, which

337

causes the output to be in docbook format. This is piped to

338

<samp>xml2brl</samp>. The output file from <samp>xml2brl</samp> contains

339

much of the formatting, including emphasis, of the word file.

340

341

342

343

<h2 class="chapter">3 Customization: Configuring liblouisxml</h2>

344

345

The operation of liblouisxml is controlled by two types of files:

346

semantic-action files and configuration files. The former are

347

discussed in the section Connecting with the xml Document -

348

Semantic-action Files (see <a href="#Connecting-with-the-xml-Document">Connecting with the xml Document - Semantic-Action Files</a>). The latter are

349

discussed in this section. A third type of file, braille translation

350

tables, is discussed in the liblouis documentation (see <a href="liblouis.html#Top">Overview</a>).

351

Another section of the present document which may be of interest is

352

Implementing Braille Mathematical Codes (see <a href="#Implementing-Braille-Mathematics-Codes">Implementing Braille Mathematics Codes</a>).

353

354

liblouisxml (with liblouis) can be used as the braille transcription

355

component in any number of applications with different overall

356

purposes and user interfaces. However, as of now the principal

357

application is <samp>xml2brl</samp>, which is a console application for

358

Mac and Linux. (There is also a Mac GUI application called louis.) The

359

information below therefore applies to <samp>xml2brl</samp> as much as to

360

liblouisxml.

361

362

Before discussing configuration files in detail it is worth noting

363

that the application program has access to the information in the

364

configuration files by calling the liblouisxml function

365

<code>lbx_initialize</code>. This function returns a pointer to a data

366

structure containing the configuration information.

367

368

<samp>xml2brl</samp> uses the configuration file <samp>default.cfg</samp>

369

unless a different one is specified via the <samp>-f</samp> command-line

370

option. The configuration file name may include a full path. In this

371

case, liblouisxml will consider this to be the user path (see <a href="#Files-and-Paths">Files and Paths</a>). If just a file name (or list) is given, liblouisxml will

372

consider the current directory as the user path.

373

374

The configuration "file" specified with the <samp>-f</samp> option need

375

not be a single filename. It can be several file names separated by

376

commas. Only the first filename may have a path component. This path

377

is taken as the user path, as discussed in the previous paragraph.

378

This file-list feature is also found in liblouis. It enables you to

379

combine configuration files on the command line. For example, a file

380

list may consist of one file specifying the output format used in your

381

establishment, a comma, and then the name of a stylesheet.

382

383

After the path, if any, has been evaluated, but before reading any of

384

the files, liblouisxml reads in a file called <samp>canonical.cfg</samp>.

385

This file specifies values for all possible settings. It is needed to

386

complete the initialization of the program. You may alter the values

387

in the distribution <samp>canonical.cfg</samp>, but you should not delete

388

any settings. Do not specify <samp>canonical.cfg</samp> as your

389

configuration file. This will lead to error messages and program

390

termination. If a configuration file read in later contains a

391

particular setting name, the value specified simply replaces the one

392

specified in <samp>canonical.cfg</samp>.

393

394

As you will see by looking at <samp>canonical.cfg</samp>, it contains four

395

main sections, <code>outputFormat</code>, <code>translation</code>, <code>xml</code> and

396

<code>styles</code>. In addition, a configuration file can contain an

397

include entry. This causes the file named on that line to be read in

398

at the point where the line occurs. The sections need not follow each

399

other in any particular order, nor is the order of settings within

400

each section important. In this document and in the

401

<samp>canonical.cfg</samp> file, where section and setting names consist of

402

more than one word, the first letter of each word following the

403

initial one is capitalized. This is merely for readability. The case

404

of the letters in these names is ignored by the program. Section and

405

setting names may not contain spaces.

406

407

Here, then, is an explanation of each section and setting in the

408

<samp>canonical.cfg</samp> file. When you look at this file you will see

409

that the section names start at the left margin, while the settings

410

are indented one tab stop. This is done for readability. it has no

411

effect on the meaning of the lines. You will also see lines beginning

412

with a number sign (`<samp>#</samp>'), which are comments. Blank lines can

413

also be used anywhere in a configuration file. In general, a section

414

name is a single word or combination of unspaced words. However, each

415

style has a section of its own, so the word `<samp>style</samp>' is followed

416

by the name of the style. Setting lines begin with the name of the

417

setting, followed by at least one space or tab, followed by the value

418

of the setting. A few settings have two values.

419

420

421

422

<h3 class="section">3.1 outputFormat</h3>

423

424

This section specifies the format of the output file (or string, if no

425

file name is given).

426

427

428

429

<dl><dt><code>cellsPerLine 40</code><dd>

430

The number of cells in a braille line.

431

432

<a name="index-linesPerPage-4"></a> <dt><code>linesPerPage 25</code><dd>

433

The number of lines on a braille page

434

435

<a name="index-interpoint-5"></a> <dt><code>interpoint no</code><dd>

436

Whether or not the output will be used to produce interpoint braille.

437

This affects the placement of page numbers and may affect other things

438

in the future. The only two values recognized are `<samp>yes</samp>' and

439

`<samp>no</samp>'.

440

441

<a name="index-lineEnd-6"></a> <dt><code>lineEnd \r\n</code><dd>

442

This specifies the control characters to be placed at the end of each

443

output line. These characters vary from one intended use of the output

444

to another. Most embossers require the carriage-return and line-feed

445

combination specified above. However, a braille display may work best

446

with just one or the other. Any valid control characters can be

447

specified.

448

449

<a name="index-pageEnd-7"></a> <dt><code>pageEnd \f</code><dd>

450

The control Character to be given at the end of a page. Here it is a

451

forms-feed character, but it can be something else if deeded.

452

453

<a name="index-fileEnd-8"></a> <dt><code>fileEnd ^z</code><dd>

454

The control character to be placed at the end of the file, here a

455

control-z.

456

457

<a name="index-printPages-9"></a> <dt><code>printPages yes</code><dd>

458

Whether or not to show print page numbers if they are given in the xml

459

input. The two valid values are `<samp>yes</samp>' and `<samp>no</samp>'.

460

461

<a name="index-braillePages-10"></a> <dt><code>braillePages yes</code><dd>

462

Whether or not to format the output into pages. Here the value is

463

`<samp>yes</samp>', for use with an embosser. However the user of a braille

464

display may wish to specify `<samp>no</samp>', so as not to be bothered with

465

page numbers and forms feed characters. If no is specified the lines

466

will still be of the length given in <code>cellsPerLine</code>, but the

467

value of <code>linesPerPage</code> will be ignored.

468

469

<a name="index-paragraphs-11"></a> <dt><code>paragraphs yes</code><dd>

470

Whether or not to format the output into paragraphs, using appropriate

471

styles. If `<samp>no</samp>' is specified, what would be a paragraph is output

472

simply as one long line. Applications that wish to do their own

473

formatting may specify `<samp>no</samp>'.

474

475

<a name="index-beginningPageNumber-12"></a> <dt><code>beginningPageNumber 1</code><dd>

476

This is the number to be placed on the first Braille page if

477

<code>braillePages</code> is yes. This is useful when producing multiple

478

Braille volumes.

479

480

<a name="index-printPageNumberAt-13"></a> <dt><code>printPageNumberAt top</code><dd>

481

If print page numbers are given in the xml input file they will be

482

placed at the top of each braille page in the right-hand corner. A

483

page separator line will also be produced on the braille page where

484

the print page break actually occurs. You may also specify

485

`<samp>bottom</samp>' for this setting.

486

487

<a name="index-braillePageNumberAt-14"></a> <dt><code>braillePageNumberAt bottom</code><dd>

488

The braille page number will be placed in the bottom right-hand corner

489

of each page. If interpoint yes has been specified only odd pages will

490

receive page numbers. If you specify `<samp>top</samp>' for this setting then

491

`<samp>bottom</samp>' must be specified for <code>printPageNumberAt</code>.

492

493

<a name="index-hyphenate-15"></a> <dt><code>hyphenate no</code><dd>

494

If `<samp>yes</samp>' is specified words will be hyphenated at the ends of

495

lines if a hyphenation table is available. In contracted English

496

Braille hyphenation is not generally used, but it can save

497

considerable space. The hyphenation table is specified as part of the

498

table list in the <code>literaryTextTable</code> setting of the translation

499

section.

500

501

<a name="index-outputEncoding-16"></a> <dt><code>outputEncoding ascii8</code><dd>

502

This specifies that the output is to be in the form of 8-bit ASCII

503

characters. This is generally used if the output is intended directly

504

for a braille embosser or display. The other values of encoding are

505

`<samp>UTF8</samp>', `<samp>UTF16</samp>' and `<samp>UTF32</samp>'. These are useful if the

506

application will process the output further, such as for generating

507

displays of braille dots on a screen.

508

509

<a name="index-inputTextEncoding-17"></a> <dt><code>inputTextEncoding ascii8</code><dd>

510

This setting is used to specify the encoding of an input text file.

511

The valid values are `<samp>UTF8</samp>' and `<samp>ascii8</samp>'.

512

513

514

<a name="index-formatFor-18"></a> <dt><code>formatFor textDevice</code><dd>

515

This setting specifies the type of device the output is intended for.

516

`<samp>textDevice</samp>' is any device that accepts plain text, including

517

embossers. You can also specify `<samp>browser</samp>'. In this case the

518

output will be formatted for viewing in a browser. If the input file

519

contains links, they will be preserved and can be used in the normal

520

way. The text will be translated into braille with the correct line

521

length. Math and computer material will be translated appropriately.

522

These files work well in lynx and Internet Explorer, not so well in

523

elinks and Firefox (Before Jaws 10).

524

525

<a name="index-backFormat-19"></a> <dt><code>backFormat plain</code><dd>

526

This setting specifies the format of back-translated files.

527

`<samp>Plain</samp>' specifies plain-text, while `<samp>html</samp>' specifies xhtml.

528

The latter is always encoded in UTF-8. Plain-text files can be encoded

529

in ascii8, UTF-8 or UTF-16. Html is strongly recommended, since it

530

will preserve print page numbering and emphasis.

531

532

<a name="index-backLineLength-20"></a> <dt><code>backLineLength 70</code><dd>

533

This setting specifies the length of lines in back-translated files,

534

whether in plain-text or html. This is mainly for human readability.

535

Lines may sometimes be somewhat longer.

536

537

<a name="index-interline-21"></a> <dt><code>interline no</code><dd>

538

This setting specifies whether interlining is desired. If it is set to

539

`<samp>yes</samp>', the first line in the output will be a braille

540

translation, the next line will be its back-translation according to

541

the interlineBackTable. Back-translation is used instead of simply

542

presenting the print original because a braille line may contain

543

additional information, such as leading blanks, print or braille page

544

numbers, print page separator lines, etc.

545

546

547

<a name="index-lineFill-22"></a> <dt><code>lineFill '</code><dd>

548

This setting defines the fill character that will be used before the

549

page numbers in the table of contents for example. The default fill

550

character is an apostrophe (dot 3).

551

552

</dl>

553

554

555

556

<h3 class="section">3.2 translation</h3>

557

558

This section specifies the liblouis translation tables to be used for

559

various purposes.

560

561

562

563

<dl><dt><code>literaryTextTable en-us-g2.ctb</code><dd>

564

The table used for producing literary braille. This may be either

565

contracted or uncontracted.

566

567

<a name="index-uncontractedTable-24"></a> <dt><code>uncontractedTable en-us-g1.ctb</code><dd>

568

The table used for producing uncontracted or Grade One braille. This

569

setting appears to be superfluous and may be eliminated in the future.

570

571

<a name="index-compbrailleTable-25"></a> <dt><code>compbrailleTable en-us-compbrl.ctb</code><dd>

572

The table used for producing large amounts of output in computer

573

braille, such as computer programs. The computer braille table is

574

usually combined with one of the two tables above.

575

576

<a name="index-mathtextTable-26"></a> <dt><code>mathtextTable en-us-mathtext.ctb</code><dd>

577

This table specifies how the non-mathematical parts of math books are

578

to be translated. In many cases it will be the same as

579

literaryTextTable or uncontractedTable. For books translated with the

580

Nemeth Code it is different, because this code requires modification

581

of standard Grade Two.

582

583

<a name="index-MathexpTable-27"></a> <dt><code>MathexpTable nemeth.ctb</code><dd>

584

This is the table used to translate mathematical expressions.

585

586

<a name="index-editTable-28"></a> <dt><code>editTable nemeth_edit.ctb</code><dd>

587

When the output includes both mathematics and text there may be errors

588

where one type of translation directly follows another. The editTable

589

removes these errors.

590

591

<a name="index-interlineBackTable-29"></a> <dt><code>interlineBackTable en-us-interline.ctb</code><dd>

592

This setting specifies the table to be used for back-translation when

593

interlining is turned on. It must be tailored for this purpose, since

594

an ordinary forward-translation table may contain entries that do not

595

handle the additional information in braille lines correctly.

596

597

</dl>

598

599

600

601

602

603

This section provides various information for the processing of xml files.

604

605

606

607

<dl><dt><code>semanticFiles *,nemeth.sem</code><dd>

608

This setting gives a list of semantic-action files. These files are

609

read in the sequence given in the list. Here the first member of the

610

list is an asterisk (`<samp>*</samp>'). This means that the corresponding file

611

is to be named by taking the root element of the document and

612

appending `<samp>.sem</samp>'. This asterisk member may occur anywhere in the

613

list.

614

615

<a name="index-xmlheader-31"></a> <dt><code>xmlheader <?xml version='1.0' encoding='UTF8' standalone='yes'?></code><dd>

616

This line gives the xml header to be added to strings produced by

617

programs like <samp>Mathtype</samp> that lack one.

618

619

<a name="index-entity-32"></a> <dt><code>entity nbsp ^1</code><dd>

620

This line defines an entity or substitution in an xml file. It is one

621

of those that has two values. The first is the thing to be replaced,

622

and the second is the replacement. As many entity lines as necessary

623

can be used. The information they contain is added to the information

624

provided by xmlHeader. In <samp>canonical.cfg</samp> this line is commented

625

out, because specifying it at this point would prevent the user from

626

specifying his own xmlheader.

627

628

<a name="index-internetAccess-33"></a> <dt><code>internetAccess yes</code><dd>

629

The computer has an internet connection and liblouisxml may obtain

630

information necessary for the processing of this file from the

631

Internet. If this setting is `<samp>no</samp>' liblouisxml will not try to use

632

the internet. The necessary information may, however, be provided on

633

the local machine in the form of a "dtd" file.

634

635

<a name="index-newEntries-34"></a> <dt><code>newEntries yes</code><dd>

636

liblouisxml may create a new semantic-action file (beginning with

637

<samp>new_</samp>) for a document with an unknown root element or a file

638

(beginning with <samp>appended_</samp>) containing new entries for an

639

existing semantic-action file. Both kinds of files are placed on the

640

current directory. If this setting is `<samp>no</samp>' liblouisxml will not

641

create a file of new entries and if it encounters a document with an

642

unknown root element it will issue an error message. Setting

643

newEntries to `<samp>no</samp>' may be useful if users should not be bothered

644

with the minutiae of semantic-action files.

645

646

</dl>

647

648

649

650

<h3 class="section">3.4 style</h3>

651

652

The following sections all deal with styles. Each style has its own

653

section. Style section names are unlike other section names in that

654

they consist of the word style, followed by a space, followed by a

655

style name. More styles may be added as the software develops, and

656

some may be dropped. New styles currently cannot be defined by the

657

user, because the styles already defined appear to be adequate. This

658

feature can be added if needed. There are, however, five utility

659

styles, <code>style1</code> through <code>style5</code>, which the user can employ

660

in any way.

661

662

<h4 class="subsection">3.4.1 style document</h4>

663

664

This section specifies the style of the whole document. The settings

665

given in it are applied to all other styles. If a section for another

666

style is given, the settings in it replace those from the document

667

style for that section. Because the settings in the document style

668

apply to all other styles, if a document style section is given it

669

must precede the sections for all other styles. Since

670

<samp>canonical.cfg</samp> contains a document style definition, the user

671

may not use this style.

672

673

674

675

<dl><dt><code>linesBefore 0</code><dd>

676

677

This setting gives the number of blank lines which should be left

678

before the text to which this style applies. It is set to a non-zero

679

value for some header styles.

680

681

<a name="index-linesAfter-36"></a> <dt><code>linesAfter 0</code><dd>

682

683

The number of blank lines which should be left after the text to which

684

this style applies.

685

686

<a name="index-leftMargin-37"></a> <dt><code>leftMargin 0</code><dd>

687

688

The number of cells by which the left margin of all lines in the text

689

should be indented. Used for hanging indents, among other things.

690

691

<a name="index-firstLineIndent-38"></a> <dt><code>firstLineIndent 0</code><dd>

692

693

The number of cells by which the first line is to be indented relative

694

to leftMargin. firstLineIndent may be negative. If the result is less

695

than 0 it will be set to 0.

696

697

<a name="index-translate-39"></a> <dt><code>translate contracted</code><dd>

698

699

This setting is currently inactive. It may be used in the future. This

700

setting tells how text in this style should be translated. Possible

701

values are `<samp>contracted</samp>', `<samp>uncontracted</samp>', `<samp>compbrl</samp>',

702

`<samp>mathtext</samp>' and `<samp>mathexpr</samp>'.

703

704

<a name="index-skipNumberLines-40"></a> <dt><code>skipNumberLines no</code><dd>

705

706

If this setting is `<samp>yes</samp>' the top and bottom lines on the page

707

will be skipped if they contain braille or print page numbers. This is

708

useful in some of the mathematical and graphical styles.

709

710

<a name="index-format-41"></a> <dt><code>format leftJustified</code><dd>

711

712

The format setting controls how the text in the style will be

713

formatted. Valid values are `<samp>leftJustified</samp>',

714

`<samp>rightJustified</samp>', `<samp>centered</samp>', `<samp>computerCoded</samp>',

715

`<samp>alignColumnsLeft</samp>', `<samp>alignColumnsRight</samp>', `<samp>listColumns</samp>',

716

`<samp>listLines</samp>' and `<samp>contents</samp>'. The first three are

717

self-explanatory. `<samp>computerCoded</samp>' is used for computer programs

718

and similar material. The next three are used for tabular material.

719

`<samp>alignColumnsLeft</samp>' causes the left ends of columns to be aligned.

720

`<samp>alignColumnsRight</samp>' causes the right ends of columns to be

721

aligned. `<samp>listColumns</samp>' causes columns to be placed one after the

722

other, separated by whatever separation character has been specified

723

in the semantic-action file, followed by a space. An escape character

724

(hex 1b) must also be specified to indicate the end of the column. Two

725

escape characters must be specified to indicate the end of a row.

726

Indentation of the lines in a row is controlled by the leftMargin and

727

firstLineIndent settings. `<samp>listLines</samp>' is similar except that it

728

lists lines, as in poetry stanzas. The semantic-action file must

729

specify two escape characters to indicate the end of a line.

730

`<samp>contents</samp>' is used only in styles specifically intended for

731

tables of contents.

732

733

<a name="index-newPageBefore-42"></a> <dt><code>newPageBefore no</code><dd>

734

735

If this setting is `<samp>yes</samp>', the text will begin on a new page. This

736

is useful for certain mathematical and graphical styles. Page numbers

737

are handled properly.

738

739

<a name="index-newPageAfter-43"></a> <dt><code>newPageAfter no</code><dd>

740

741

If this setting is `<samp>yes</samp>' any remaining space on the page after

742

the material covered by this style is handled is left blank, except

743

for page numbers.

744

745

<a name="index-rightHandPage-44"></a> <dt><code>rightHandPage no</code><dd>

746

747

if this setting is `<samp>yes</samp>' and interpoint is yes the material

748

covered by this style will start on a right-hand page. This may cause

749

a left-hand page to be left blank except for page numbers. If

750

interpoint is `<samp>no</samp>' this setting is equivalent to newPageBefore.

751

752

</dl>

753

754

<h4 class="subsection">3.4.2 style arith</h4>

755

756

This style is used for arithmetic examples in elementary math books.

757

On recognizing this style, the translator formats the material in a

758

special way. This style has no settings different from those of the

759

document style at the moment. Nevertheless, the line `<samp>style

760

arith</samp>' must be included in <samp>canonical.cfg</samp> so that it will be set

761

up properly.

762

763

<h4 class="subsection">3.4.3 style attribution</h4>

764

765

This style is used for an attribution following a quotation.

766

767

768

769

<dl><dt><code>format rightJustified</code><dd>

770

771

</dl>

772

773

<h4 class="subsection">3.4.4 style biblio</h4>

774

775

This style is used for bibliographies. Settings will be added later.

776

777

<h4 class="subsection">3.4.5 style blankLineBefore</h4>

778

779

This style is used automatically when a text file has three or more

780

blank lines in succession.

781

782

783

784

<dl><dt><code>linesBefore 1</code><dd>

785

786

<a name="index-firstLineIndent-47"></a> <dt><code>firstLineIndent 2</code><dd>

787

788

</dl>

789

790

<h4 class="subsection">3.4.6 style caption</h4>

791

792

This style is used for picture captions.

793

794

795

796

<dl><dt><code>leftMargin 4</code><dd>

797

798

<a name="index-firstLineIndent-49"></a> <dt><code>firstLineIndent 2</code><dd>

799

800

Note that the first line is actually indented six cells.

801

802

</dl>

803

804

<h4 class="subsection">3.4.7 style code</h4>

805

806

This style is used for computer programs.

807

808

809

810

<dl><dt><code>skipNumberLines yes</code><dd>

811

812

<a name="index-linesBefore-51"></a> <dt><code>linesBefore 1</code><dd>

813

814

<a name="index-linesAfter-52"></a> <dt><code>linesAfter 1</code><dd>

815

816

<a name="index-format-53"></a> <dt><code>format computerCode</code><dd>

817

818

</dl>

819

820

821

822

<h4 class="subsection">3.4.8 style contentsheader</h4>

823

824

This style is used to specify where the contents should be placed and

825

the title that should be given to it.

826

827

828

<dl><dt><code>linesBefore 1</code><dd>

829

<a name="index-linesAfter-55"></a> <dt><code>linesAfter 1</code><dd>

830

<a name="index-format-56"></a> <dt><code>format centered</code><dd>

831

</dl>

832

833

<h4 class="subsection">3.4.9 style contents1</h4>

834

835

This style and the other contents styles are used for the table of

836

contents and correspond to the four heading levels.

837

838

839

<dl><dt><code>firstLineIndent -2</code><dd>

840

<a name="index-leftMargin-58"></a> <dt><code>leftMargin 2</code><dd>

841

<a name="index-format-59"></a> <dt><code>format contents</code><dd>

842

</dl>

843

844

<h4 class="subsection">3.4.10 style contents2</h4>

845

846

847

848

<dl><dt><code>firstLineIndent -2</code><dd>

849

<a name="index-leftMargin-61"></a> <dt><code>leftMargin 4</code><dd>

850

<a name="index-format-62"></a> <dt><code>format contents</code><dd>

851

</dl>

852

853

<h4 class="subsection">3.4.11 style contents3</h4>

854

855

856

857

<dl><dt><code>firstLineIndent -2</code><dd>

858

<a name="index-leftMargin-64"></a> <dt><code>leftMargin 6</code><dd>

859

<a name="index-format-65"></a> <dt><code>format contents</code><dd>

860

</dl>

861

862

<h4 class="subsection">3.4.12 style contents4</h4>

863

864

865

866

<dl><dt><code>firstLineIndent -2</code><dd>

867

<a name="index-leftMargin-67"></a> <dt><code>leftMargin 8</code><dd>

868

<a name="index-format-68"></a> <dt><code>format contents</code><dd>

869

</dl>

870

871

<h4 class="subsection">3.4.13 style dedication</h4>

872

873

This style is for the dedication of a book.

874

875

876

877

<dl><dt><code>newPageBefore yes</code><dd>

878

879

<a name="index-newPageAfter-70"></a> <dt><code>newPageAfter yes</code><dd>

880

881

<a name="index-center-71"></a> <dt><code>center yes</code><dd>

882

883

</dl>

884

885

<h4 class="subsection">3.4.14 style directions</h4>

886

887

This is for giving directions for exercises.

888

889

<h4 class="subsection">3.4.15 style dispmath</h4>

890

891

This is for showing mathematics that is set off from the text.

892

893

894

895

<dl><dt><code>leftMargin 2</code><dd>

896

897

</dl>

898

899

<h4 class="subsection">3.4.16 style disptext</h4>

900

901

This if for text that is set off from the rest of the text.

902

903

904

905

<dl><dt><code>leftMargin 2</code><dd>

906

907

<a name="index-firstLineIndent-74"></a> <dt><code>firstLineIndent 2</code><dd>

908

909

</dl>

910

911

<h4 class="subsection">3.4.17 style exercise1</h4>

912

913

This is the first level in a set of exercises where there are sublevels.

914

915

916

917

<dl><dt><code>leftMargin 2</code><dd>

918

919

<a name="index-firstLineIndent-76"></a> <dt><code>firstLineIndent -2</code><dd>

920

921

</dl>

922

923

<h4 class="subsection">3.4.18 style exercise2</h4>

924

925

This is for the second level of exercises, such as exercise a following

926

exercise 1.

927

928

929

930

<dl><dt><code>leftMargin 4</code><dd>

931

932

<a name="index-firstLineIndent-78"></a> <dt><code>firstLineIndent -2</code><dd>

933

934

</dl>

935

936

<h4 class="subsection">3.4.19 style exercise3</h4>

937

938

This is for the third level of exercises.

939

940

941

942

<dl><dt><code>leftMargin 6</code><dd>

943

944

<a name="index-firstLineIndent-80"></a> <dt><code>firstLineIndent -2</code><dd>

945

946

</dl>

947

948

<h4 class="subsection">3.4.20 style glossary</h4>

949

950

This is for a glossary.

951

952

953

954

<dl><dt><code>firstLineIndent 2</code><dd>

955

956

Section: style graph

957

958

This style reserves space for a graph or other tactile material.

959

960

<a name="index-skipNumberLines-82"></a> <dt><code>skipNumberLines yes</code><dd>

961

962

</dl>

963

964

<h4 class="subsection">3.4.21 style graphLabel</h4>

965

966

This style reserves space for the label of a graph.

967

968

<h4 class="subsection">3.4.22 style heading1</h4>

969

970

This style is used for main headings, such as chapter titles.

971

972

973

974

<dl><dt><code>linesBefore 1</code><dd>

975

976

<a name="index-center-84"></a> <dt><code>center yes</code><dd>

977

978

<a name="index-linesAfter-85"></a> <dt><code>linesAfter 1</code><dd>

979

980

</dl>

981

982

<h4 class="subsection">3.4.23 style heading2</h4>

983

984

The first level of subreadings after the main heading.

985

986

987

988

<dl><dt><code>linesBefore 1</code><dd>

989

990

<a name="index-firstLineIndent-87"></a> <dt><code>firstLineIndent 4</code><dd>

991

992

</dl>

993

994

<h4 class="subsection">3.4.24 style heading3</h4>

995

996

The third level of headings.

997

998

999

1000

<dl><dt><code>firstLineIndent 4</code><dd>

1001

1002

</dl>

1003

1004

<h4 class="subsection">3.4.25 style heading4</h4>

1005

1006

The fourth and final level of headings.

1007

1008

1009

1010

<dl><dt><code>firstLineIndent 4</code><dd>

1011

1012

</dl>

1013

1014

<h4 class="subsection">3.4.26 style indexx</h4>

1015

1016

This style is used for indexes. The extra `<samp>x</samp>' is not an error. It

1017

is there to prevent conflict with names elsewhere in the software.

1018

1019

<h4 class="subsection">3.4.27 style list</h4>

1020

1021

This is for the individual items in a list.

1022

1023

1024

1025

<dl><dt><code>firstLineIndent -2</code><dd>

1026

1027

<a name="index-leftMargin-91"></a> <dt><code>leftMargin 2</code><dd>

1028

1029

</dl>

1030

1031

<h4 class="subsection">3.4.28 style matrix</h4>

1032

1033

This style causes its contents to be formatted in a way suitable for

1034

the representation of matrices.

1035

1036

1037

1038

<dl><dt><code>format alignColumnsLeft</code><dd>

1039

1040

</dl>

1041

1042

<h4 class="subsection">3.4.29 style music</h4>

1043

1044

This style is used for braille music.

1045

1046

1047

1048

<dl><dt><code>skipNumberLines yes</code><dd>

1049

1050

</dl>

1051

1052

<h4 class="subsection">3.4.30 style note</h4>

1053

1054

This style is used for footnotes.

1055

1056

<h4 class="subsection">3.4.31 style para</h4>

1057

1058

Paragraph. This is ordinary body text.

1059

1060

1061

1062

<dl><dt><code>firstLineIndent 2</code><dd>

1063

1064

</dl>

1065

1066

<h4 class="subsection">3.4.32 style quotation</h4>

1067

1068

This style is used for quotations that are set off from the rest of

1069

the text.

1070

1071

1072

1073

<dl><dt><code>linesBefore 1</code><dd>

1074

1075

<a name="index-linesAfter-96"></a> <dt><code>linesAfter 1</code><dd>

1076

1077

</dl>

1078

1079

<h4 class="subsection">3.4.33 style section</h4>

1080

1081

This style is used for a section with a section number.

1082

1083

1084

1085

<dl><dt><code>firstLineIndent 4</code><dd>

1086

1087

</dl>

1088

1089

<h4 class="subsection">3.4.34 style spatial</h4>

1090

1091

This style is used for mathematical material that is arranged

1092

spatially, such as large fractions.

1093

1094

<h4 class="subsection">3.4.35 style stanza</h4>

1095

1096

this style is used for stanzas in poetry.

1097

1098

1099

1100

<dl><dt><code>linesBefore 1</code><dd>

1101

1102

<a name="index-linesAfter-99"></a> <dt><code>linesAfter 1</code><dd>

1103

1104

<a name="index-format-100"></a> <dt><code>format listLines</code><dd>

1105

1106

</dl>

1107

1108

<h4 class="subsection">3.4.36 style style1</h4>

1109

1110

This and the subsequent numbered styles can be used by the user for

1111

any purpose.

1112

1113

<h4 class="subsection">3.4.37 style style2</h4>

1114

1115

<h4 class="subsection">3.4.38 style style3</h4>

1116

1117

<h4 class="subsection">3.4.39 style style4</h4>

1118

1119

<h4 class="subsection">3.4.40 style style5</h4>

1120

1121

<h4 class="subsection">3.4.41 style subsection</h4>

1122

1123

This style is used for subsections with a subsection number.

1124

1125

1126

1127

<dl><dt><code>firstLineIndent 4</code><dd>

1128

1129

</dl>

1130

1131

<h4 class="subsection">3.4.42 style table</h4>

1132

1133

This style is used for ordinary tables.

1134

1135

<h4 class="subsection">3.4.43 style titlepage</h4>

1136

1137

This style is used to begin a title page.

1138

1139

1140

1141

<dl><dt><code>newPageAfter yes</code><dd>

1142

1143

</dl>

1144

1145

<h4 class="subsection">3.4.44 style trnote</h4>

1146

1147

This style is used for transcriber's notes which are set off from the

1148

text.

1149

1150

<h4 class="subsection">3.4.45 style volume</h4>

1151

1152

This style is used to indicate the beginning of a braille volume.

1153

1154

1155

1156

<h2 class="chapter">4 Connecting with the xml Document - Semantic-Action Files</h2>

1157

1158

1159

1160

<h3 class="section">4.1 Overview</h3>

1161

1162

When liblouisxml (or <samp>xml2brl</samp>) processes an xml document, it

1163

needs to be told how to use the information in that document to

1164

produce a properly translated and formatted braille document. These

1165

instructions are provided by a semantic-action file, so called because

1166

it explains the meaning, or semantics, of the various specifications

1167

in the xml document. To understand how this works, it is necessary to

1168

have a basic knowledge of the organization of an xml document.

1169

1170

An xml document is organized like a book, but with much finer detail.

1171

First there is the title of the whole book. Then there are various

1172

sections, such as author, copyright, table of contents, dedication,

1173

acknowledgments, preface, various chapters, bibliography, index, and

1174

so on. Each chapter may be divided into sections, and these in turn

1175

can be divided into subsections, subsubsections, etc. In a book the

1176

parts have names or titles distinguished by capitalization, type

1177

fonts, spacing, and so forth. In an xml document the names of the

1178

parts are enclosed in angle brackets (`<samp><></samp>'). For example, if

1179

liblouisxml encounters <code><html></code> at the beginning of a document,

1180

it knows it is dealing with a document that conforms to the standards

1181

of the extensible markup language (xhtml) - at least we hope it does.

1182

When you see a book, you know it's a book. The computer can know only

1183

by being told. Something enclosed in angle brackets is called an

1184

"element" (more properly, a "tag") in xml parlance. (There may be more

1185

between the angle brackets than just the name of the element. More of

1186

this later). The first "element" in a document thus tells liblouisxml

1187

what kind of document it is dealing with. This element is called the

1188

"root element" because the document is visualized as branching out

1189

from it like a tree. Some examples of root elements are <code><html></code>,

1190

<code><math></code>, <code><book></code>, <code><dtbook3></code> and

1191

<code><wordDocument></code>. Whenever liblouisxml encounters a root element

1192

that it doesn't know about it creates a new file called a

1193

semantic-action file. The name of this file is formed by stripping the

1194

angle brackets from the root element and adding a period plus the

1195

letters `<samp>sem</samp>'. If you look in a directory containing

1196

semantic-action files you will see names like <samp>html.sem</samp>,

1197

<samp>dtbook3.sem</samp>, <samp>math.sem</samp>, and so on.

1198

1199

Sometimes it is advantageous to preempt the creation of a

1200

semantic-action file for a new root element. For example, an article

1201

written according to the docbook specification may have the root

1202

element <code><article></code>. However, the specification itself has the

1203

root element <code><book></code>. In this case you can specify the

1204

<samp>book.sem</samp> file in the configuration file by writing, in the xml

1205

section,:

1206

1207

<pre class="example"> semanticFiles book.sem

1208

</pre>

1209

You will note that this setting uses the plural of "file". This is

1210

because you can actually specify a list of file names separated by

1211

commas. You might want to do this to specify the semantic-action file

1212

for the particular braille mathematical code to be used. For example:

1213

1214

<pre class="example"> semanticFiles book.sem,ukmaths.sem

1215

</pre>

1216

As you will see in the next section, different braille style

1217

conventions and different braille mathematical codes may require

1218

different semantic-action files

1219

1220

liblouisxml records the names of all elements found in the document in

1221

the semantic-action file. The document has a multitude of elements,

1222

which can be thought of as describing the headings of various parts of

1223

the document. One element is used to denote a chapter heading. Another

1224

is used to denote a paragraph, Still another to denote text in bold

1225

type, and so on. In other words, the elements take the place of the

1226

capitalization, changes in type font, spacing, etc. in a book.

1227

However, the computer still does not know what to do when it

1228

encounters an element. The semantic-action file tells it that.

1229

1230

Consider <samp>html.sem</samp>. A copy is included as part of this

1231

documentation with the name <samp>example_html.sem</samp>. It may differ from

1232

the

1233

file that liblouisxml is currently using. You will see that it begins

1234

with some lines about copyrights. Each line begins with a number sign

1235

(`<samp>#</samp>'). This indicates that it is a "comment", intended for the

1236

human reader and the computer should ignore it. Then there is a blank

1237

line. Finally, there are two other comments explaining that the file

1238

must be edited to get proper output. This is because a human being

1239

must tell the computer what to do with each element. The semantic

1240

files for common types of documents have already been edited, so you

1241

generally don't have to worry about this. But if you encounter a new

1242

type of document or wish to specify special handling for styles or

1243

mathematics you may have to edit the semantic-action file or send it

1244

to the maintainer for editing. In any case the rest of this section is

1245

essential for understanding how liblouisxml handles documents and for

1246

making changes if the way it does so is not correct.

1247

1248

After another blank line you will see a table consisting of two, and

1249

sometimes three, columns. The first column contains a word which tells

1250

the computer to do something. For example, the first entry in the

1251

table is: `<samp>include nemeth.sem</samp>'. This tells liblouisxml to include

1252

the information in the <samp>nemeth.sem</samp> file when it is deciphering

1253

an html (actually xhtml) document (it may be preferable to use the

1254

semanticFiles setting in the configuration file rather than an

1255

include).

1256

1257

The second row of the table is:

1258

1259

<pre class="example"> no hr

1260

</pre>

1261

`<samp>hr</samp>' is an element with the angle brackets removed. It means

1262

nothing in itself. However, the first column contains the word

1263

`<samp>no</samp>'. This tells liblouisxml "no do", that is, do nothing.

1264

1265

After a few more lines with `<samp>no</samp>' in the first column, we see one

1266

that says:

1267

1268

<pre class="example"> softreturn br

1269

</pre>

1270

This means that when the element <code> </code> is encountered,

1271

liblouisxml is to do a soft return, that is, start a new line without

1272

starting a new paragraph.

1273

1274

The next line says:

1275

1276

<pre class="example"> heading1 h1

1277

</pre>

1278

This tells liblouisxml that when it encounters the element <code><h1></code>

1279

it is to format the text which follows as a first-level braille

1280

heading, that is, the text will be centered and proceeded and followed

1281

by blank lines. (You can change this by changing the definition of the

1282

heading1 style).

1283

1284

The next line says:

1285

1286

<pre class="example"> italicx em

1287

</pre>

1288

This tells liblouisxml that when it encounters the element <code></code>

1289

it is to enclose the text which follows in braille italic indicators.

1290

The `<samp>x</samp>' at the end of the semantic action name is there to

1291

prevent conflicts with names elsewhere in the software. Just where the

1292

italic indicators will be placed is controlled by the liblouis

1293

translation table in use.

1294

1295

The next line says:

1296

1297

<pre class="example"> skip style

1298

</pre>

1299

This tells liblouis to simply skip ahead until it encounters the

1300

element <code></style></code>. Nothing in between will have any effect on

1301

the braille output. Note the slash (`<samp>/</samp>') before the `<samp>style</samp>'.

1302

This means the end of whatever the <code><style></code> element was

1303

referring to. Actually, it was referring to specifications of how

1304

things should be printed. If liblouisxml had not been told to skip

1305

these specifications, the braille output would have contained a lot of

1306

gobledygook.

1307

1308

The next line says:

1309

1310

<pre class="example"> italicx strong

1311

</pre>

1312

This tells liblouis to also use the italic braille indicators for the

1313

text between the <code></code> and <code></code> elements.

1314

1315

After a few more lines with `<samp>no</samp>' in the first column we come to

1316

the line:

1317

1318

<pre class="example"> document html

1319

</pre>

1320

This tells liblouisxml that everything between <code><html></code> and

1321

<code></html></code> is an entire document. <code><html></code> was the root

1322

element of this document, so this is logical.

1323

1324

After another `<samp>no</samp>' line we come to:

1325

1326

<pre class="example"> para p

1327

</pre>

1328

liblouisxml will consider everything between <code></code> and

1329

<code></code> to be a normal body text paragraph.

1330

1331

The next line is:

1332

1333

<pre class="example"> heading1 title

1334

</pre>

1335

this causes the title of the document to also be treated as a braille

1336

level 1 heading.

1337

1338

Next we have the line:

1339

1340

<pre class="example"> list li

1341

</pre>

1342

The xhtml <code><li></code> and <code></li></code> pair of elements is used to

1343

enclose an item in a list. liblouisxml will format this with its own

1344

list style. That is, the first line will begin at the left margin and

1345

subsequent lines will be indented two cells.

1346

1347

Next we have:

1348

1349

<pre class="example"> table table

1350

</pre>

1351

You will note that the names of actions and elements are often

1352

identical. This is because they are both mnemonic. In any case, this

1353

line tells liblouisxml to format the table contained in the xhtml

1354

document according to the table formatting rules it has been given for

1355

braille output.

1356

1357

Next we have the line:

1358

1359

<pre class="example"> heading2 h2

1360

</pre>

1361

This means that the text between <code><h2></code> and <code></h2></code> is to be

1362

formatted according to the Liblouisxml style heading2. A blank line

1363

will be left before the heading and the first line will be indented

1364

four spaces.

1365

1366

After a few more lines we come to:

1367

1368

<pre class="example"> no table,cellpadding

1369

</pre>

1370

Note the comma in the second column. This divides the column into two

1371

subcolumns. The first is the table element name. The second is called

1372

an "attribute" in xml. It gives further instructions about the

1373

material enclosed between the starting and ending "tags" of the

1374

element (<code><table></code> and <code></table></code>. Full information requires

1375

three subcolumns. The third is called the value and gives the actual

1376

information. The attribute is merely the name of the information.

1377

1378

Much further down we find:

1379

1380

<pre class="example"> no table,border,0

1381

</pre>

1382

Here the element is table, the attribute is border and the value is 0.

1383

If liblouisxml were to interpret this, it would mean that the table

1384

was to have a border of 0 width. It is not told to do so because

1385

tables in braille do not have borders.

1386

1387

Now let's look at the file which is included at the beginning of the

1388

<samp>html.sem</samp> file. This is <samp>nemeth.sem</samp>. As with

1389

<samp>html.sem</samp>, a copy is included in the documentation directory

1390

with the name <samp>example_nemeth.sem</samp> , but it is not necessarily

1391

the one that liblouisxml is currently using. It illustrates several

1392

more things about how liblouisxml uses semantic-action files.

1393

1394

The first thing you will notice is that for quite a few lines the

1395

first and second columns are identical. This is because the MathML

1396

element and attribute names are part of a standard, and it was

1397

simplest to use the element names for the semantic actions as well.

1398

1399

The first line of real interest is:

1400

1401

<pre class="example"> math math

1402

</pre>

1403

Every mathematical expression begins with the element <code><math></code>

1404

(which may have attributes and values), and ends with <code></math></code>.

1405

This is therefore the root element of a mathematical expression.

1406

However, mathematical expressions are usually part of a document, so

1407

it is not given the semantic action document. The math semantic action

1408

causes liblouisxml to carry out special interpretation actions. These

1409

will become clearer as we continue to look at the <samp>nemeth.sem</samp>

1410

file. You will note that this line has three columns. The meaning of

1411

the third column is discussed below.

1412

1413

After another uninteresting line we come to two that illustrate

1414

several more facts about semantic-action files:

1415

1416

<pre class="example"> mfrac mfrac ^?,/,^#

1417

mfrac mfrac,linethickness,0 ^(,^;%,^)

1418

</pre>

1419

Like the math entry above, the first line has three columns. While the

1420

first two columns must always be present, the third column is

1421

optional. Here, it is also divided into subcolumns by commas. The

1422

element <code><mfrac></code> indicates a fraction. A fraction has two parts,

1423

a numerator and a denominator. In xml, we call these parts children of

1424

<code><mfrac></code>. They may be represented in various ways, which need

1425

not concern us here. What is of real importance is that the third

1426

column tells liblouisxml to put the characters `<samp>~?</samp>' before the

1427

numerator, `<samp>/</samp>' between the numerator and denominator, and

1428

`<samp>~#</samp>' after the denominator. Later on, liblouis will translate

1429

these characters into the proper representation of a fraction in the

1430

Nemeth Code of Braille Mathematics. (For other mathematical codes,

1431

see <a href="#Implementing-Braille-Mathematics-Codes">Implementing Braille Mathematics Codes</a>).

1432

1433

The second line is of even greater interest. The first column is again

1434

`<samp>mfrac</samp>', but this line is for binomial coefficient. The second

1435

column contains three subcolumns, an element name, an attribute name

1436

and an attribute value. The attribute linethickness specifies the

1437

thickness of the line separating the numerator and denominator. Here

1438

it is 0, so there is no line. This is how the binomial coefficient is

1439

represented in print. The third column tells how to represent it in

1440

braille. liblouisxml will supply `<samp>~(</samp>', upper number, `<samp>~%</samp>',

1441

lower number, `<samp>~)</samp>' to liblouis, which will then produce the

1442

proper braille representation for the binomial coefficient.

1443

1444

Returning to the line for the math element, we see that the third

1445

column begins with a backslash followed by an asterisk. The backslash

1446

is an escape character which gives a special meaning to the character

1447

which follows it. Here the asterisk means that what follows is to be

1448

placed at the very end of the mathematical expression, no matter how

1449

complex it is.

1450

1451

For further discussion of how the third column is used

1452

see <a href="#Implementing-Braille-Mathematics-Codes">Implementing Braille Mathematics Codes</a>. The third column is

1453

not limited to mathematics. It can be used to add characters to

1454

anything enclosed by an xml tag.

1455

1456

1457

1458

<h3 class="section">4.2 Semantic Actions in detail</h3>

1459

1460

Here is a complete list of the semantic actions which liblouisxml

1461

recognizes. Many of them are also the names of styles. These are

1462

listed first, preceded by an asterisk. For a discussion of these,

1463

see <a href="#Customization-Configuring-liblouisxml">Customization Configuring liblouisxml</a>.

1464

1465

Generally the format of a semantic action is:

1466

1467

<pre class="example"> semanticAction elementSpecifier optionalArguments

1468

</pre>

1469

<code>elementSpecifier</code> is the second-column value, which may be an

1470

element name, an element-attribute pair or an element-attribute-value

1471

triplet, separated by commas. This specifies where a semantic action

1472

is to be applied. If it is solely an element then the action is

1473

applied if this element is encountered. If it is an element-attribute

1474

pair then the action is applied if the given element also has the

1475

specified attribute. In the last case with a element-attribute-value

1476

triplet the action is only applied if the element has the specified

1477

attribute and the value of this attribute is equal to the specified

1478

value.

1479

1480

In the following table the styles are merely listed (preceded by an

1481

asterisk), since they have been described in style subsections above.

1482

1483

<dl>

1484

<dt><code>* arith</code> <dt><code>* attribution</code> <dt><code>* biblio</code> <dt><code>* blanklinebefore</code> <dt><code>* caption</code> <dt><code>* code</code> <dt><code>* contents</code> <dt><code>contents1</code> <dt><code>contents2</code> <dt><code>contenss3</code> <dt><code>contents4</code> <dt><code>contentsHeader</code> <dt><code>* dedication</code> <dt><code>* directions</code> <dt><code>* dispmath</code> <dt><code>* disptext</code><dd>

1485

1486

<dt><code>document elementSpecifier</code><dd>

1487

Everything between <code><elementSpecifier></code> and

1488

<code></elementSpecifier></code> is an entire document.

1489

1490

<dt><code>* exercise1</code> <dt><code>* exercise2</code> <dt><code>* exercise3</code> <dt><code>* glossary</code> <dt><code>* graph</code> <dt><code>* graphlabel</code><dd><a name="index-heading1-104"></a><a name="heading1-semantic"></a>

1491

<dt><code>heading1 elementSpecifier</code><dd>

1492

Format the enclosed text as a first-level braille heading, that is,

1493

the text will be centered and proceeded and followed by blank lines.

1494

(You can change this by changing the definition of the heading1

1495

style).

1496

1497

1498

<dt><code>heading2 elementSpecifier</code><dd>

1499

Format the enclosed text as a second-level braille heading. (You can

1500

change this by changing the definition of the heading2 style).

1501

1502

1503

<dt><code>heading3 elementSpecifier</code><dd>

1504

Format the enclosed text as a third-level braille heading. (You can

1505

change this by changing the definition of the heading3 style).

1506

1507

1508

<dt><code>heading4 elementSpecifier</code><dd>

1509

Format the enclosed text as a fourth-level braille heading. (You can

1510

change this by changing the definition of the heading4 style).

1511

1512

<dt><code>* indexx</code><dd><a name="index-list-108"></a><a name="list-semantic"></a>

1513

<dt><code>list elementSpecifier</code><dd>

1514

Format the content of <code>elementSpecifier</code> with list style. That is, the

1515

first line will begin at the left margin and subsequent lines will be

1516

indented two cells.

1517

1518

<dt><code>* matrix</code> <dt><code>* music</code> <dt><code>* note</code><dd>

1519

1520

<dt><code>para elementSpecifier</code><dd>

1521

Everything between <code><elementSpecifier></code> and

1522

<code></elementSpecifier></code> is to be formatted as a normal body text

1523

paragraph.

1524

1525

<dt><code>* quotation</code> <dt><code>* section</code> <dt><code>* spatial</code> <dt><code>* stanza</code> <dt><code>* style1</code> <dt><code>* style2</code> <dt><code>* style3</code> <dt><code>* style4</code> <dt><code>* style5</code> <dt><code>* subsection</code><dd><a name="index-table-110"></a><a name="table-semantic"></a>

1526

<dt><code>table elementSpecifier</code><dd>

1527

Format the table contained in the element <code><elementSpecifier></code> according to

1528

the table formatting rules it has been given for braille output.

1529

1530

<dt><code>* titlepage</code> <dt><code>* trnote</code> <dt><code>* volume</code> <dt><code>acknowledge</code> <dt><code>author</code> <dt><code>blankline</code> <dt><code>bodymatter</code> <dt><code>boldx</code> <dt><code>booktitle</code> <dt><code>boxline</code> <dt><code>cdata</code> <dt><code>center</code> <dt><code>chemistry</code> <dt><code>changetable</code> <dt><code>compbrl</code><dd><a name="index-configfile-111"></a><a name="configfile-semantic"></a>

1531

<dt><code>configfile elementSpecifier filename</code><dd>

1532

1533

The <code>configfile</code>, <code>configstring</code> and <code>configtweak</code>

1534

semantic actions enable the configuration of liblouisxml to be changed

1535

according to the contents of the document being transcribed.

1536

<code>configfile</code> and <code>configstring</code> take effect during the

1537

document analysis phase performed by <samp>examine_document.c</samp>.

1538

<code>configtweak</code> is effective during the transcription phase,

1539

performed by <samp>transcribe_document.c</samp> and the functions called in

1540

this module.

1541

1542

<code>elementSpecifier</code> is the usual second-column value, which may be

1543

an element name, an element-attribute pair or an

1544

element-attribute-value triplet, separated by commas. <code>filename</code>

1545

must be on one of the paths set in the <samp>paths.c</samp> module. The file

1546

may contain any configuration settings except those in the xml

1547

section. These would be ineffective, since the document has already

1548

been parsed.

1549

1550

1551

<dt><code>configstring elementSpecifier setting1=value1;setting2=value2;...</code><dd>

1552

1553

Note that the <code>setting=value</code> pairs are separated by semicolons.

1554

Because the string may be longer than a screen line, you can use a

1555

backslash `<samp>\</samp>' followed immediately by a line ending `<samp>\n</samp>', to

1556

continue to another line. The string must not contain any blanks. Any

1557

setting which can be specified in a file read with configfile can be

1558

specified in <code>configstring</code>.

1559

1560

1561

<dt><code>configtweak elementSpecifier</code><dd>

1562

1563

<code>configtweak</code> is identical to <code>configstring</code> except that it

1564

is called in the transcription phase. It should be used only for

1565

things like changing translation tables. For example:

1566

1567

<pre class="example"> configtweak elementSpecifier literaryTextTable=fooTable;\

1568

mathExprTable=barTable

1569

</pre>

1570

<code>configtweak</code> is not a generalization of <code>changetable</code>. The

1571

latter changes only the literarytexttable and applies to a subtree.

1572

<code>configtweak</code> remains in effect until changed by another

1573

<code>configtweak</code>.

1574

1575

1576

<dt><code>contentsheader elementSpecifier</code><dd>

1577

1578

Replace the given element with a table of contents (see <a href="#Table-of-contents">Table of contents</a>). Typically the <code>elementSpecifier</code> would occur at the

1579

end of the information which you want to be at the head of the output,

1580

such as a title page, dedication, etc.

1581

1582

<dt><code>contracted</code> <dt><code>copyright</code> <dt><code>endnotes</code> <dt><code>footer</code> <dt><code>frontmatter</code> <dt><code>generic</code> <dt><code>graphic</code> <dt><code>htmllink</code> <dt><code>htmltarget</code><dd>

1583

1584

<dt><code>italicx elementSpecifier</code><dd>

1585

Enclose the text which follows in braille italic indicators.

1586

The `<samp>x</samp>' at the end of the semantic action name is there to

1587

prevent conflicts with names elsewhere in the software. Just where the

1588

italic indicators will be placed is controlled by the liblouis

1589

translation table in use.

1590

1591

<dt><code>jacket</code> <dt><code>line</code> <dt><code>maction</code> <dt><code>maligngroup</code> <dt><code>malignmark</code><dd><a name="index-math-116"></a><a name="math-semantic"></a>

1592

<dt><code>math elementSpecifier</code><dd>

1593

Every mathematical expression begins with the element <code><elementSpecifier></code>

1594

(which may have attributes and values), and ends with

1595

<code></elementSpecifier></code>. This is therefore the root element of a mathematical

1596

expression. However, mathematical expressions are usually part of a

1597

document, so it is not given the semantic action document. The

1598

<code>math</code> semantic action causes liblouisxml to carry out special

1599

interpretation actions.

1600

1601

<dt><code>menclose</code> <dt><code>merror</code> <dt><code>mfenced</code> <dt><code>mfrac</code> <dt><code>mglyph</code> <dt><code>mi</code> <dt><code>mlabeledtr</code> <dt><code>mmultiscripts</code> <dt><code>mn</code> <dt><code>mo</code> <dt><code>mover</code> <dt><code>mpadded</code> <dt><code>mphantom</code> <dt><code>mprescripts</code> <dt><code>mroot</code> <dt><code>mrow</code> <dt><code>ms</code> <dt><code>mspace</code> <dt><code>msqrt</code> <dt><code>mstyle</code> <dt><code>msub</code> <dt><code>msubsup</code> <dt><code>msup</code> <dt><code>mtable</code> <dt><code>mtd</code> <dt><code>mtext</code> <dt><code>mtr</code> <dt><code>munder</code> <dt><code>munderover</code> <dt><code>newpage</code> <dt><code>no</code> <dt><code>none</code><dd>

1602

1603

<dt><code>notranslate elementSpecifier</code><dd>

1604

Output the text between the start and end tags exactly as written. It

1605

will, however, be formatted with appropriate line breaks, page numbers

1606

etc. If you want to make sure that things appear on the same line

1607

separate them with an unbreakable space, `<samp>&#160;</samp>' or

1608

`<samp>&#xa0;</samp>'.

1609

1610

<dt><code>pagenum</code> <dt><code>preface</code> <dt><code>rearmatter</code> <dt><code>reverse</code> <dt><code>righthandpage</code> <dt><code>runninghead</code> <dt><code>semantics</code><dd>

1611

1612

<dt><code>skip elementSpecifier</code><dd>

1613

Skip ahead until it encounters the element <code></elementSpecifier></code>.

1614

Nothing

1615

in between will have any effect on the braille output.

1616

1617

1618

<dt><code>softreturn elementSpecifier</code><dd>

1619

Do a soft return, that is, start a new line without starting a new

1620

paragraph.

1621

1622

<dt><code>tblbody</code> <dt><code>tblcol</code> <dt><code>tblhead</code> <dt><code>tblrow</code> <dt><code>tnpage</code> <dt><code>transcriber</code> <dt><code>uncontracted</code><dd>

1623

</dl>

1624

1625

1626

1627

<h2 class="chapter">5 Special Features</h2>

1628

1629

1630

1631

<h3 class="section">5.1 Table of contents</h3>

1632

1633

A table of contents is produced for an xml file if the file contains a

1634

tag which has been defined with the <code>contentsheader</code> semantic action (see <a href="#contentsheader-semantic">contentsheader</a>) and

1635

also tags for the <code>heading1</code>, <code>heading2</code>, <code>heading3</code> or

1636

<code>heading4</code> semantic actions (see <a href="#heading1-semantic">heading1</a>). The table of contents will

1637

contain print and braille page numbers if these features have been

1638

enabled. A sequence of fill characters will be inserted before the

1639

page numbers, so that the latter are at the right margin. The fill

1640

character can be specified in a configuration file with the

1641

<code>lineFill</code> setting (see <a href="#lineFill-setting">lineFill</a>). The default fill character is an apostrophe

1642

(dot 3).

1643

1644

Five new styles have been defined for the table of contents. The first

1645

is the <code>contentsheader</code> style (see <a href="#contentsheader-style">contentsheader style</a>),

1646

which is used to specify how the contents should be placed and the

1647

title that should be given to it. The others correspond to the four

1648

heading levels and are <code>contents1</code>, <code>contents2</code>,

1649

<code>contents3</code> and <code>contents4</code>. These styles are chosen as

1650

appropriate while the table of contents is being made. Do not declare

1651

them in a semantic-action file. See the <samp>canonical.cfg</samp> file for

1652

the current default definitions of all these styles.

1653

1654

The table of contents will be placed where the xml tag is that you

1655

declared in the <code>contentsheader</code> semantic action (see <a href="#contentsheader-semantic">contentsheader</a>). It begins on a new page.

1656

After it is completed the braille page number is reset to

1657

<code>beginningBraillePageNumber</code> and another new page is started.

1658

This means that the xml tag with the <code>contentsheader</code> semantic

1659

action should occur at the end of the information which you want to be

1660

at the head of the output, such as a title page, dedication, etc.

1661

1662

It is not necessary that an xml file contain a tag with the

1663

<code>contentsheader</code> semantic action. If the file contains headers

1664

you can obtain a table of contents by specifying <code>contents yes</code>

1665

in a configuration file or <samp>-Ccontents=yes</samp> on the command line

1666

of <samp>xml2brl</samp>. In this case, the table of contents will appear

1667

at the beginning of the output. Pages will be numbered beginning with

1668

1. When the table of contents is complete, the material in the file

1669

will start on a new page and the page number will be the value given

1670

in <code>beginningBraillePageNumber</code>.

1671

1672

The <code>contents1</code>, etc. styles all have the <code>format contents</code>

1673

setting. This is a variant of the <code>leftJustified</code> format. It has

1674

been necessary to change the way <code>firstLineIndent</code> is handled to

1675

accommodate multilevel lists. Up till now, if <code>firstLineIndent</code>

1676

was negative, the first line would start at the real left margin,

1677

regardless of the value of <code>leftMargin</code>. Now the value of

1678

<code>firstLineIndent</code> is simply added to <code>leftMargin</code>. This

1679

means that if it is negative it is really subtracted. For example, if

1680

<code>leftMargin</code> is 4 and <code>firstLineIndent</code> is -2 the first line

1681

will start in cell 2.

1682

1683

1684

1685

<h2 class="chapter">6 Implementing Braille Mathematics Codes</h2>

1686

1687

The Nemeth Code of Braille Mathematical and Science Notation has been

1688

implemented. Other braille mathematics codes can be implemented by

1689

following the same pattern. The Nemeth Code implementation is

1690

discussed as an example below.

1691

1692

Four tables are used to translate xml documents containing a mixture

1693

of text and mathematics into the Nemeth code. They can be found in the

1694

subdirectory <samp>lbx_files</samp> of the liblouisxml directory. First, the

1695

semantic-action file <samp>nemeth.sem</samp> is used to interpret the

1696

mathematical portions of the xml document (The text portions are

1697

interpreted by another semantic-action file which will not be

1698

discussed here). After the math and text have been interpreted, two

1699

liblouis tables, <samp>nemeth.ctb</samp> and <samp>en-mathtext.ctb</samp> are used

1700

to translate them. Each piece of mathematics or text is translated

1701

separately and the pieces are strung together with blanks between

1702

them. This results in inaccuracies where mathematics meets text. The

1703

fourth table, also a liblouis table, is used to remove these

1704

inaccuracies. It is called <samp>edittable.ctb</samp>, and it does things

1705

like removing the multi-purpose indicator before a blank, inserting

1706

the punctuation indicator before a punctuation mark following a math

1707

expression, and removing extra spaces.

1708

1709

The general format and use of semantic-action files were discussed in

1710

the previous section, (see <a href="#Connecting-with-the-xml-Document">Connecting with the xml Document - Semantic-Action Files</a>). In this section we

1711

shall concentrate on the optional third column, which is used a lot in

1712

<samp>nemeth.sem</samp>. While the first two columns can be generated by

1713

liblouisxml but must be edited by a person, the third column must

1714

always be provided by a human.

1715

1716

As previously stated, the third column tells liblouisxml what

1717

characters to insert to inform liblouis how to translate the math

1718

expression. Look at the following line:

1719

1720

<pre class="example"> mfrac mfrac ^?,/,^#

1721

</pre>

1722

You will see that the third column contains two commas. This means

1723

that it has three subcolumns. A fraction has a numerator and a

1724

denominator. These are called children of the <code>mfrac</code> element.

1725

The first subcolumn specifies the characters that liblouisxml should

1726

place in front of the numerator. The second subcolumn gives the

1727

characters to be placed between the numerator and denominator.

1728

Finally, the third subcolumn gives the characters to place after the

1729

denominator. You will see that the first subcolumn contains a caret

1730

followed by a question mark. The dot pattern for the question mark in

1731

computer braille is the same as for the Nemeth start-fraction

1732

indicator. The caret is used so that liblouis can tell this apart from

1733

a question mark, which also has the same dot pattern in computer

1734

braille. The second subcolumn contains a slash but no caret. This is

1735

because there is no danger of confusion where the slash is concerned.

1736

The third subcolumn does contain a caret, and it also contains a

1737

number sign, which corresponds to the Nemeth end-fraction indicator.

1738

When liblouisxml encounters the MathML representation of the fraction

1739

one-half it produces the following string of characters:

1740

`<samp>^?1/2^#</samp>'. liblouis then removes the carets to get `<samp>?1/2#</samp>'.

1741

1742

As another example, consider the entry in <samp>nemeth.sem</samp> for a

1743

subscript.

1744

1745

<pre class="example"> msub msub ,^;,^"

1746

</pre>

1747

Here the first subcolumn is blank, because nothing is to be placed

1748

before the subscripted symbol. The second subcolumn contains a caret

1749

and a semicolon (in computer braille). This corresponds to the Nemeth

1750

subscript indicator. The third column contains a caret and a quotation

1751

mark, corresponding to the Nemeth baseline indicator. liblouisxml

1752

translates the MathML expression for x superscript i into

1753

`<samp>x^;i^</samp>'. liblouis subsequently produces `<samp>x;i</samp>'. There are

1754

other steps if the subscript is numeric. These are handled by pass2

1755

opcodes in the liblouis translation table, <samp>nemeth.ctb</samp>.

1756

1757

You will notice that the entries in <samp>nemeth.sem</samp> have various

1758

numbers of subcolumns in the third column. In general, the characters

1759

given in the first subcolumn are placed before the first child of the

1760

element given in the second column. The characters in the second

1761

subcolumn are placed before the second child, and so on, until the

1762

characters given in the last subcolumn are placed after the last

1763

child.

1764

1765

Sometimes an element or tag can have an indeterminate number of

1766

children. This is true of <code><math></code> itself. Yet, it may be

1767

necessary to place some characters after the very last element. Let us

1768

look at the <code><math></code> entry.

1769

1770

<pre class="example"> math math \eb,\*\ee

1771

</pre>

1772

First let us discuss escape sequences starting with a backslash. These

1773

are basically the same as in liblouis. The sequence `<samp>\e</samp>' is

1774

shorthand for the escape character, which would otherwise be

1775

represented by `<samp>\x001b</samp>'. The beginning of a math expression is

1776

denoted by an escape character followed by the letter b and the end by

1777

an escape character followed by the letter `<samp>e</samp>'. This enables the

1778

editing table to do such things as drop the baseline indicator at the

1779

end of a math expression and insert a number sign at the beginning, if

1780

needed.

1781

1782

Not found in liblouis is the sequence `<samp>\*</samp>'. This means to put

1783

what follows after the very last child of the math element, no matter

1784

how many there are.

1785

1786

As another example consider:

1787

1788

<pre class="example"> mtd mtd \*\ec

1789

</pre>

1790

<code>mtd</code> is the MathML tag for a table column. There may be many

1791

children of this tag. The entry says to put an escape character (hex

1792

1b), plus the letter `<samp>c</samp>', after the very last of them.

1793

1794

As a final example consider:

1795

1796

<pre class="example"> mtr mtr ^.^\,^(,\*^.^\,^)\er

1797

</pre>

1798

<code>mtr</code> is the MathML tag for a row in a table, in this case a

1799

matrix. Each row in a matrix must begin with the dot pattern

1800

`<samp>46-6-12356</samp>' and end with the dot pattern `<samp>46-6-12456</samp>'. As

1801

usual a caret is placed before the corresponding characters. Since dot

1802

6 is a comma, it must be escaped. This is done by placing a backslash

1803

before the comma. There are two subcolumns. the first contains the

1804

characters to be placed at the beginning of each row. The second

1805

starts with `<samp>\*</samp>', signifying that the characters following it

1806

are to be placed at the end of everything in this row. A subcolumn

1807

starting with `<samp>\*</samp>' must be the last (or only) subcolumn.

1808

1809

Here this last subcolumn ends with an escape character and the letter

1810

<r>, signifying the end of a row.

1811

1812

So much for the semantic action file. Even though the characters in

1813

the third column were chosen to correspond with nemeth characters,

1814

they may not have to be changed for other math codes. liblouis can

1815

replace them with anything needed.

1816

1817

This brings us to a consideration of the two tables used by liblouis

1818

to translate mathematics texts. The first, <samp>en-mathtext.ctb</samp> is

1819

used to translate text appearing outside math expressions. It is

1820

necessary because the Nemeth code requires modifications of Grade 2

1821

braille. Other math codes may not have this requirement.

1822

1823

The table actually used to translate mathematics is <samp>nemeth.ctb</samp>.

1824

It includes two other tables, <samp>chardfs.cti</samp> and

1825

<samp>nemethdefs.cti</samp>. The first gives ordinary character definitions

1826

and is included by all the other tables. Note however, that the

1827

unbreakable space, `<samp>\x00a0</samp>', is translated by dot 9. This is used

1828

before and after the equal sign and other symbols in

1829

<samp>nemeth.ctb</samp>. The second table contains character definitions for

1830

special math symbols, most of which are Unicode characters greater

1831

than `<samp>\x00ff</samp>'. The Greek letters are here. So are symbols like

1832

the integral sign.

1833

1834

Most of the entries in <samp>nemeth.ctb</samp> should be familiar from other

1835

tables. The unfamiliar ones follow the comments `<samp># Semantic

1836

pairs</samp>' and `<samp># pass2 corrections</samp>'. The first simply replace

1837

characters preceded by a caret with the character itself. The second

1838

make adjustments in the code generated directly from the

1839

<samp>nemeth.sem</samp> file. The pass2 opcode is discussed in the liblouis

1840

documentation (see <a href="liblouis.html#Top">Overview</a>). Here are some comments on a few of the entries in

1841

<samp>nemeth.ctb</samp>.

1842

1843

<pre class="example"> pass2 @1456-1456 @6-1456

1844

</pre>

1845

Replaces double start-fraction indicators with the start complex

1846

fraction indicator.

1847

1848

<pre class="example"> pass2 @3456-3456 @6-3456

1849

</pre>

1850

Replaces double end-fraction indicators with the end-complex-fraction

1851

indicator.

1852

1853

<pre class="example"> pass2 @56[$d1-5]@5 *

1854

</pre>

1855

Removes the subscript and baseline indicators from numeric subscripts.

1856

1857

<pre class="example"> pass2 @5-9 @9

1858

</pre>

1859

Removes the baseline or multipurpose indicator before an unbreakable

1860

space generated by the translation of an equal sign, etc.

1861

1862

<pre class="example"> pass2 @45-3-5 @3

1863

</pre>

1864

Replaces a superscript apostrophe with a simple prime symbol.

1865

1866

<pre class="example"> pass2 @9[]$d @3456

1867

</pre>

1868

Puts a number sign before a digit preceded by a blank.

1869

1870

<pre class="example"> pass2 @9-0 @9

1871

</pre>

1872

Removes a space following an unbreakable space.

1873

1874

We now come to the fourth and last table used for math translation,

1875

the editing table, <samp>edittable.ctb</samp>. As explained at the

1876

beginning, this table is used to remove inaccuracies where math

1877

translation butts up against text translation. For example, the Nemeth

1878

code puts numbers in the lower part of the cell. However, punctuation

1879

marks are also in the lower part of the cell. So Nemeth puts a

1880

punctuation indicator, dots `<samp>456</samp>', in front of any lower-cell

1881

punctuation that immediately follows a mathematical expression. If

1882

this occurs inside Mathml it is handled by <samp>nemeth.ctb</samp>. However,

1883

a MathML expression is often followed by a punctuation mark which is

1884

the first part of text. liblouisxml puts a blank between math and

1885

text, but this can result in a mathematical expression followed by a

1886

blank and then, say, a period, dots `<samp>256</samp>'. <samp>edittable.ctb</samp>

1887

replaces the blank with the punctuation indicator.

1888

1889

When you look at <samp>edittable.ctb</samp> you will see that it begins with

1890

an include of <samp>chardefs.cti</samp>. Most of the entries are ordinary,

1891

but some are interesting. for example,

1892

1893

<pre class="example"> always "\s 0

1894

</pre>

1895

replaces the baseline or multipurpose indicator followed by a space

1896

with just a space.

1897

1898

1899

1900

<h2 class="chapter">7 Programming with liblouisxml</h2>

1901

1902

1903

1904

<h3 class="section">7.1 License</h3>

1905

1906

Liblouisxml may contain code borrowed from the Linux screenreader

1907

1908

by the BRLTTY Team.

1909

1910

1911

<a href="www.viewplus.com">www.viewplus.com</a>.

1912

1913

1914

<a href="www.abilitiessoft.com">www.abilitiessoft.com</a>.

1915

1916

Liblouisxml is free software: you can redistribute it and/or modify it

1917

under the terms of the GNU Lesser General Public License as published

1918

by the Free Software Foundation, either version 3 of the License, or

1919

(at your option) any later version.

1920

1921

Liblouisxml is distributed in the hope that it will be useful, but

1922

WITHOUT ANY WARRANTY; without even the implied warranty of

1923

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

1924

Lesser General Public License for more details.

1925

1926

You should have received a copy of the GNU Lesser General Public

1927

License along with Liblouisxml. If not, see

1928

<a href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>.

1929

1930

1931

1932

<h3 class="section">7.2 Overview</h3>

1933

1934

liblouisxml is an "extensible renderer", designed to translate a wide

1935

variety of xml and text documents into braille, but with a special

1936

emphasis on

1937

technical material. The overall operation of liblouisxml is controlled

1938

by a configuration file. The way in which a particular type of xml

1939

document is to be rendered is specified by a semantic-action file for

1940

that document type. Braille translation is done by the liblouis

1941

braille translation and back-translation library (see <a href="liblouis.html#Top">Overview</a>).

1942

Its operation, in turn is controlled by translation table files. All

1943

these files are plain text and can be created and edited in any text

1944

editor. Configuration settings can also be specified on the command

1945

line of the console-mode transcription program <samp>xml2brl</samp>.

1946

1947

The general operation of liblouisxml is as follows. It uses the

1948

libxml2 library to construct a parse tree of the xml document. After

1949

the parse tree is constructed, a function called

1950

<code>examine_document</code> looks it over and determines whether math

1951

translation tables, etc. are needed. <code>examine_document</code> also

1952

constructs a prototype semantic-action file, if one does not exist

1953

already. When it is finished, another function, called

1954

<code>transcribe_document</code>, does the actual braille transcription. It

1955

calls <code>transcribe_math</code> to handle MathML subtrees,

1956

<code>transcribe_chemistry</code> for chemical formula subtrees,

1957

<code>transcribe_graphic</code> for SVG graphics, etc. Entities are

1958

translated to Unicode, if they are not already. Sequences of symbols

1959

indicate superscripts, return to the baseline, subscripts, start and

1960

end of fractions, etc. The Braille translator and back-translator

1961

library liblouis is used to do the braille translation.

1962

1963

The <code>transcribe_math</code> function works in conjunction with the

1964

latest version of liblouis and a special math translation table to

1965

transcribe most mathematical expressions into good Nemeth Code.

1966

Other Braille mathematics codes can be handled by modifying the

1967

translation table and semantic-action file.

1968

1969

The functions which are not needed at the moment, such as

1970

<code>transcribe_chemistry</code>, are only skeletons. However, I hope that

1971

<code>transcribe_graphics</code> can be expanded in the near future to use

1972

the graphics capability of the Tiger tactile graphics embossers.

1973

1974

The latest versions of liblouisxml and liblouis can be downloaded from

1975

<a href="www.abilitiessoft.com">www.abilitiessoft.com</a>. Note that liblouisxml will only work with

1976

the latest version of liblouis.

1977

1978

liblouisxml can be compiled to use either 16-bit or 32-bit Unicode

1979

internally. This is inherited from liblouis, so liblouis must be

1980

compiled first and then liblouisxml. Wherever 16 bits are mentioned in

1981

this document, read 32 if you have compiled the library for 32 bits.

1982

1983

1984

1985

<h3 class="section">7.3 Files and Paths</h3>

1986

1987

As stated in the previous section, liblouisxml uses three kinds of

1988

files, configuration files, semantic-action files, and liblouis

1989

translation tables. The first two are discussed later in this

1990

documentation. liblouis translation tables are discussed in the

1991

liblouis documentation (see <a href="liblouis.html#Top">Overview</a>) which is distributed with liblouis.

1992

These files can be placed on various paths, which are determined at

1993

compile time. One of these paths should be to the <samp>lbx_files</samp>

1994

directory provided by liblouisxml, which contains the principal

1995

configuration file (<samp>canonical.cfg</samp>) and the semantic-action

1996

files. Another should be to the tables directory in the liblouis

1997

distribution. Note that liblouisxml also generates some files, all of

1998

which are placed in the current directory. These files are new

1999

prototype semantic-action files, additions to old semantic-action

2000

files, temporary files, and log files. The first two can be used to

2001

extend the capability of liblouisxml to process xml documents. The

2002

latter two are useful for debugging.

2003

2004

Paths are set by changing a few lines of code in the <samp>paths.c</samp>

2005

module. If you are preparing liblouisxml for Windows a function which

2006

finds the name of the "Program Files" directory for your locale is

2007

called automatically. You can then modify the line containing the term

2008

`<samp>yourSubDir</samp>' as needed. Note that this line will produce a

2009

deliberate compiler error, so you can find it easily.

2010

2011

If you are preparing liblouisxml for a Unix-type system look for the

2012

line that says `<samp>Set Unix Paths</samp>'. The following lines

2013

establish paths to the <samp>lbx_files</samp> directory and to the liblouis

2014

<samp>tables</samp> directory. If you are using the Gnu autotooled versions of

2015

liblouis and liblouisxml these paths are set up automatically.

2016

2017

The function <code>addPath</code> takes care of adding a path to liblouisxml

2018

properly. You can specify many more than two paths.

2019

2020

2021

2022

2023

<h3 class="section">7.4 lbx_version</h3>

2024

2025

2026

<pre class="example"> char *lbx_version (void)

2027

</pre>

2028

This function returns a pointer to a character string containing the

2029

version of liblouisxml. Other information such as the release

2030

date and perhaps notable changes may be added later.

2031

2032

2033

2034

2035

<h3 class="section">7.5 lbx_initialize</h3>

2036

2037

2038

<pre class="example"> void * lbx_initialize (

2039

const char *configFilelist,

2040

const char *logFileName,

2041

const char *settingsString)

2042

</pre>

2043

This function initializes the libxml2 library, processes

2044

<samp>canonical.cfg</samp> and configuration settings given in

2045

<code>settingsString</code> and the configuration files given in

2046

<code>configFilelist</code>. This is a list of configuration file names

2047

separated by commas. If the first character is a comma it is taken to

2048

be a string containing configuration settings and is processed like

2049

the <code>settingsString</code> string. Such a string must conform to the

2050

format of a configuration file. Newlines should be represented with

2051

ASCII 10. If <code>logfilename</code> is not <code>null</code>, a log file is

2052

produced on the current directory. If it is <code>null</code> any messages

2053

are printed on stderr. The function returns a pointer to the

2054

<code>UserData</code> structure. This pointer is <code>void</code> and must be

2055

cast to <code>(UserData *)</code> in the calling program. To access the

2056

information in this structure you must include <samp>louisxml.h</samp>. This

2057

function is used by <samp>xml2brl</samp>.

2058

2059

2060

2061

2062

<h3 class="section">7.6 lbx_translateString</h3>

2063

2064

2065

<pre class="example"> int lbx_translateString (

2066

const char *configfilelist,

2067

char * inbuf,

2068

widechar *outbuf,

2069

int *outlen,

2070

unsigned int mode)

2071

</pre>

2072

This function takes a well-formed xml expression in <code>inbuf</code> and

2073

translates it into a string of 16-bit (or 32-bit if this has been

2074

specified in liblouis) braille characters in <code>outbuf</code>. The xml

2075

expression must be immediately followed by a zero or null byte.

2076

Leading whitespace is ignored. If it does not then begin with the

2077

characters `<samp><?xml</samp>' an xml header is added. If it does not begin

2078

with `<samp><</samp>' it is assumed to be a text string and is translated

2079

accordingly. The header is specified by the <code>xmlHeader</code> line in

2080

the configuration file. If no such line is present, a default header

2081

specifying UTF-8 encoding is used. The <code>mode</code> parameter specifies

2082

whether you want the library to be initialized. If it is 0 everything

2083

is reset, the <samp>canonical.cfg</samp> file is processed and the

2084

configuration file and/or string (see previous section) are processed.

2085

If <code>mode</code> is 1 liblouisxml simply prepares to handle a new

2086

document. For more on the <code>mode</code> parameter see the next section.

2087

2088

Which 16-bit character in <code>outbuf</code> represents which dot pattern

2089

is indicated in the liblouis translation tables. The

2090

<code>configfilelist</code> parameter points to a configuration file or

2091

string. Among other things, this file specifies translation tables. It

2092

is these tables which control just how the translation is made,

2093

whether in Grade 2, Grade 1, the Nemeth Code of Braille Mathematics or

2094

something else.

2095

2096

Note that the <code>*outlen</code> parameter is a pointer to an integer.

2097

When the function is called, this integer contains the maximum output

2098

length. When it returns, it is set to the actual length used. The

2099

function returns 1 if no errors were encountered and a negative number

2100

if a complete translation could not be done.

2101

2102

2103

2104

2105

<h3 class="section">7.7 lbx_translateFile</h3>

2106

2107

2108

<pre class="example"> int lbx_translateFile (

2109

char *configfilelist,

2110

char *inputFileName,

2111

char *outputFileName,

2112

unsigned int mode)

2113

</pre>

2114

This function accepts a well-formed xml document in

2115

<code>inputFilename</code> and produces a braille translation in

2116

<code>outputFilename</code>. As for <code>lbx_translateString</code>, the

2117

<code>mode</code> parameter specifies whether the library is to be

2118

initialized with new configuration information or simply prepared to

2119

handle a new document. In addition, the <code>mode</code> parameter can

2120

specify that a document is in html, not xhtml. <samp>liblouisxml.h</samp>

2121

contains an enumeration type with the values <code>dontInit</code> and

2122

<code>htmlDoc</code>. These can be combined with an or (`<samp>|</samp>') operator. The

2123

input file is assumed to be encoded in UTF-8, unless otherwise

2124

specified in the xml header. The encoding of the output file may be

2125

UTF-8, UTF-16, UTF-32 or Ascii-8. This is specified by the

2126

<code>outputEncoding</code> line in the configuration file,

2127

<code>configfilelist</code>. The function returns 1 if the translation was

2128

successful.

2129

2130

2131

2132

2133

<h3 class="section">7.8 lbx_translateTextFile</h3>

2134

2135

2136

<pre class="example"> int lbx_translateTextFile (

2137

char *configfilelist,

2138

char *inputFileName,

2139

char *outputFileName,

2140

unsigned int mode)

2141

</pre>

2142

This function accepts a text file in <code>inputFilename</code> and produces

2143

a braille translation in <code>outputFilename</code>. The input file is

2144

assumed to be encoded in Ascii8. However, utf-8 can be specified with

2145

the configuration setting <code>inputTextEncoding utf8</code>. Blank lines

2146

indicate the divisions between paragraphs. Two blank lines cause a

2147

blank line between paragraphs (or headers). The output file may be in

2148

UTF-8, UTF-16, or Ascii8, as specified by the <code>outputEncoding</code>

2149

line in the configuration file, <code>configfilelist</code>. As for

2150

<code>lbx_translateString</code>, the <code>mode</code> parameter specifies

2151

whether complete initialization is to be done or simply initialization

2152

for a new document.

2153

2154

2155

2156

2157

<h3 class="section">7.9 lbx_backTranslateFile</h3>

2158

2159

2160

<pre class="example"> int lbx_backTranslateFile (

2161

char *configfilelist,

2162

char *inputFileName,

2163

char *outputFileName,

2164

unsigned int mode)

2165

</pre>

2166

This function accepts a braille file in <code>inputFilename</code> and

2167

produces a back-translation in <code>outputFilename</code>. The input file

2168

is assumed to be encoded in Ascii8. The output file is in either plain

2169

text or html, according to the setting of <code>backFormat</code> in the

2170

configuration file. Html files are encoded in UTF8. In plain-text,

2171

blank lines are inserted between paragraphs. The output file may be in

2172

UTF-8, UTF-16, or Ascii8, as specified by the <code>outputEncoding</code>

2173

line in the configuration file, <code>configfilelist</code>. The mode

2174

parameter specifies whether or not the library is to be initialized

2175

with new configuration information, as described in the section on

2176

<code>lbx_translateString</code> (see <a href="#lbx_005ftranslateString">lbx_translateString</a>).

2177

2178

2179

2180

2181

2182

2183

2184

<pre class="example"> void lbx_free (void)

2185

</pre>

2186

This function should be called at the end of the application to free

2187

all memory allocated by liblouisxml and liblouis. If you wish to

2188

change configuration files during your application, use a <code>mode</code>

2189

parameter of 0 on the function call using the new configuration

2190

information. This will call the function automatically.

2191

2192

2193

2194

<h2 class="unnumbered">Configuration Settings Index</h2>

2195

2196

2197

<li><a href="#index-backFormat-19"><code>backFormat</code></a>: <a href="#outputFormat">outputFormat</a></li>

2198

<li><a href="#index-backLineLength-20"><code>backLineLength</code></a>: <a href="#outputFormat">outputFormat</a></li>

2199

<li><a href="#index-beginningPageNumber-12"><code>beginningPageNumber</code></a>: <a href="#outputFormat">outputFormat</a></li>

2200

<li><a href="#index-braillePageNumberAt-14"><code>braillePageNumberAt</code></a>: <a href="#outputFormat">outputFormat</a></li>

2201

<li><a href="#index-braillePages-10"><code>braillePages</code></a>: <a href="#outputFormat">outputFormat</a></li>

2202

<li><a href="#index-cellsPerLine-3"><code>cellsPerLine</code></a>: <a href="#outputFormat">outputFormat</a></li>

2203

<li><a href="#index-center-71"><code>center</code></a>: <a href="#style">style</a></li>

2204

<li><a href="#index-compbrailleTable-25"><code>compbrailleTable</code></a>: <a href="#translation">translation</a></li>

2205

<li><a href="#index-editTable-28"><code>editTable</code></a>: <a href="#translation">translation</a></li>

2206

<li><a href="#index-entity-32"><code>entity</code></a>: <a href="#xml">xml</a></li>

2207

<li><a href="#index-fileEnd-8"><code>fileEnd</code></a>: <a href="#outputFormat">outputFormat</a></li>

2208

<li><a href="#index-firstLineIndent-38"><code>firstLineIndent</code></a>: <a href="#style">style</a></li>

2209

<li><a href="#index-format-41"><code>format</code></a>: <a href="#style">style</a></li>

2210

<li><a href="#index-formatFor-18"><code>formatFor</code></a>: <a href="#outputFormat">outputFormat</a></li>

2211

<li><a href="#index-hyphenate-15"><code>hyphenate</code></a>: <a href="#outputFormat">outputFormat</a></li>

2212

<li><a href="#index-inputTextEncoding-17"><code>inputTextEncoding</code></a>: <a href="#outputFormat">outputFormat</a></li>

2213

<li><a href="#index-interline-21"><code>interline</code></a>: <a href="#outputFormat">outputFormat</a></li>

2214

<li><a href="#index-interlineBackTable-29"><code>interlineBackTable</code></a>: <a href="#translation">translation</a></li>

2215

<li><a href="#index-internetAccess-33"><code>internetAccess</code></a>: <a href="#xml">xml</a></li>

2216

<li><a href="#index-interpoint-5"><code>interpoint</code></a>: <a href="#outputFormat">outputFormat</a></li>

2217

<li><a href="#index-leftMargin-37"><code>leftMargin</code></a>: <a href="#style">style</a></li>

2218

<li><a href="#index-lineEnd-6"><code>lineEnd</code></a>: <a href="#outputFormat">outputFormat</a></li>

2219

<li><a href="#index-lineFill-22"><code>lineFill</code></a>: <a href="#outputFormat">outputFormat</a></li>

2220

<li><a href="#index-linesAfter-36"><code>linesAfter</code></a>: <a href="#style">style</a></li>

2221

<li><a href="#index-linesBefore-35"><code>linesBefore</code></a>: <a href="#style">style</a></li>

2222

<li><a href="#index-linesPerPage-4"><code>linesPerPage</code></a>: <a href="#outputFormat">outputFormat</a></li>

2223

<li><a href="#index-literaryTextTable-23"><code>literaryTextTable</code></a>: <a href="#translation">translation</a></li>

2224

<li><a href="#index-MathexpTable-27"><code>MathexpTable</code></a>: <a href="#translation">translation</a></li>

2225

<li><a href="#index-mathtextTable-26"><code>mathtextTable</code></a>: <a href="#translation">translation</a></li>

2226

<li><a href="#index-newEntries-34"><code>newEntries</code></a>: <a href="#xml">xml</a></li>

2227

<li><a href="#index-newPageAfter-43"><code>newPageAfter</code></a>: <a href="#style">style</a></li>

2228

<li><a href="#index-newPageBefore-42"><code>newPageBefore</code></a>: <a href="#style">style</a></li>

2229

<li><a href="#index-outputEncoding-16"><code>outputEncoding</code></a>: <a href="#outputFormat">outputFormat</a></li>

2230

<li><a href="#index-pageEnd-7"><code>pageEnd</code></a>: <a href="#outputFormat">outputFormat</a></li>

2231

<li><a href="#index-paragraphs-11"><code>paragraphs</code></a>: <a href="#outputFormat">outputFormat</a></li>

2232

<li><a href="#index-printPageNumberAt-13"><code>printPageNumberAt</code></a>: <a href="#outputFormat">outputFormat</a></li>

2233

<li><a href="#index-printPages-9"><code>printPages</code></a>: <a href="#outputFormat">outputFormat</a></li>

2234

<li><a href="#index-rightHandPage-44"><code>rightHandPage</code></a>: <a href="#style">style</a></li>

2235

<li><a href="#index-semanticFiles-30"><code>semanticFiles</code></a>: <a href="#xml">xml</a></li>

2236

<li><a href="#index-skipNumberLines-40"><code>skipNumberLines</code></a>: <a href="#style">style</a></li>

2237

<li><a href="#index-translate-39"><code>translate</code></a>: <a href="#style">style</a></li>

2238

<li><a href="#index-uncontractedTable-24"><code>uncontractedTable</code></a>: <a href="#translation">translation</a></li>

2239

<li><a href="#index-xmlheader-31"><code>xmlheader</code></a>: <a href="#xml">xml</a></li>

2240

</ul><a name="Semantic-Action-Index"></a>

2241

2242

<h2 class="unnumbered">Semantic Action Index</h2>

2243

2244

2245

2246

2247

<li><a href="#index-configfile-111">configfile</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2248

<li><a href="#index-configstring-112">configstring</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2249

<li><a href="#index-configtweak-113">configtweak</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2250

<li><a href="#index-contentsheader-114">contentsheader</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2251

<li><a href="#index-document-103">document</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2252

<li><a href="#index-heading1-104">heading1</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2253

<li><a href="#index-heading2-105">heading2</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2254

<li><a href="#index-heading3-106">heading3</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2255

<li><a href="#index-heading4-107">heading4</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2256

<li><a href="#index-italicx-115">italicx</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2257

<li><a href="#index-list-108">list</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2258

<li><a href="#index-math-116">math</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2259

<li><a href="#index-notranslate-117">notranslate</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2260

<li><a href="#index-para-109">para</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2261

<li><a href="#index-skip-118">skip</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2262

<li><a href="#index-softreturn-119">softreturn</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2263

<li><a href="#index-table-110">table</a>: <a href="#Semantic-Actions-in-detail">Semantic Actions in detail</a></li>

2264

</ul><a name="Function-Index"></a>

2265

2266

<h2 class="unnumbered">Function Index</h2>

2267

2268

2269

2270

2271

<li><a href="#index-lbx_005fbackTranslateFile-125"><code>lbx_backTranslateFile</code></a>: <a href="#lbx_005fbackTranslateFile">lbx_backTranslateFile</a></li>

2272

2273

<li><a href="#index-lbx_005finitialize-121"><code>lbx_initialize</code></a>: <a href="#lbx_005finitialize">lbx_initialize</a></li>

2274

<li><a href="#index-lbx_005ftranslateFile-123"><code>lbx_translateFile</code></a>: <a href="#lbx_005ftranslateFile">lbx_translateFile</a></li>

2275

<li><a href="#index-lbx_005ftranslateString-122"><code>lbx_translateString</code></a>: <a href="#lbx_005ftranslateString">lbx_translateString</a></li>

2276

<li><a href="#index-lbx_005ftranslateTextFile-124"><code>lbx_translateTextFile</code></a>: <a href="#lbx_005ftranslateTextFile">lbx_translateTextFile</a></li>

2277

<li><a href="#index-lbx_005fversion-120"><code>lbx_version</code></a>: <a href="#lbx_005fversion">lbx_version</a></li>

2278

</ul><a name="Program-Index"></a>

2279

2280

<h2 class="unnumbered">Program Index</h2>

2281

2282

2283

2284

2285

<li><a href="#index-msword2brl-2"><code>msword2brl</code></a>: <a href="#Transcribing-Microsoft-Word-Files-with-msword2brl">Transcribing Microsoft Word Files with msword2brl</a></li>

2286

<li><a href="#index-xml2brl-1"><code>xml2brl</code></a>: <a href="#Transcribing-with-the-xml2brl-program">Transcribing with the xml2brl program</a></li>

2287

</ul></body></html>

2288