343 lines
6.0 KiB
HTML
343 lines
6.0 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Entities (shortcuts,
|
|
text macros and re-usable text)</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
|
|
REL="HOME"
|
|
TITLE="LDP Author Guide"
|
|
HREF="index.html"><LINK
|
|
REL="UP"
|
|
TITLE="DocBook: Sample Markup"
|
|
HREF="using-docbook.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="Bibliographies"
|
|
HREF="doc-bib.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="Customizing your HTML files"
|
|
HREF="namedfiles.html"></HEAD
|
|
><BODY
|
|
CLASS="section"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>LDP Author Guide</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="doc-bib.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
>Appendix D. DocBook: Sample Markup</TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="namedfiles.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H1
|
|
CLASS="section"
|
|
><A
|
|
NAME="tools-entities"
|
|
></A
|
|
>D.8. Entities (shortcuts,
|
|
text macros and re-usable text)</H1
|
|
><P
|
|
> There may be some segments of text, or markup
|
|
that you want to use over and over again. Instead
|
|
of typing it up multiple times (and then having
|
|
to edit it multiple times if you want to make
|
|
a change) you can use <I
|
|
CLASS="glossterm"
|
|
>external
|
|
entities</I
|
|
>. Entities can give you a short
|
|
cut to:
|
|
re-using whole documents, text snippets, and
|
|
special markup. Some common ways to use an
|
|
entity would be for:
|
|
</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>text macros
|
|
for markup. </B
|
|
>An example would be a company
|
|
URL. By using a parameter entity you
|
|
could refer simply to &my-company-url;
|
|
instead of typing out the full <ulink
|
|
url="http://foo.bar">Foo.bar</ulink>
|
|
each time. </P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>software
|
|
license. </B
|
|
>Such as the GNU Free
|
|
Documentation License: it is long. And must
|
|
be included in full in each document. By
|
|
leaving the license in a separate file you can
|
|
easily include it in many documents without
|
|
having to redo the markup each time. </P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
>repeated
|
|
text. </B
|
|
>For instance an introduction to a
|
|
topic which is included both as a summary in
|
|
one section and as an introduction to the full
|
|
information in another. Saves on editing time if
|
|
you need to make changes to both sets of text.
|
|
</P
|
|
></DIV
|
|
></LI
|
|
></UL
|
|
><DIV
|
|
CLASS="example"
|
|
><A
|
|
NAME="ex-entities"
|
|
></A
|
|
><P
|
|
><B
|
|
>Example D-12. Adding
|
|
Entities</B
|
|
></P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> <?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
|
<-- I can add comments here -->
|
|
<!ENTITY shortcut "Replace 'shortcut' with this text.">
|
|
|
|
<!ENTITY sc-to-a-file SYSTEM "anotherfile.xml">
|
|
<-- note: the square bracket on the third line is closed on the next
|
|
line--> ]>
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><P
|
|
> To use these entities simply insert the name
|
|
you gave the entity between a <SPAN
|
|
CLASS="QUOTE"
|
|
>"&"</SPAN
|
|
> (ampersand) and a <SPAN
|
|
CLASS="QUOTE"
|
|
>";"</SPAN
|
|
> (semicolon). For
|
|
example: <SPAN
|
|
CLASS="QUOTE"
|
|
>"&shortcut;"</SPAN
|
|
> would expand into <SPAN
|
|
CLASS="QUOTE"
|
|
>"Replace
|
|
'shortcut' with this text"</SPAN
|
|
>; <SPAN
|
|
CLASS="QUOTE"
|
|
>"&sc-to-a-file;"</SPAN
|
|
>
|
|
would include the full contents of whatever
|
|
is in <TT
|
|
CLASS="replaceable"
|
|
><I
|
|
>anotherfile.xml</I
|
|
></TT
|
|
>.
|
|
</P
|
|
><P
|
|
>An important feature while writing a text is the ability to
|
|
check whether or not it will be presented in the final draft. It is
|
|
common to have several parts of the text marked as draft,
|
|
especially when updating an already existing document.</P
|
|
><P
|
|
>With the use of parameter entities, you can include or
|
|
eliminate these drafts by altering only one line at the beginning
|
|
of a document.</P
|
|
><DIV
|
|
CLASS="example"
|
|
><A
|
|
NAME="ex-entity-parameters"
|
|
></A
|
|
><P
|
|
><B
|
|
>Example D-13. Use of parameter entities</B
|
|
></P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
> <TT
|
|
CLASS="sgmltag"
|
|
><!ENTITY % review "INCLUDE"></TT
|
|
> ...
|
|
<TT
|
|
CLASS="sgmltag"
|
|
><![%review;[ <para>This paragraph will
|
|
be included on the draft when the entity "review" is defined with the
|
|
value "INCLUDE". </para> ]]></TT
|
|
>
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><P
|
|
>The entity <TT
|
|
CLASS="literal"
|
|
>review</TT
|
|
> might have several texts
|
|
defined, as in <A
|
|
HREF="tools-entities.html#ex-entity-parameters"
|
|
>Example D-13</A
|
|
>. When the
|
|
changes to the text are considered final, you need only to remove
|
|
parts of the text between the 3<SUP
|
|
>rd.</SUP
|
|
>
|
|
and 6<SUP
|
|
>th.</SUP
|
|
> lines.</P
|
|
><P
|
|
>To keep the draft definitions and hide the text in the
|
|
final draft, just alter the specification of the entity from
|
|
<TT
|
|
CLASS="literal"
|
|
>INCLUDE</TT
|
|
> to <TT
|
|
CLASS="literal"
|
|
>IGNORE</TT
|
|
>.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="doc-bib.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="index.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="namedfiles.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>Bibliographies</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="using-docbook.html"
|
|
ACCESSKEY="U"
|
|
>Up</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>Customizing your HTML files</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |