~ubuntu-branches/ubuntu/trusty/libpod-simple-perl/trusty

Committer: Bazaar Package Importer
Author(s): Jonathan Yu, Jonathan Yu, Salvatore Bonaccorso, Ryan Niebur, gregor herrmann
Date: 2009-10-26 19:03:16 UTC
mfrom: (1.1.5 upstream)
Revision ID: james.westby@ubuntu.com-20091026190316-f9z7itsbjva0k8tv

Tags: 3.09-1

[ Jonathan Yu ]
* New upstream release
* Standards-Version 3.8.3 (no changes)

[ Salvatore Bonaccorso ]
* debian/control: Changed: Replace versioned (build-)dependency on
  perl (>= 5.6.0-{12,16}) with an unversioned dependency on perl (as
  permitted by Debian Policy 3.8.3).

[ Ryan Niebur ]
* Update jawnsy's email address

[ gregor herrmann ]
* debian/control: Changed: (build-)depend on perl instead of perl-
  modules.
* debian/watch: use extended regexp for matching upstream versions.
* debian/rules: minimize and use override_* feature.

Show diffs side-by-side

added added

removed removed

lib/perlpod.pod

like "perldoc perlpod".

=head1 NAME

X<POD> X<plain old documentation>

perlpod - the Plain Old Documentation format

=head2 Ordinary Paragraph

X<POD, ordinary paragraph>

Most paragraphs in your documentation will be ordinary blocks

of text, like this one. You can simply type in your text without

=head2 Verbatim Paragraph

X<POD, verbatim paragraph> X<verbatim>

Verbatim paragraphs are usually used for presenting a codeblock or

other text which does not require any special parsing or formatting,

=head2 Command Paragraph

X<POD, command>

A command paragraph is used for special treatment of whole chunks

of text, usually as headings or parts of lists.

the command can use however it pleases. Currently recognized commands

are

=pod

=head1 Heading Text

=head2 Heading Text

=head3 Heading Text

=over indentlevel

=item stuff

=back

=cut

=pod

=begin format

=end format

=for format text...

=encoding type

=cut

To explain them each in detail:

=over

=item C<=head1 I<Heading Text>>

X<=head1> X<=head2> X<=head3> X<=head4>

X<head1> X<head2> X<head3> X<head4>

=item C<=head2 I<Heading Text>>

102

109

"L<Formatting Codes|/"Formatting Codes">" section, below.

103

110

104

111

=item C<=over I<indentlevel>>

112

X<=over> X<=item> X<=back> X<over> X<item> X<back>

105

113

106

114

=item C<=item I<stuff...>>

107

115

157

165

=back

158

166

159

167

=item C<=cut>

168

X<=cut> X<cut>

160

169

161

170

To end a Pod block, use a blank line,

162

171

then a line beginning with "=cut", and a blank

165

174

is not technically necessary, but many older Pod processors require it.)

166

175

167

176

=item C<=pod>

177

X<=pod> X<pod>

168

178

169

179

The "=pod" command by itself doesn't do much of anything, but it

170

180

signals to Perl (and Pod formatters) that a Pod block starts here. A

191

201

=cut

192

202

193

203

=item C<=begin I<formatname>>

204

X<=begin> X<=end> X<=for> X<begin> X<end> X<for>

194

205

195

206

=item C<=end I<formatname>>

196

207

203

214

will be completely ignored.

204

215

205

216

A command "=begin I<formatname>", some paragraphs, and a

206

command "=end I<formatname>", mean that the text/data inbetween

217

command "=end I<formatname>", mean that the text/data in between

207

218

is meant for formatters that understand the special format

208

219

called I<formatname>. For example,

209

220

269

280

normal formatting (e.g., may not be a normal-use paragraph, but might

270

281

be for formatting as a footnote).

271

282

283

=item C<=encoding I<encodingname>>

284

X<=encoding> X<encoding>

285

286

This command is used for declaring the encoding of a document. Most

287

users won't need this; but if your encoding isn't US-ASCII or Latin-1,

288

then put a C<=encoding I<encodingname>> command early in the document so

289

that pod formatters will know how to decode the document. For

290

I<encodingname>, use a name recognized by the L<Encode::Supported>

291

module. Examples:

292

293

=encoding utf8

294

295

=encoding koi8-r

296

297

=encoding ShiftJIS

298

299

=encoding big5

300

272

301

=back

273

302

274

And don't forget, when using any command, that the command lasts up

303

C<=encoding> affects the whole document, and must occur only once.

304

305

And don't forget, when using any other command, that the command lasts up

275

306

until the end of its I<paragraph>, not its line. So in the

276

307

examples below, you can see that every command needs the blank

277

308

line after it, to end its paragraph.

304

335

305

336

306

337

=head2 Formatting Codes

338

X<POD, formatting code> X<formatting code>

339

X<POD, interior sequence> X<interior sequence>

307

340

308

341

In ordinary paragraphs and in some command paragraphs, various

309

342

formatting codes (a.k.a. "interior sequences") can be used:

315

348

=over

316

349

317

350

=item C<IE<lt>textE<gt>> -- italic text

351

X<I> X<< IZ<><> >> X<POD, formatting code, italic> X<italic>

318

352

319

353

Used for emphasis ("C<be IE<lt>careful!E<gt>>") and parameters

320

354

("C<redo IE<lt>LABELE<gt>>")

321

355

322

356

=item C<BE<lt>textE<gt>> -- bold text

357

X<B> X<< BZ<><> >> X<POD, formatting code, bold> X<bold>

323

358

324

359

Used for switches ("C<perl's BE<lt>-nE<gt> switch>"), programs

325

360

("C<some systems provide a BE<lt>chfnE<gt> for that>"),

327

362

("C<and that feature is known as BE<lt>autovivificationE<gt>>").

328

363

329

364

=item C<CE<lt>codeE<gt>> -- code text

365

X<C> X<< CZ<><> >> X<POD, formatting code, code> X<code>

330

366

331

367

Renders code in a typewriter font, or gives some other indication that

332

368

this represents program text ("C<CE<lt>gmtime($^T)E<gt>>") or some other

333

369

form of computerese ("C<CE<lt>drwxr-xr-xE<gt>>").

334

370

335

371

=item C<LE<lt>nameE<gt>> -- a hyperlink

372

X<L> X<< LZ<><> >> X<POD, formatting code, hyperlink> X<hyperlink>

336

373

337

374

There are various syntaxes, listed below. In the syntaxes given,

338

375

C<text>, C<name>, and C<section> cannot contain the characters

389

426

C<LE<lt>text|name/"sec"E<gt>> or C<LE<lt>text|name/secE<gt>>

390

427

391

428

Link this text to that section in that manual page. E.g.,

392

C<LE<lt>SWITCH statements|perlsyn/"Basic BLOCKs and Switch

393

Statements"E<gt>>

429

C<LE<lt>postfix "if"|perlsyn/"Statement Modifiers"E<gt>>

394

430

395

431

=item *

396

432

418

454

=back

419

455

420

456

=item C<EE<lt>escapeE<gt>> -- a character escape

457

X<E> X<< EZ<><> >> X<POD, formatting code, escape> X<escape>

421

458

422

459

Very similar to HTML/XML C<&I<foo>;> "entity references":

423

460

470

507

=back

471

508

472

509

=item C<FE<lt>filenameE<gt>> -- used for filenames

510

X<F> X<< FZ<><> >> X<POD, formatting code, filename> X<filename>

473

511

474

512

Typically displayed in italics. Example: "C<FE<lt>.cshrcE<gt>>"

475

513

476

514

=item C<SE<lt>textE<gt>> -- text contains non-breaking spaces

515

X<S> X<< SZ<><> >> X<POD, formatting code, non-breaking space>

516

X<non-breaking space>

477

517

478

518

This means that the words in I<text> should not be broken

479

519

across lines. Example: S<C<SE<lt>$x ? $y : $zE<gt>>>.

480

520

481

521

=item C<XE<lt>topic nameE<gt>> -- an index entry

522

X<X> X<< XZ<><> >> X<POD, formatting code, index entry> X<index entry>

482

523

483

524

This is ignored by most formatters, but some may use it for building

484

525

indexes. It always renders as empty-string.

485

526

Example: C<XE<lt>absolutizing relative URLsE<gt>>

486

527

487

528

=item C<ZE<lt>E<gt>> -- a null (zero-effect) formatting code

529

X<Z> X<< ZZ<><> >> X<POD, formatting code, null> X<null>

488

530

489

531

This is rarely used. It's one way to get around using an

490

532

EE<lt>...E<gt> code sometimes. For example, instead of

521

563

whitespace right after the opening delimiter and whitespace right

522

564

before the closing delimiter!> For example, the following will

523

565

do the trick:

566

X<POD, formatting code, escaping with multiple brackets>

524

567

525

568

C<< $a <=> $b >>

526

569

530

573

'<' of the opening delimiter, and immediately precedes the first '>'

531

574

of the closing delimiter. (The whitespace is ignored.) So the

532

575

following will also work:

576

X<POD, formatting code, escaping with multiple brackets>

533

577

534

578

C<<< $a <=> $b >>>

535

579

C<<<< $a <=> $b >>>>

552

596

which is presumably easier to read than the old way:

553

597

554

598

C<open(X, "E<gt>E<gt>thing.dat") || die $!>

555

C<$foo-E<gt>bar(); >>

599

C<$foo-E<gt>bar();>

556

600

557

601

This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),

558

602

and any other pod2xxx or Pod::Xxxx translators that use

559

603

Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.

560

604

561

605

=head2 The Intent

606

X<POD, intent of>

562

607

563

608

The intent is simplicity of use, not power of expression. Paragraphs

564

609

look like paragraphs (block format), so that they stand out

578

623

579

624

580

625

=head2 Embedding Pods in Perl Modules

626

X<POD, embedding>

581

627

582

628

You can embed Pod documentation in your Perl modules and scripts.

583

629

Start your documentation with an empty line, a "=head1" command at the

601

647

=over

602

648

603

649

=item *

650

X<podchecker> X<POD, validating>

604

651

605

652

The B<podchecker> command is provided for checking Pod syntax for errors

606

653

and warnings. For example, it checks for completely blank lines in

Older »