~ubuntu-branches/ubuntu/trusty/openjade1.3/trusty

openjade [-vCegG2s] [-b encoding] [-f error_file] [-c catalog_sysid] [-D dir] [-a link_type] [-A arch] [-E max_errors] [-i entity] [-w warning_type] [-d dsssl_spec] [-V variable[=value]] [-t (fot|rtf|tex|mif|sgml|xml)] [-o output_file] sysid...

-->

<title>Description</title>

<para>

<command>openjade</command> is an implementation of the ISO/IEC 10179:1996 standard DSSSL

language. The DSSSL engine receives as input an SGML or XML document and transforms it into formats like:</para>

<para>* XML representation of the flow object tree.</para>

<para>* RTF format that can be rendered and printed with Microsoft's free Word Viewer 97</para>

<para>* TeX format</para>

<para>* MIF format that can be rendered and printed with Framemaker</para>

<para>* SGML or XML format. This is used in conjunction with non-standard

flow object classes to generate SGML, thus allowing <command>openjade</command> to be

used for SGML/XML transformations. </para>

<para>The system identifier of the document to be processed is specified as an

argument to <command>openjade</command>. If this is omitted, standard input will be read. </para>

<para><command>openjade</command> determines the system identifier for the DSSSL specification as

follows: </para>

<para>1. If the -d option is specified, it will use the argument as the

system identifier. </para>

<para>2. Otherwise, it will look for processing instructions in the prolog of

the document. Two kinds of processing instruction are recognized: </para>

<para>

<?stylesheet href="sysid" type="text/dsssl"> </para>

<para> The system data of the processing instruction is parsed like

an SGML start-tag. It will be parsed using the reference

concrete syntax whatever the actual concrete syntax of the

document. The name that starts the processing instruction

can be either stylesheet, xml-stylesheet or xml:stylesheet.

The processing instruction will be ignored unless the value

of the type attribute is one of text/dsssl, text/x-dsssl,

application/dsssl, or application/x-dsssl. The value of href

attribute is the system identifier of the DSSSL

specification. </para>

100

<para>

101

<?dsssl sysid> </para>

102

<para> The system identifier is the portion of the system data of

103

the processing instruction following the initial name and

104

any whitespace. </para>

105

106

<para> Although the processing instruction is only recognized in the

107

prolog, it need not occur in the document entity. For example, it

108

could occur in a DTD. The system identifier will be interpreted

109

relative to where the the processing instruction occurs. </para>

110

111

<para> 3. Otherwise, it will use the system identifier of the document with

112

any extension changed to .dsl. </para>

113

114

<para> A DSSSL specification document can contain more than one

115

style-specification. If the system identifier of the DSSSL specification

116

is followed by #id, then <command>openjade</command> will use the style-specification whose

117

unique identifier is id. This is allowed both with the <option>-d</option> option and

118

with the processing instructions. </para>

119

120

<para> The DSSSL specification must be an SGML document conforming to the DSSSL

121

architecture. For an example, see <filename>dsssl/demo.dsl</filename>. </para>

122

123

<para><command>openjade</command> supports the following options in addition to the normal OpenSP (see <command>onsgmls(1)</command>)

124

options (note that all options are case-sensitive, ie <option>-g</option> and <option>-G</option> are

125

different options):</para>

126

127

128

129

<term><option>-d <replaceable>dsssl_spec</replaceable></option></term>

130

131

<para> This specifies that dsssl_spec is the system identifier of the DSSSL

132

specification to be used. </para>

133

</listitem>

134

</varlistentry>

135

136

137

138

139

<para>Debug mode. When an error occurs in the evaluation of an expression,

140

<command>openjade</command> will display a stack trace. Note that this disables

141

tail-call optimization.</para>

142

</listitem>

143

</varlistentry>

144

145

<term><option>-c <replaceable>filename</replaceable></option></term>

146

147

<para>The filename arguments specify catalog files rather than the document

148

entity. The document entity is specified by the first DOCUMENT entry

149

in the catalog files. </para>

150

</listitem>

151

</varlistentry>

152

153

154

155

156

<para>

157

Strict compliance mode. Currently the only effect is that jade

158

doesn't use any predefined character names, sdata-entity mappings or

159

name-characters. This is useful for checking that your stylesheet is

160

portable to other DSSSL implementations and that it is strictly

161

compliant to the DSSSL specifications. </para>

162

</listitem>

163

</varlistentry>

164

165

166

<term><option>-t <replaceable>output_type</replaceable></option></term>

167

168

<para><replaceable>output_type</replaceable> specifies the type of output as follows: </para>

169

170

An XML representation of the flow object tree </para>

171

172

RTF (used for SGML/XML to RTF transformations)

173

Microsoft's Rich Text Format. rtf-95 produces output

174

optimized for Word 95 rather than Word 97.</para>

175

176

TeX (used for SGML/XML to TeX transformations)</para>

177

178

SGML (used for SGML/XML to SGML transformations). sgml-raw

179

doesn't emit linebreaks in tags. </para>

180

181

XML (used for SGML/XML to XML transformations). xml-raw

182

doesn't emit linebreaks in tags.</para>

183

184

HTML (used for SGML/XML to HTML transformations)</para>

185

186

MIF (used for SGML/XML to MIF transformations) </para>

187

</listitem>

188

</varlistentry>

189

190

191

<term><option>-o <replaceable>output_file</replaceable></option></term>

192

193

<para>Write output to <replaceable>output_file</replaceable> instead of the default. The default

194

filename is the name of the last input file with its extension

195

replaced by the name of the type of output. If there is no input

196

filename, then the extension is added onto jade-out.</para>

197

</listitem>

198

</varlistentry>

199

200

201

<term><option>-V <replaceable>variable</replaceable></option></term>

202

<listitem><para>This is equivalent to doing (define variable #t) except that this

203

definition will take priority over any definition of variable in a

204

style-sheet.</para></listitem>

205

</varlistentry>

206

207

208

<term><option>-V <replaceable>variable=value</replaceable></option></term>

209

<listitem><para>This is equivalent to doing (define <replaceable>variable</replaceable> "<replaceable>value</replaceable>") except that

210

this definition will take priority over any definition of variable in

211

a style-sheet.</para></listitem>

212

</varlistentry>

213

214

215

<term><option>-V (define <replaceable>variable</replaceable> <replacable>value</replacable>)</option></term>

216

<listitem><para>This is equivalent to doing (define variable value) except that this

217

definition will take priority over any definition of variable in a

218

style-sheet. Note that you will probably have to use some escaping

219

mechanism for the spaces to get the entire scheme expression parsed

220

as one cmdline argument.</para></listitem>

221

</varlistentry>

222

223

224

225

<listitem><para>Control warnings and errors. Multiple <option>-w</option> options are allowed. The

226

following values of type enable warnings: </para>

227

228

229

Warn about constructs that are not allowed by XML.</para>

230

231

<para><option>mixed</option>

232

Warn about mixed content models that do not allow #pcdata

233

anywhere.</para>

234

235

<para><option>sgmldecl</option>

236

Warn about various dubious constructions in the SGML

237

declaration.</para>

238

239

<para><option>should</option>

240

Warn about various recommendations made in ISO 8879 that the

241

document does not comply with. (Recommendations are expressed

242

with ``should'', as distinct from requirements which are

243

usually expressed with ``shall''.)</para>

244

245

<para><option>default</option>

246

Warn about defaulted references.</para>

247

248

<para><option>duplicate</option>

249

Warn about duplicate entity declarations.</para>

250

251

<para><option>undefined</option>

252

Warn about undefined elements: elements used in the DTD but

253

not defined.</para>

254

255

<para><option>unclosed</option>

256

Warn about unclosed start and end-tags.</para>

257

258

<para><option>empty</option>

259

Warn about empty start and end-tags.</para>

260

261

262

Warn about net-enabling start-tags and null end-tags.</para>

263

264

265

Warn about minimized start and end-tags. Equivalent to

266

combination of unclosed, empty and net warnings.</para>

267

268

<para><option>unused-map</option>

269

Warn about unused short reference maps: maps that are

270

declared with a short reference mapping declaration but never

271

used in a short reference use declaration in the DTD.</para>

272

273

<para><option>unused-param</option>

274

Warn about parameter entities that are defined but not used

275

in a DTD. Unused internal parameter entities whose text is

276

INCLUDE or IGNORE won't get the warning.</para>

277

278

<para><option>notation-sysid</option>

279

Warn about notations for which no system identifier could be

280

generated.</para>

281

282

283

Warn about conditions that should usually be avoided (in the

284

opinion of the author). Equivalent to: mixed, should,

285

default, undefined, sgmldecl, unused-map, unused-param, empty

286

and unclosed.</para>

287

288

<para>A warning can be disabled by using its name prefixed with no-. Thus

289

<option>-wall</option> <option>-wno-duplicate</option> will enable all warnings except those about

290

duplicate entity declarations.</para>

291

292

<para>The following values for <replaceable>warning_type</replaceable> disable errors:</para>

293

294

<para><option>no-idref</option>

295

Do not give an error for an ID reference value which no

296

element has as its ID. The effect will be as if each

297

attribute declared as an ID reference value had been declared

298

as a name.</para>

299

300

<para><option>no-significant</option>

301

Do not give an error when a character that is not a

302

significant character in the reference concrete syntax occurs

303

in a literal in the SGML declaration. This may be useful in

304

conjunction with certain buggy test suites.</para>

305

306

<para><option>no-valid</option>

307

Do not require the document to be type-valid. This has the

308

effect of changing the SGML declaration to specify VALIDITY

309

NOASSERT and IMPLYDEF ATTLIST YES ELEMENT YES. An option of

310

<option>-wvalid</option> has the effect of changing the SGML declaration to

311

specify VALIDITY TYPE and IMPLYDEF ATTLIST NO ELEMENT NO. If

312

neither <option>-wvalid</option> nor <option>-wno-valid</option> are specified, then the

313

VALIDITY and IMPLYDEF specified in the SGML declaration will

314

be used. </para>

315

</listitem>

316

</varlistentry>

317

</variablelist>

318

</refsect1>

319

320

321

<title>Environment</title>

322

323

<para> OpenJade ignores the SP_CHARSET_FIXED and SP_SYSTEM_CHARSET environment

324

variables and always uses Unicode as its internal character set, as if

325

SP_CHARSET_FIXED was 1 and SP_SYSTEM_CHARSET was unset. Thus only the

326

SP_ENCODING environment variable is relevant to OpenJade's handling of

327

character sets.</para>

328

</refsect1>

329

330

331

<title>OpenJade Extensions</title>

332

333

<para>The following external procedures are available. These external

334

procedures are defined by a prototype in the same manner as in the

335

standard. To use one of these external procedures, you must make use of

336

the standard external-procedure procedure, using a public identifier of

337

"UNREGISTERED::James Clark//Procedure::name" where name is the name

338

given here, typically by including the following in the DSSSL

339

specification:</para>

340

341

<para>(define name

342

(external-procedure "UNREGISTERED::James Clark//Procedure::name"))</para>

343

344

<para>Note that external-procedure returns #f if it doesn't know about the

345

specified public identifier. You can use this to enable your DSSSL

346

specifications to work gracefully with other implementations which do

347

not support these extensions.</para>

348

349

<para>For external procedures added by the OpenJade team, use a public

350

identifier of the form "UNREGISTERED::OpenJade//Procedure::name".</para>

351

352

<para>An easy way to get access to all external procedures is to use the style

353

specification dsssl/extensions.dsl#procedures. The file

354

dsssl/extensions.dsl also contains style specifications which make the

355

nonstandard flow object classes and inherited characteristics supported

356

by the backends available in a convenient way.</para>

357

358

<para><option>Debugging</option></para>

359

360

<para>(debug obj)</para>

361

362

<para>Generates a message including the value of obj and then returns obj.</para>

363

364

<para><option>Simple-page-sequence header/footer control</option></para>

365

366

<para>(if-first-page sosofo1 sosofo2)</para>

367

368

<para>This can be used only in the specification of the value of one of the

369

header/footer characteristics of simple-page-sequence. It returns a

370

sosofo that will display as sosofo1 if the page is the first page of the

371

simple-page-sequence and as sosofo2 otherwise.</para>

372

373

374

<para>(if-front-page sosofo1 sosofo2)</para>

375

376

<para>This can be used only in the specification of the value of one of the

377

header/footer characteristics of simple-page-sequence. It returns a

378

sosofo that will display as sosofo1 if the page is a front (ie recto,

379

odd-numbered) page and as sosofo2 if it is a back (ie verso,

380

even-numbered) page.</para>

381

382

<para><option>Numbering</option></para>

383

384

<para>(all-element-number)</para>

385

<para>(all-element-number osnl)</para>

386

387

<para>This is the same as element-number except it counts elements with any

388

generic identifier. If osnl is not an element returns #f, otherwise

389

returns 1 plus the number of elements that started before osnl. This

390

provides an efficient way of creating a unique identifier for any

391

element in a document.</para>

392

393

<para><option>External entity access</option></para>

394

395

<para>(read-entity string)</para>

396

397

<para>This returns a string containing the contents of the external entity

398

with system identifier string. This should be used only for textual

399

entities (CDATA and SDATA), and not for binary entities (NDATA).</para>

400

401

<para><option>POSIX locale access</option></para>

402

403

<para>(language lang country)</para>

404

405

<para>This procedure returns an object of type language, if the system

406

supports the specified language. lang is a string or symbol giving the

407

two letter language code. country is a string or symbol giving the two

408

letter country code.</para>

409

410

<para>This procedure uses POSIX locales. It is an OpenJade addition. It is not supported on all operating systems.</para>

411

412

<para><option>Extended standard procedures</option></para>

413

414

<para>(sgml-parse sysid #!key active: parent: architecture:)</para>

415

416

<para>This allows you to specify an SGML architecture with respect to which

417

the document should be parsed. It is an OpenJade addition.</para>

418

419

420

421

<para>This allows you to raise a quantity to an integral power. It is an

422

OpenJade addition.</para>

423

</refsect1>

424

425

426

<title>Limitations</title>

427

428

<para>This section describes the limitations of the front-end (the

429

general-purpose DSSSL engine); each backend also has its own

430

limitations.</para>

431

432

<para><command>openjade</command> doesn't allow internal definitions at the beginning of bodies and

433

the (test => recipient) variant of cond clauses.</para>

434

435

<para><command>openjade</command> supports only a single, fixed grove plan which comprises the

436

following modules:</para>

437

438

<para>* baseabs</para>

439

<para>* prlgabs0</para>

440

<para>* prlgabs1</para>

441

<para>* instabs</para>

442

<para>* basesds0</para>

443

<para>* instsds0</para>

444

<para>* subdcabs</para>

445

446

<para>It doesn't implement the following parts of SDQL: HyTime support,

447

auxiliary parsing, node regular expressions.</para>

448

449

<para>Query rules, sosofo synchronization, indirect sosofos, reference values,

450

decoration areas and font properties are not supported.</para>

451

452

<para>Note that only inherited characteristics that are applicable to some

453

supported flow object can be specified.</para>

454

455

<para><option>Character/glyph handling</option></para>

456

457

<para>It only supports a single pre-defined character repertoire. A character

458

name of the form U-XXXX where XXXX are four upper-case hexadecimal

459

digits, is recognized as referring to the Unicode character with that

460

code. For many characters, it is also possible to use the ISO/IEC 10646

461

name in lower-case with words separated by hyphens.</para>

462

463

<para>Some common SDATA entity names from the ISO entity sets are recognized

464

and mapped to characters. In addition an SDATA entity name of the form

465

U-XXXX, where XXXX are four upper-case hexadecimal digits, is mapped to

466

the Unicode character with that code.</para>

467

468

<para>OpenJade now supports the standard-chars, map-sdata-entity,

469

add-name-chars, add-separator-chars and char-repertoire declaration

470

element forms, allowing a style-sheet to define additional character

471

names, sdata entity mappings, name characters (i.e. characters allowed

472

in identifiers) and separator characters. Currently the only recognized

473

character repertoire is the built-in repertoire. It has the public

474

identifier "UNREGISTERED::OpenJade//Character Repertoire::OpenJade".</para>

475

476

<para><option>Validation</option></para>

477

478

<para>Several things that it would be desirable to have checked aren't

479

checked:</para>

480

481

<para>* When the allowed value of an inherited characteristic is a symbol,

482

OpenJade checks only that the value is a symbol that is allowed as

483

the value of some characteristic; #t and #f are treated as a special

484

kind of symbol in this case.</para>

485

<para>* OpenJade doesn't check whether a flow object is occurring in a

486

context where it is allowed.</para>

487

<para>* OpenJade does not prevent flow objects being attached to the

488

principal port of a flow object when the flow object shouldn't have

489

a principal port.</para>

490

<para>* Most type-checking is done at run-time not compile-time.</para>

491

<para>* OpenJade does not check for non-inherited characteristics that are

492

required to be specified.</para>

493

<para>* It doesn't check that optional features that have been used were

494

declared in the features form.</para>

495

496

<para><option>Other limitations</option></para>

497

498

<para>The following primitives are just stubs:</para>

499

500

<para><option>char-script-case</option>

501

Always returns last argument.</para>

502

503

<para><option>address-visited?</option>

504

Always returns #f.</para>

505

</refsect1>

506

507

<title>Examples</title>

508

<para>Given an SGML file <command>file.sgml</command>, use the stylesheet <command>file.dsl</command> and publish as an rtf file.</para>

509

510

<para>openjade -t rtf file.sgml</para>

511

512

<para>Using a different stylesheet:</para>

513

514

<para>openjade -t rtf -d docbook.dsl file.sgml</para>

515

516

<para>Using the <command>print</command> style specification contained

517

within the stylesheet</para>

518

519

<para>openjade -t rtf -d docbook.dsl#print file.sgml</para>

520

521

<para>And use the html specification within the style sheet to convert

522

to html</para>

523

524

<para>openjade -t sgml -i html -d docbook.dsl#html file.sgml</para>

525

</refsect1>

526

527

528

529

<para><command>onsgmls(1)</command></para>

530

</refsect1>

531

</refentry>

532

</section>

533

</article>

Older »