9 Managing documents #
This section provides an overview over features of XML you can use to manage documents.
9.1 Remarks #
Use remarks for editorial comments. Remarks can be placed within, before, or after a para but must always be within a section element. When creating output, remarks can be made visible in the output and thus help within the editorial process. When creating the final output, deactivate remarks.
Start remarks with your user name and the current date, then add a colon
(:
) and finally your actual remark. To comment on
someone else's remark, add a new remark directly below it. Delete remarks
when the corresponding issue is resolved.
<remark>tux (2013-10-13): could not find the option for foo</remark> <remark>geeko (2013-11-02): see /usr/share/doc/foo.html</remark>
You can add a role
attribute with one of the
following values to show the type of the remark:
structure
. Use this type of remark to suggest changes to the text or XML structure.language
. Use this type of remark to suggest language improvements.needinfo
. Use this type of remark to mark sections where you need input from others, such as developers.trans
. Use this type of remark to give hints to translators.
9.2 XML comments #
XML comments can be used for temporarily disabling portions of text. Another use of XML comments is to create more permanent internal comments or to mark up changes made for layout reasons. XML comments are never visible in a publication.
<!-- This is an XML comment. -->
For information about formatting XML comments, see Chapter 10, Formatting XML.
9.3 Entities #
Entities are used to expand text. There are several situations in which they can be used:
To represent special characters that cannot easily be displayed, entered or memorized.
To integrate external files using entities representing references to their file names.
To repeat content easily.
When an entity is defined, it can be used in many places. Entities increase consistency, as they only need to be defined once and will automatically be expanded everywhere within the document.
9.3.1 Common types of entities #
Official generic entities are maintained in the
Doc Kit
repository. They include SUSE product names and other terms
that are valid for every repository. In repositories configured with
Doc Kit, the file generic-entities.ent
therefore
must not be changed (any changes will be overwritten by the next Doc
Kit run). If there is a need to declare a specific entity that applies
to the current repository only, this can be done in the
product-entities.ent
or
entity-decl.ent
file in the respective repository.
A generic-entities.ent
or
entity-decl.ent
file contains several categories
of entities:
- Products
All SUSE product names and other products and applications. This helps when sudden name changes are necessary and avoids misspellings.
- Platforms
Use entities for all hardware architectures referenced. This helps when sudden name changes are necessary.
- Books
Title entities for all SUSE books. This helps when sudden name changes are necessary.
- General Entities
Network IP addresses, host names and user names.
There are several guidelines to consider when working with product entities for SUSE documentation:
- Entity selection
Use the entity name
&productname;
to identify the product for which the documentation is built. Set the value of this entity once per release and have it expand to the name of the current product:&productname; includes 389-ds.
If you need to reference a specific subproduct or a different product, use a more specific entity:
Tuning &sle; for SAP
- Acronyms
In some cases (for example, limited space in table cells or in titles), it is acceptable to use an entity for a product name acronym. Find the approved entities for product name acronyms in the entity declaration files, such as
product-entities.ent
orgeneric-entities.ent
. For a product name acronym, you can use the generic entity&productnameshort;
. If you need acronym entities for specific products, they usually have an appendeda
at the end, for example,&slsa;
for the acronym “SLES.”- Trademarks
Follow the rules under Section 6.21, “Trademarks” and Section 7.17, “Products”.
If an entity is placed at the beginning of a phrase or title, its
resolved form is usually lowercase (unless specified in uppercase, for
example, for product names). To have it capitalized, use the
<phrase role="style:sentencecase"/>
element.
For example:
<phrase role="style:sentencecase">&ulp;
</phrase>
The entity &ulp;
expands into “User
space live patching”.
Never add this tag to the content within
<command/>
and
<systemitem/>
elements. Capitalizing anything
inside these elements makes the content ambiguous.
9.3.2 Using entity files #
SUSE uses a set of custom entities. Find these entities in the
*.ent
files in each documentation repository. One
entity file can include other entity files.
Entity files are only used for original, English-language documents. Translated documents contain only the resolved form of entities, that is, plain-text directly in the document.
If you need a new entity to be used generically across all repositories, open a pull request against
generic-entities.ent
in the Doc Kit repository. After the change is approved by the Doc Kit maintainers, the entity update forgeneric-entities.ent
will be rolled out to all Doc Kit-based repositories with the next Doc Kit run. If you need a custom entity that only applies to a specific repository, define it inproduct-entities.ent
or inentities-decl.ent
in this specific repository.Do not include custom entity definitions directly in the file header, unless the custom definitions are needed to override externally embedded entities.
Use the UTF-8 encoding when editing and saving the entity declaration file or any of the SUSE XML files.
Each header of a SUSE XML file includes the entity declaration file (by means of an entity):
<!ENTITY % entities SYSTEM "generic-entities.ent"> %entities;
product-entities.ent
#<!ENTITY1product-sp2 "13"> <!ENTITY product-ga "15"> <!ENTITY productnumber-regurl "&product-ga;.&product-sp;4"> <!ENTITY productnumber "<phrase xmlns='http://docbook.org/ns/docbook' role='productnumber'>15</phrase">5">
Making an entity declaration. | |
Defining the entity name. | |
Setting the value which the processed entity should expand to. | |
Using another entity within the entity value. This entity reference is only valid if the other entity is defined somewhere within the scope of the XML document that is built. However, it does not matter whether the entity is defined before or after the current entity definition. | |
Using a DocBook/GeekoDoc element within the entity value. The
attribute |
9.4 XInclude elements #
XInclude elements are used to create modular source files that are easier to work with and can be reused. When editing a book, create a new source file for every chapter. Later, create a new GeekoDoc file that can serve as the central point. In this file, use XInclude elements to reference all chapters in the correct order:
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="gfdl.xml"/>
XInclude elements allow adding common sections to multiple books or articles without having to maintain the text in multiple places. Common sections include licenses and information on typographical conventions. XIncludes also simplify co-editing documentation with others in a version control system as they reduce the chance of merge conflicts.
By default, files referenced via XIncludes must be well-formed XML files
that are also valid GeekoDoc fragments. This means that they must have a
single top-level element and must not contain elements that are not
allowed in GeekoDoc. Files that are supposed to be referenced multiple
times from within the same set, book or article must not contain any
xml:id
attributes.
XIncludes also allow embedding plaintext files, for example, as the
content in <screen/>
elements. To embed a
plaintext file, add the attribute
parse="text"
to the
<xi:include/>
element.