third_party/docbook-xsl-1.78.0/common/refentry.xml - Issue 1394993002: Doing some cleanup.

Side by Side Diff: third_party/docbook-xsl-1.78.0/common/refentry.xml

Issue 1394993002: Doing some cleanup. (Closed) Base URL: https://github.com/dart-lang/www.dartlang.org.git@master

Patch Set: Created 5 years, 2 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

OLD	NEW
	(Empty)
1 <?xml version="1.0"?>

2

3 <reference xml:id="refentry">

4 <info>

5 <title>Common » Refentry Metadata Template Reference</title>

6 <releaseinfo role="meta">

7 $Id: refentry.xsl 7867 2008-03-07 09:54:25Z xmldoc $

8 </releaseinfo>

9 </info>

10

11 <partintro xml:id="partintro">

12 <title>Introduction</title>

13

14 <para>This is technical reference documentation for the “refentry

15 metadata” templates in the DocBook XSL Stylesheets.</para>

16

17

18 <para>This is not intended to be user documentation. It is provided

19 for developers writing customization layers for the stylesheets.</para>

20

21 <note>

22

23 <para>Currently, only the manpages stylesheets make use of these

24 templates. They are, however, potentially useful elsewhere.</para>

25

26 </note>

27 </partintro>

28

29 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refent ry.metadata">

30 <refnamediv>

31 <refname>get.refentry.metadata</refname>

32 <refpurpose>Gathers metadata from a refentry and its ancestors</refpurpose>

33 </refnamediv>

34 <refsynopsisdiv>

35 <synopsis><xsl:template name="get.refentry.metadata">

36 <xsl:param name="refname"/>

37 <xsl:param name="info"/>

38 <xsl:param name="prefs"/>

39 ...

40 </xsl:template></synopsis>

41 </refsynopsisdiv>

42 <refsect1><title>Description</title>

43

44 <para>Reference documentation for particular commands, functions,

45 etc., is sometimes viewed in isolation from its greater "context". For

46 example, users view Unix man pages as, well, individual pages, not as

47 part of a "book" of some kind. Therefore, it is sometimes necessary to

48 embed "context" information in output for each <tag>refentry</tag>.</para>

49

50

51

52 <para>However, one problem is that different users mark up that

53 context information in different ways. Often (usually), the

54 context information is not actually part of the content of the

55 <tag>refentry</tag> itself, but instead part of the content of a

56 parent or ancestor element to the <tag>refentry</tag>. And

57 even then, DocBook provides a variety of elements that users might

58 potentially use to mark up the same kind of information. One user

59 might use the <tag>productnumber</tag> element to mark up version

60 information about a particular product, while another might use

61 the <tag>releaseinfo</tag> element.</para>

62

63

64

65 <para>Taking all that in mind, the

66 <function>get.refentry.metadata</function> template tries to gather

67 metadata from a <tag>refentry</tag> element and its ancestor

68 elements in an intelligent and user-configurable way. The basic

69 mechanism used in the XPath expressions throughout this stylesheet

70 is to select the relevant metadata from the *info element that is

71 closest to the actual <tag>refentry</tag> – either on the

72 <tag>refentry</tag> itself, or on its nearest ancestor.</para>

73

74

75 <note>

76

77 <para>The <function>get.refentry.metadata</function>

78 template is actually just sort of a "driver" template; it

79 calls other templates that do the actual data collection,

80 then returns the data as a set.</para>

81

82 </note>

83

84 </refsect1><refsect1><title>Parameters</title>

85

86 <variablelist>

87 <varlistentry>

88 <term>refname</term>

89 <listitem>

90

91 <para>The first <tag>refname</tag> in the refentry</para>

92

93 </listitem>

94 </varlistentry>

95 <varlistentry>

96 <term>info</term>

97 <listitem>

98

99 <para>A set of info nodes (from a <tag>refentry</tag>

100 element and its ancestors)</para>

101

102 </listitem>

103 </varlistentry>

104 <varlistentry>

105 <term>prefs</term>

106 <listitem>

107

108 <para>A node containing user preferences (from global

109 stylesheet parameters)</para>

110

111 </listitem>

112 </varlistentry>

113 </variablelist>

114

115 </refsect1><refsect1><title>Returns</title>

116

117 <para>Returns a node set with the following elements. The

118 descriptions are verbatim from the <literal>man(7)</literal> man

119 page.

120

121 <variablelist>

122 <varlistentry>

123 <term>title</term>

124 <listitem>

125

126 <para>the title of the man page (e.g., <literal>MAN</literal>)</para>

127

128 </listitem>

129 </varlistentry>

130 <varlistentry>

131 <term>section</term>

132 <listitem>

133

134 <para>the section number the man page should be placed in (e.g.,

135 <literal>7</literal>)</para>

136

137 </listitem>

138 </varlistentry>

139 <varlistentry>

140 <term>date</term>

141 <listitem>

142

143 <para>the date of the last revision</para>

144

145 </listitem>

146 </varlistentry>

147 <varlistentry>

148 <term>source</term>

149 <listitem>

150

151 <para>the source of the command</para>

152

153 </listitem>

154 </varlistentry>

155 <varlistentry>

156 <term>manual</term>

157 <listitem>

158

159 <para>the title of the manual (e.g., <citetitle>Linux

160 Programmer's Manual</citetitle>)</para>

161

162 </listitem>

163 </varlistentry>

164 </variablelist>

165

166 </para>

167

168 </refsect1></refentry>

169

170 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refent ry.title">

171 <refnamediv>

172 <refname>get.refentry.title</refname>

173 <refpurpose>Gets title metadata for a refentry</refpurpose>

174 </refnamediv>

175 <refsynopsisdiv>

176 <synopsis><xsl:template name="get.refentry.title">

177 <xsl:param name="refname"/>

178 ...

179 </xsl:template></synopsis>

180 </refsynopsisdiv>

181 <refsect1><title>Description</title>

182

183 <para>The <literal>man(7)</literal> man page describes this as "the

184 title of the man page (e.g., <literal>MAN</literal>). This differs

185 from <tag>refname</tag> in that, if the <tag>refentry</tag> has a

186 <tag>refentrytitle</tag>, we use that as the <tag>title</tag>;

187 otherwise, we just use first <tag>refname</tag> in the first

188 <tag>refnamediv</tag> in the source.</para>

189

190 </refsect1><refsect1><title>Parameters</title>

191

192 <variablelist>

193 <varlistentry>

194 <term>refname</term>

195 <listitem>

196

197 <para>The first <tag>refname</tag> in the refentry</para>

198

199 </listitem>

200 </varlistentry>

201 </variablelist>

202

203 </refsect1><refsect1><title>Returns</title>

204

205 <para>Returns a <tag>title</tag> node.</para>

206 </refsect1></refentry>

207

208 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refent ry.section">

209 <refnamediv>

210 <refname>get.refentry.section</refname>

211 <refpurpose>Gets section metadata for a refentry</refpurpose>

212 </refnamediv>

213 <refsynopsisdiv>

214 <synopsis><xsl:template name="get.refentry.section">

215 <xsl:param name="refname"/>

216 <xsl:param name="quiet" select="0"/>

217 ...

218 </xsl:template></synopsis>

219 </refsynopsisdiv>

220 <refsect1><title>Description</title>

221

222 <para>The <literal>man(7)</literal> man page describes this as "the

223 section number the man page should be placed in (e.g.,

224 <literal>7</literal>)". If we do not find a <tag>manvolnum</tag>

225 specified in the source, and we find that the <tag>refentry</tag> is

226 for a function, we use the section number <literal>3</literal>

227 ["Library calls (functions within program libraries)"]; otherwise, we

228 default to using <literal>1</literal> ["Executable programs or shell

229 commands"].</para>

230

231 </refsect1><refsect1><title>Parameters</title>

232

233 <variablelist>

234 <varlistentry>

235 <term>refname</term>

236 <listitem>

237

238 <para>The first <tag>refname</tag> in the refentry</para>

239

240 </listitem>

241 </varlistentry>

242 <varlistentry>

243 <term>quiet</term>

244 <listitem>

245

246 <para>If non-zero, no "missing" message is emitted</para>

247

248 </listitem>

249 </varlistentry>

250 </variablelist>

251

252 </refsect1><refsect1><title>Returns</title>

253

254 <para>Returns a string representing a section number.</para>

255 </refsect1></refentry>

256

257 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refent ry.date">

258 <refnamediv>

259 <refname>get.refentry.date</refname>

260 <refpurpose>Gets date metadata for a refentry</refpurpose>

261 </refnamediv>

262 <refsynopsisdiv>

263 <synopsis><xsl:template name="get.refentry.date">

264 <xsl:param name="refname"/>

265 <xsl:param name="info"/>

266 <xsl:param name="prefs"/>

267 ...

268 </xsl:template></synopsis>

269 </refsynopsisdiv>

270 <refsect1><title>Description</title>

271

272 <para>The <literal>man(7)</literal> man page describes this as "the

273 date of the last revision". If we cannot find a date in the source, we

274 generate one.</para>

275

276 </refsect1><refsect1><title>Parameters</title>

277

278 <variablelist>

279 <varlistentry>

280 <term>refname</term>

281 <listitem>

282

283 <para>The first <tag>refname</tag> in the refentry</para>

284

285 </listitem>

286 </varlistentry>

287 <varlistentry>

288 <term>info</term>

289 <listitem>

290

291 <para>A set of info nodes (from a <tag>refentry</tag>

292 element and its ancestors)</para>

293

294 </listitem>

295 </varlistentry>

296 <varlistentry>

297 <term>prefs</term>

298 <listitem>

299

300 <para>A node containing users preferences (from global stylesheet parameters)</p ara>

301

302 </listitem>

303 </varlistentry>

304 </variablelist>

305

306 </refsect1><refsect1><title>Returns</title>

307

308 <para>Returns a <tag>date</tag> node.</para>

309

310 </refsect1></refentry>

311

312 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refent ry.source">

313 <refnamediv>

314 <refname>get.refentry.source</refname>

315 <refpurpose>Gets source metadata for a refentry</refpurpose>

316 </refnamediv>

317 <refsynopsisdiv>

318 <synopsis><xsl:template name="get.refentry.source">

319 <xsl:param name="refname"/>

320 <xsl:param name="info"/>

321 <xsl:param name="prefs"/>

322 ...

323 </xsl:template></synopsis>

324 </refsynopsisdiv>

325 <refsect1><title>Description</title>

326

327 <para>The <literal>man(7)</literal> man page describes this as "the

328 source of the command", and provides the following examples:

329

330 <itemizedlist>

331 <listitem>

332

333 <para>For binaries, use something like: GNU, NET-2, SLS

334 Distribution, MCC Distribution.</para>

335

336 </listitem>

337 <listitem>

338

339 <para>For system calls, use the version of the kernel that you are

340 currently looking at: Linux 0.99.11.</para>

341

342 </listitem>

343 <listitem>

344

345 <para>For library calls, use the source of the function: GNU, BSD

346 4.3, Linux DLL 4.4.1.</para>

347

348 </listitem>

349 </itemizedlist>

350

351 </para>

352

353

354

355 <para>The <literal>solbook(5)</literal> man page describes

356 something very much like what <literal>man(7)</literal> calls

357 "source", except that <literal>solbook(5)</literal> names it

358 "software" and describes it like this:

359 <blockquote>

360

361 <para>This is the name of the software product that the topic

362 discussed on the reference page belongs to. For example UNIX

363 commands are part of the <literal>SunOS x.x</literal>

364 release.</para>

365

366 </blockquote>

367 </para>

368

369

370

371 <para>In practice, there are many pages that simply have a version

372 number in the "source" field. So, it looks like what we have is a

373 two-part field,

374 <replaceable>Name</replaceable> <replaceable>Version</replaceable>,

375 where:

376

377 <variablelist>

378 <varlistentry>

379 <term>Name</term>

380 <listitem>

381

382 <para>product name (e.g., BSD) or org. name (e.g., GNU)</para>

383

384 </listitem>

385 </varlistentry>

386 <varlistentry>

387 <term>Version</term>

388 <listitem>

389

390 <para>version name</para>

391

392 </listitem>

393 </varlistentry>

394 </variablelist>

395

396 Each part is optional. If the <replaceable>Name</replaceable> is a

397 product name, then the <replaceable>Version</replaceable> is probably

398 the version of the product. Or there may be no

399 <replaceable>Name</replaceable>, in which case, if there is a

400 <replaceable>Version</replaceable>, it is probably the version of the

401 item itself, not the product it is part of. Or, if the

402 <replaceable>Name</replaceable> is an organization name, then there

403 probably will be no <replaceable>Version</replaceable>.

404 </para>

405

406 </refsect1><refsect1><title>Parameters</title>

407

408 <variablelist>

409 <varlistentry>

410 <term>refname</term>

411 <listitem>

412

413 <para>The first <tag>refname</tag> in the refentry</para>

414

415 </listitem>

416 </varlistentry>

417 <varlistentry>

418 <term>info</term>

419 <listitem>

420

421 <para>A set of info nodes (from a <tag>refentry</tag>

422 element and its ancestors)</para>

423

424 </listitem>

425 </varlistentry>

426 <varlistentry>

427 <term>prefs</term>

428 <listitem>

429

430 <para>A node containing users preferences (from global

431 stylesheet parameters)</para>

432

433 </listitem>

434 </varlistentry>

435 </variablelist>

436

437 </refsect1><refsect1><title>Returns</title>

438

439 <para>Returns a <tag>source</tag> node.</para>

440

441 </refsect1></refentry>

442

443 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refent ry.source.name">

444 <refnamediv>

445 <refname>get.refentry.source.name</refname>

446 <refpurpose>Gets source-name metadata for a refentry</refpurpose>

447 </refnamediv>

448 <refsynopsisdiv>

449 <synopsis><xsl:template name="get.refentry.source.name">

450 <xsl:param name="refname"/>

451 <xsl:param name="info"/>

452 <xsl:param name="prefs"/>

453 ...

454 </xsl:template></synopsis>

455 </refsynopsisdiv>

456 <refsect1><title>Description</title>

457

458 <para>A "source name" is one part of a (potentially) two-part

459 <replaceable>Name</replaceable> <replaceable>Version</replaceable>

460 source field. For more details, see the documentation for the

461 <function>get.refentry.source</function> template.</para>

462

463 </refsect1><refsect1><title>Parameters</title>

464

465 <variablelist>

466 <varlistentry>

467 <term>refname</term>

468 <listitem>

469

470 <para>The first <tag>refname</tag> in the refentry</para>

471

472 </listitem>

473 </varlistentry>

474 <varlistentry>

475 <term>info</term>

476 <listitem>

477

478 <para>A set of info nodes (from a <tag>refentry</tag>

479 element and its ancestors)</para>

480

481 </listitem>

482 </varlistentry>

483 <varlistentry>

484 <term>prefs</term>

485 <listitem>

486

487 <para>A node containing users preferences (from global

488 stylesheet parameters)</para>

489

490 </listitem>

491 </varlistentry>

492 </variablelist>

493

494 </refsect1><refsect1><title>Returns</title>

495

496 <para>Depending on what output method is used for the

497 current stylesheet, either returns a text node or possibly an element

498 node, containing "source name" data.</para>

499

500 </refsect1></refentry>

501

502 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refent ry.version">

503 <refnamediv>

504 <refname>get.refentry.version</refname>

505 <refpurpose>Gets version metadata for a refentry</refpurpose>

506 </refnamediv>

507 <refsynopsisdiv>

508 <synopsis><xsl:template name="get.refentry.version">

509 <xsl:param name="refname"/>

510 <xsl:param name="info"/>

511 <xsl:param name="prefs"/>

512 ...

513 </xsl:template></synopsis>

514 </refsynopsisdiv>

515 <refsect1><title>Description</title>

516

517 <para>A "version" is one part of a (potentially) two-part

518 <replaceable>Name</replaceable> <replaceable>Version</replaceable>

519 source field. For more details, see the documentation for the

520 <function>get.refentry.source</function> template.</para>

521

522 </refsect1><refsect1><title>Parameters</title>

523

524 <variablelist>

525 <varlistentry>

526 <term>refname</term>

527 <listitem>

528

529 <para>The first <tag>refname</tag> in the refentry</para>

530

531 </listitem>

532 </varlistentry>

533 <varlistentry>

534 <term>info</term>

535 <listitem>

536

537 <para>A set of info nodes (from a <tag>refentry</tag>

538 element and its ancestors)</para>

539

540 </listitem>

541 </varlistentry>

542 <varlistentry>

543 <term>prefs</term>

544 <listitem>

545

546 <para>A node containing users preferences (from global

547 stylesheet parameters)</para>

548

549 </listitem>

550 </varlistentry>

551 </variablelist>

552

553 </refsect1><refsect1><title>Returns</title>

554

555 <para>Depending on what output method is used for the

556 current stylesheet, either returns a text node or possibly an element

557 node, containing "version" data.</para>

558

559 </refsect1></refentry>

560

561 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refent ry.manual">

562 <refnamediv>

563 <refname>get.refentry.manual</refname>

564 <refpurpose>Gets source metadata for a refentry</refpurpose>

565 </refnamediv>

566 <refsynopsisdiv>

567 <synopsis><xsl:template name="get.refentry.manual">

568 <xsl:param name="refname"/>

569 <xsl:param name="info"/>

570 <xsl:param name="prefs"/>

571 ...

572 </xsl:template></synopsis>

573 </refsynopsisdiv>

574 <refsect1><title>Description</title>

575

576 <para>The <literal>man(7)</literal> man page describes this as "the

577 title of the manual (e.g., <citetitle>Linux Programmer's

578 Manual</citetitle>)". Here are some examples from existing man pages:

579

580 <itemizedlist>

581 <listitem>

582

583 <para><citetitle>dpkg utilities</citetitle>

584 (<command>dpkg-name</command>)</para>

585

586 </listitem>

587 <listitem>

588

589 <para><citetitle>User Contributed Perl Documentation</citetitle>

590 (<command>GET</command>)</para>

591

592 </listitem>

593 <listitem>

594

595 <para><citetitle>GNU Development Tools</citetitle>

596 (<command>ld</command>)</para>

597

598 </listitem>

599 <listitem>

600

601 <para><citetitle>Emperor Norton Utilities</citetitle>

602 (<command>ddate</command>)</para>

603

604 </listitem>

605 <listitem>

606

607 <para><citetitle>Debian GNU/Linux manual</citetitle>

608 (<command>faked</command>)</para>

609

610 </listitem>

611 <listitem>

612

613 <para><citetitle>GIMP Manual Pages</citetitle>

614 (<command>gimp</command>)</para>

615

616 </listitem>

617 <listitem>

618

619 <para><citetitle>KDOC Documentation System</citetitle>

620 (<command>qt2kdoc</command>)</para>

621

622 </listitem>

623 </itemizedlist>

624

625 </para>

626

627

628

629 <para>The <literal>solbook(5)</literal> man page describes

630 something very much like what <literal>man(7)</literal> calls

631 "manual", except that <literal>solbook(5)</literal> names it

632 "sectdesc" and describes it like this:

633 <blockquote>

634

635 <para>This is the section title of the reference page; for

636 example <literal>User Commands</literal>.</para>

637

638 </blockquote>

639 </para>

640

641

642 </refsect1><refsect1><title>Parameters</title>

643

644 <variablelist>

645 <varlistentry>

646 <term>refname</term>

647 <listitem>

648

649 <para>The first <tag>refname</tag> in the refentry</para>

650

651 </listitem>

652 </varlistentry>

653 <varlistentry>

654 <term>info</term>

655 <listitem>

656

657 <para>A set of info nodes (from a <tag>refentry</tag>

658 element and its ancestors)</para>

659

660 </listitem>

661 </varlistentry>

662 <varlistentry>

663 <term>prefs</term>

664 <listitem>

665

666 <para>A node containing users preferences (from global

667 stylesheet parameters)</para>

668

669 </listitem>

670 </varlistentry>

671 </variablelist>

672

673 </refsect1><refsect1><title>Returns</title>

674

675 <para>Returns a <tag>manual</tag> node.</para>

676

677 </refsect1></refentry>

678

679 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refent ry.metadata.prefs">

680 <refnamediv>

681 <refname>get.refentry.metadata.prefs</refname>

682 <refpurpose>Gets user preferences for refentry metadata gathering</refpurpose>

683 </refnamediv>

684 <refsynopsisdiv>

685 <synopsis><xsl:template name="get.refentry.metadata.prefs"/></synopsis>

686 </refsynopsisdiv>

687 <refsect1><title>Description</title>

688

689 <para>The DocBook XSL stylesheets include several user-configurable

690 global stylesheet parameters for controlling <tag>refentry</tag>

691 metadata gathering. Those parameters are not read directly by the

692 other <tag>refentry</tag> metadata-gathering

693 templates. Instead, they are read only by the

694 <function>get.refentry.metadata.prefs</function> template,

695 which assembles them into a structure that is then passed to

696 the other <tag>refentry</tag> metadata-gathering

697 templates.</para>

698

699

700

701 <para>So the, <function>get.refentry.metadata.prefs</function>

702 template is the only interface to collecting stylesheet parameters for

703 controlling <tag>refentry</tag> metadata gathering.</para>

704

705 </refsect1><refsect1><title>Parameters</title>

706

707 <para>There are no local parameters for this template; however, it

708 does rely on a number of global parameters.</para>

709

710 </refsect1><refsect1><title>Returns</title>

711

712 <para>Returns a <tag>manual</tag> node.</para>

713

714 </refsect1></refentry>

715

716 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.set.refent ry.metadata">

717 <refnamediv>

718 <refname>set.refentry.metadata</refname>

719 <refpurpose>Sets content of a refentry metadata item</refpurpose>

720 </refnamediv>

721 <refsynopsisdiv>

722 <synopsis><xsl:template name="set.refentry.metadata">

723 <xsl:param name="refname"/>

724 <xsl:param name="info"/>

725 <xsl:param name="contents"/>

726 <xsl:param name="context"/>

727 <xsl:param name="preferred"/>

728 ...

729 </xsl:template></synopsis>

730 </refsynopsisdiv>

731 <refsect1><title>Description</title>

732

733 <para>The <function>set.refentry.metadata</function> template is

734 called each time a suitable source element is found for a certain

735 metadata field.</para>

736

737 </refsect1><refsect1><title>Parameters</title>

738

739 <variablelist>

740 <varlistentry>

741 <term>refname</term>

742 <listitem>

743

744 <para>The first <tag>refname</tag> in the refentry</para>

745

746 </listitem>

747 </varlistentry>

748 <varlistentry>

749 <term>info</term>

750 <listitem>

751

752 <para>A single *info node that contains the selected source element.</para>

753

754 </listitem>

755 </varlistentry>

756 <varlistentry>

757 <term>contents</term>

758 <listitem>

759

760 <para>A node containing the selected source element.</para>

761

762 </listitem>

763 </varlistentry>

764 <varlistentry>

765 <term>context</term>

766 <listitem>

767

768 <para>A string describing the metadata context in which the

769 <function>set.refentry.metadata</function> template was

770 called: either "date", "source", "version", or "manual".</para>

771

772 </listitem>

773 </varlistentry>

774 </variablelist>

775

776 </refsect1><refsect1><title>Returns</title>

777

778 <para>Returns formatted contents of a selected source element.</para>

779 </refsect1></refentry>

780 </reference>

781

OLD	NEW

« no previous file with comments | « third_party/docbook-xsl-1.78.0/common/pt_br.xml ('k') | third_party/docbook-xsl-1.78.0/common/refentry.xsl » ('j') | no next file with comments »