Documentation Primer/Manual/DocBook - Revision history

Claus chr: Corrected link

2012-09-09T10:08:20Z

Corrected link

Claus chr: Corrected links

2012-09-09T09:46:04Z

Corrected links

Claus chr at 08:27, 2 September 2012

2012-09-02T08:27:10Z

Claus chr at 09:02, 1 September 2012

2012-09-01T09:02:43Z

Claus chr: 1 revision: Moving Docbook Primer from UserBase to TechBase

2012-09-01T08:47:32Z

1 revision: Moving Docbook Primer from UserBase to TechBase

Claus chr: /* Necessary Sections */

2011-11-30T05:50:50Z

‎Necessary Sections

New page

<languages />
<translate>

== DocBook Introduction == 


All KDE documentation is produced in DocBook XML format, and writers are encouraged to learn it (although it's by no means necessary, and we're very happy to receive documentation written in plain text). Although DocBook can look somewhat intimidating to beginners, the markup is extremely self-descriptive, and many people find it easier than HTML to learn.


In this chapter, we'll just take a basic overview of the ideas behind DocBook. For detailed information about individual tags and so on, please see [[Documentation Primer/Manual/DocBook Reference|Appendix A. DocBook Reference]].

</translate><translate>

=== Overview === 


DocBook is just an application of XML, so if you're familiar with XML, then you'll feel right at home. If not, don't worry, as most of the gory details aren't required knowledge for simply writing and updating documentation. A DocBook file (and, indeed, any XML file) consists of plain text, with tags surrounding some text to tell you (or a computer) what that text represents. So, a snippet from a DocBook file might look like:
</translate>
<translate>


{{Input|1=<nowiki><para>To display the clipboard history, click on the &klipper; icon
in the &kde; panel, or press <keycombo
action="simul">&Ctrl;&Alt;<keycap>V</keycap></keycombo>. Previous
clipboard entries are shown
at the top of the popup menu which
appears.<para></nowiki>}}


The <code><nowiki><para></nowiki></code> and <code><nowiki></para></nowiki></code> show the start and end, respectively, of a paragraph. These delimiting marks are called "tags", and the content they contain (along with the tags) is called an "element". The <code><nowiki><keycombo></nowiki></code> tag has an extra piece of information specified: <code><nowiki>action="simul"</nowiki></code>. This is called an "attribute," and makes the tag more specific. The words surrounded by & and ; are "entities". They are simply variables that expand to some other text, and are widely used in KDE documentation. See [[#KDE Specialities]] for more information about entities. Tags, entities, comments and other parts of XML that aren't simple text are referred to as "markup."

</translate><translate>

=== Content and Presentation === 


One of the basic principles behind the use of DocBook in KDE is that content and presentation are strictly separated. DocBook files contain the content, and XSL files contain the information about presentation. This has a number of advantages, some of which are:


* When writing, you don't have to worry about whether the information is well presented, just that the information you're writing is correct and readable.


* All KDE documentation has a similar look, so once readers are familiar with conventions in one document, They are familiar with all documents.


* Documentation is future-proofed, since by providing as much information about content as possible, future formats, search engines, etc. are likely to be catered for easily.


In practice, this means that you should add markup that describes what things ''are'' and not how they should appear. So, in the example above, the <code><nowiki><keycombo></nowiki></code> (a keyboard shortcut) tells the reader (or computer) that the keys <keycap>Ctrl</keycap>, <keycap>Alt</keycap> and <keycap>V</keycap> should be pressed simultaneously, but doesn't say anything about how that should be displayed in the final output. (In fact, it appears as "<keycap>Ctrl + Alt + V</keycap>", but it
could equally be converted to "C-M-V" à la '''Emacs''' or even some other way of showing keyboard shortcuts. What's important is that the DocBook source has the "information" necessary to work out what is being referred to.)

</translate>



<translate>

</translate><translate>

=== KDE Specialities === 


KDE-isms: entities, necessary bits (credits, translation stuff)

==== Entities ==== 


Entities (which are simply variables which expand to some other text) are an important part of DocBook markup, and are used particularly widely in KDE documentation. For example, there are entities defined for almost all KDE applications. Therefore, when referring to, for example, '''Konqueror in documentation, you should use:


{{Input|1=<nowiki>&konqueror; is, among other things, a
web browser.</nowiki>}}


This has several advantages. Firstly, it ensures that applications are capitalized and marked-up consistently across all KDE documentation. This means that you don't have to remember whether the
help center program is KHelpCenter, KHelpcenter or Khelpcenter: the entity (which is always entirely lowercase) automatically expands to the correct one.
</translate>


<translate>


There are entities defined for several classes of names:


;All KDE applications
:As mentioned before, all KDE applications have an entity. The entity name is in entirely lowercase, and expands to the correctly capitalized version of the application name. There is also an entity for KDE itself: <code>&kde;</code>.


;Common English and technology abbreviations :For example, "i.e." is written as <code>&ie;</code> and "e.g." as <code>&eg;</code>. This ensures that the same markup and capitalization are used for these abbreviations throughout KDE documentation. Technological abbreviations such as HTTP and XML also have entities, which are capitalized as usual (i.e., <code>&HTTP;</code> and <code>&XML;</code> for the previous examples).


;Trademarks
:Names of companies and their products are often trademarked. For this reason, it is important to mark them up with the <code>trademark</code> tag, using the <code>class="registered"</code> attribute if necessary. To reduce effort, and ensure that trademarks are given proper acknowledgment, many common technology-related trademarks have been given entities. For example, the entity <code>&X-Window;</code> expands to X Window System®.


;Contributor Names
:Names of contributors to KDE documentation have entities of the form <code>&Firstname.Lastname</code> (or <code>&Firstname.Initial.Lastname</code>). Email addresses of contributors have entities of the form <code>&Firstname.Lastname.mail</code>.


;Names of special keys
:Names of keys on the keyboard are always marked up with either <code>keycap</code> or <code>keysym</code>. Since it can be difficult to distinguish between these two tags, entities have been created for common keys, e.g., <code>&Ctrl;</code> and <code>&Alt;</code>.


The definitions of these entities can be found in the following locations in KDE:


;Items not requiring translation (KDE application names, technology abbreviations, trademarks
:<tt>kdelibs/kdoctools/customization/entities/general.entities</tt>


;Contributor names and email addresses
:<tt>kdelibs/kdoctools/customization/entities/contributor.entities</tt>


;Language-specific terms and key names
:<tt>kdelibs/kdoctools/customization/en/user.entities</tt>

==== Necessary Sections ==== 


There are several sections that appear in all KDE DocBook files, even though they are not required by DocBook itself:


* {{Input|1=<nowiki><!ENTITY package "kde-module">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE"></nowiki>}} This appears in the prologue immediately after the FPI. See [[Documentation Primer/Manual/DocBook Reference#The Prologue|The Prologue]] for more details about this section.


* {{Input|1=<nowiki></nowiki>}} This appears after the <code>authorgroup</code> element, and is a required placeholder for use in translation (also known as "i18n" from the number of letters between the first and the last of the word "internationalization").


{{Prevnext2
| prevpage=Documentation_Primer/Manual/Writing
| prevtext=Writing Documentation: Procedures and Tools
| nextpage=Documentation_Primer/Manual/Publishing
| nexttext=Sending the New Documents and Changes to KDE
| index=Documentation_Primer/Manual
| indextext=Back to Menu
}}

</translate>

@@ Line 8: / Line 8: @@
 <!--T:3-->
-In this chapter, we'll just take a basic overview of the ideas behind DocBook. For detailed information about individual tags and so on, please see [[Documentation Primer/Manual/DocBook Reference|Appendix A. DocBook Reference]].
+In this chapter, we'll just take a basic overview of the ideas behind DocBook. For detailed information about individual tags and so on, please see [[Special:myLanguage/Documentation Primer/Manual/DocBook Reference|Appendix A. DocBook Reference]].
 </translate><span id="Overview"></span><translate>

← Older revision		Revision as of 08:27, 2 September 2012
Line 1:		Line 1:
	<languages />		<languages />
−	~~{{Transferring}}~~
	<translate>		<translate>

← Older revision		Revision as of 09:02, 1 September 2012
Line 1:		Line 1:
	<languages />		<languages />
		+	{{Transferring}}
	<translate>		<translate>

@@ Line 28: / Line 28: @@
 <!--T:7-->
-The <code><nowiki><para></nowiki></code> and <code><nowiki></para></nowiki></code> show the start and end, respectively, of a paragraph. These delimiting marks are called "tags", and the content they contain (along with the tags) is called an "element". The <code><nowiki><keycombo></nowiki></code> tag has an extra piece of information specified: <code><nowiki>action="simul"</nowiki></code>. This is called an "attribute," and makes the tag more specific. The words surrounded by & and ; are "entities". They are simply variables that expand to some other text, and are widely used in KDE documentation. See [[#KDE Specialities]] for more information about entities. Tags, entities, comments and other parts of XML that aren't simple text are referred to as "markup."
+The <code><nowiki><para></nowiki></code> and <code><nowiki></para></nowiki></code> show the start and end, respectively, of a paragraph. These delimiting marks are called "tags", and the content they contain (along with the tags) is called an "element". The <code><nowiki><keycombo></nowiki></code> tag has an extra piece of information specified: <code><nowiki>action="simul"</nowiki></code>. This is called an "attribute," and makes the tag more specific. The words surrounded by & and ; are "entities". They are simply variables that expand to some other text, and are widely used in KDE documentation. See [[Special:myLanguage/Documentation Primer/Manual/DocBook#KDE Specialities|KDE Specialities]] for more information about entities. Tags, entities, comments and other parts of XML that aren't simple text are referred to as "markup."
 </translate><span id="Content and Presentation"></span><translate>
@@ Line 132: / Line 132: @@
 * {{Input|1=<nowiki><!ENTITY package "kde-module">
 <!ENTITY % addindex "IGNORE">
-<!ENTITY % English "INCLUDE"></nowiki>}}<br /><br />This appears in the prologue immediately after the FPI. See [[Documentation Primer/Manual/DocBook Reference#The Prologue|The Prologue]] for more details about this section.
+<!ENTITY % English "INCLUDE"></nowiki>}}<br /><br />This appears in the prologue immediately after the FPI. See [[Special:myLanguage/Documentation Primer/Manual/DocBook Reference/Prologue|The Prologue]] for more details about this section.
 <!--T:33-->
@@ Line 139: / Line 139: @@
 <!--T:34-->
 {{Prevnext2
-| prevpage=Documentation_Primer/Manual/Writing
+| prevpage=Special:myLanguage/Documentation_Primer/Manual/Writing
 | prevtext=Writing Documentation: Procedures and Tools
-| nextpage=Documentation_Primer/Manual/Publishing
+| nextpage=Special:myLanguage/Documentation_Primer/Manual/Publishing
 | nexttext=Sending the New Documents and Changes to KDE
-| index=Documentation_Primer/Manual
+| index=Special:myLanguage/Documentation_Primer/Manual
 | indextext=Back to Menu
 }}
 </translate>