Claus chr: Corrected links

2012-09-09T10:40:07Z

Corrected links

Claus chr at 08:31, 2 September 2012

2012-09-02T08:31:52Z

Claus chr at 09:09, 1 September 2012

2012-09-01T09:09:18Z

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

Annew: Marked this version for translation

2011-11-30T15:50:51Z

Marked this version for translation

New page

<translate>

=== Making Callouts === 


:Callouts are difficult, so they have their own chapter. Use callouts when you want to refer from text to specific parts of an image, programlisting, or synopsis. Using callouts with graphics is currently unused, and is somewhat problematic, so they will not (yet) be described here.


{{Tag|calloutlist}}
</translate><translate>


:A list element that contains the callouts themselves. That is, a list of the explanations that belong to the indicated areas in the item being explained.


{{Tag|1=callout arearefs=""}}
</translate><translate>


:The actual explanation or description of the called out area or line. The <tt>arearefs</tt> attribute should contain the id of the appropriate callout you are referring to.


{{Tag|programlistingco}} and {{Tag|screenco}}
</translate><translate>
</translate><translate>


:Callouts applied to a programlisting or a screen element. Although they look more difficult than just embedding the callouts directly in the text, they really aren't too hard. The programlistingco contains one areaspec, and one programlisting. The screenco contains one areaspec and one screen element. The programlisting and screen elements are exactly as you would normally have.


:{{Tag|areaspec}}
</translate><translate>


::The areaspec contains a list of area elements, each of which describes one single callout.


:{{Tag|1=area coords="" id=""/}}
</translate><translate>


::The area is another of the very few empty elements, so there is no {{Tag|/area}}. The <tt>id</tt> attribute should contain a unique name for the item. The <tt>coords</tt> contains a pair of numbers which indicate first the line and then the column where the co should appear. The line and column refer to the position in relation to the container element, ''not the entire document!''. That is, in a screenco, the line and column numbers refer to the line ''within the'' <tt>screen</tt> ''element''.


:'''Example: Marking up callouts with {{Tag|screenco}}'''


:{{Input|1=<nowiki>
<screenco>
<areaspec>
<area coords="2 65" id="currentdir"/>
<area coords="3 65" id="updir"/>
<area coords="4 75" id="hiddenfile"/>
<area coords="10 75" id="backupfile"/>
<area coords="13 70" id="hiddendir"/>


<screen>
total 864
drwx------ 8 vampyr vampyr 4096 Oct 2 18:01 ./
drwxr-xr-x 13 root root 4096 Oct 1 16:32 ../
-rw------- 1 vampyr vampyr 32 Sep 2 14:21 .MCOP-random-seed
-rw------- 1 vampyr vampyr 0 Sep 2 14:42 .Xauthority
-rw-r--r-- 1 vampyr vampyr 1899 Aug 6 19:32 .Xdefaults
-rw------- 1 vampyr vampyr 261 Sep 29 22:59 .bash_history
-rw-r--r-- 1 vampyr vampyr 24 Aug 6 19:32 .bash_logout
-rw-r--r-- 1 vampyr vampyr 285 Aug 6 19:34 .bash_profile
-rw-r--r-- 1 root root 230 Aug 6 19:32 .bash_profile~
-rw-r--r-- 1 vampyr vampyr 559 Aug 6 19:32 .bashrc
-rw-r--r-- 1 vampyr vampyr 4044 Aug 6 19:32 .emacs
drwxr-xr-x 7 vampyr vampyr 4096 Sep 29 17:31 .kde/
</screen>
</screenco>
<calloutlist>
<callout arearefs="currentdir1"><para>The current folder.</para>
</callout>
<callout arearefs="updir1">
<para>One folder up in the tree.</para>
</callout>
<callout arearefs="hiddenfile1">
<para>A hidden file, indicated by the . beginning the name.</para>
</callout>
<callout arearefs="backupfile1">
<para>A backup or temporary file, indicated by the ~ ending the name.</para>
</callout>
<callout arearefs="hiddendir1">
<para>A hidden folder, which, like a hidden file, is indicated by the . at
the start of the name.</para>
</callout>
</calloutlist>
</nowiki>}}


:All this markup above, while it looks complicated is really quite simple if you study it closely. It would generate the following:


:{{output|1=<nowiki>
total 864
drwx------ 8 vampyr vampyr 4096 Oct 2 18:01 ./
drwxr-xr-x 13 root root 4096 Oct 1 16:32 ../
-rw------- 1 vampyr vampyr 32 Sep 2 14:21 .MCOP-random-seed
-rw------- 1 vampyr vampyr 0 Sep 2 14:42 .Xauthority
-rw-r--r-- 1 vampyr vampyr 1899 Aug 6 19:32 .Xdefaults
-rw------- 1 vampyr vampyr 261 Sep 29 22:59 .bash_history
-rw-r--r-- 1 vampyr vampyr 24 Aug 6 19:32 .bash_logout
-rw-r--r-- 1 vampyr vampyr 285 Aug 6 19:34 .bash_profile
-rw-r--r-- 1 root root 230 Aug 6 19:32 .bash_profile~
-rw-r--r-- 1 vampyr vampyr 559 Aug 6 19:32 .bashrc
-rw-r--r-- 1 vampyr vampyr 4044 Aug 6 19:32 .emacs
drwxr-xr-x 7 vampyr vampyr 4096 Sep 29 17:31 .kde/
</nowiki>}}


:❶ The current folder. 
:❷ One folder up in the tree. 
:❸ A hidden file, indicated by the . beginning the name. 
:❹ A backup or temporary file, indicated by the ~ ending the name. 
:❺ A hidden folder, which, like a hidden file, is indicated by the . at the start of the name.


{{Tag|co}}
</translate><translate>


:Indicates where a callout is. For KDE HTML documentation, a small numbered graphic will be placed here, and also at the location of the explanation. These numbered graphics are links between the two places. It is entirely possible to embed the callout elements directly in the text you are describing, and this is perhaps the easiest way to do it. It isn't the most specific, but working out the line coordinates to use the more precise elements is difficult, so this way is acceptable for now.


'''Example: Marking up callouts by embedding directly in text'''


:{{Input|1=<nowiki>
<screen>
drwxr-xr-x 3 vampyr vampyr 4096 Aug 6 19:32 .kde2/
lrwxrwxrwx 1 vampyr vampyr 15 Sep 3 19:46
.kdeinit-whiterabbit.magicians.org-:0 -> /tmp/.kinV4m2iI= <co id="symlink"/>
-rw-r--r-- 1 vampyr vampyr 2096 Aug 6 19:32 .kderc
-r-------- 1 vampyr vampyr 21 Sep 2 14:21 .kxmlrpcd
-rw-r--r-- 1 vampyr vampyr 185 Aug 6 19:32 .mailcap
-rw------- 1 vampyr vampyr 31 Sep 2 14:21 .mcoprc
drwxr-xr-x 4 vampyr vampyr 4096 Aug 6 19:32 .netscape/
-rw------- 1 vampyr vampyr 777947 Sep 2 14:42 .xsession-errors
drwxr-xr-x 5 vampyr vampyr 4096 Sep 2 14:42 Desktop/ <co id="dir"/>
drwx------ 2 vampyr vampyr 4096 Aug 6 19:32 tmp/
-rw-r--r-- 1 vampyr vampyr 3836 Oct 13 16:44 notes.txt <co id="file"/>
</screen>


<calloutlist>
<callout arearefs="symlink">
<para>A symbolic link, indicated by the ->, and showing the location it is
linked to.</para>
</callout>
<callout arearefs="dir">
<para>An ordinary folder.</para>
</callout>
<callout arearefs="file">
<para>An ordinary file.</para>
</callout>
</calloutlist>
</nowiki>}}


:Again it's really not as hard as it looks on first glance. This markup would generate the following:


:{{Output|1=<nowiki>
drwxr-xr-x 3 vampyr vampyr 4096 Aug 6 19:32 .kde2/
lrwxrwxrwx 1 vampyr vampyr 15 Sep 3 19:46
.kdeinit-whiterabbit.magicians.org-:0 -> /tmp/.kinV4m2iI= ❶
-rw-r--r-- 1 vampyr vampyr 2096 Aug 6 19:32 .kderc
-r-------- 1 vampyr vampyr 21 Sep 2 14:21 .kxmlrpcd
-rw-r--r-- 1 vampyr vampyr 185 Aug 6 19:32 .mailcap
-rw------- 1 vampyr vampyr 31 Sep 2 14:21 .mcoprc
drwxr-xr-x 4 vampyr vampyr 4096 Aug 6 19:32 .netscape/
-rw------- 1 vampyr vampyr 777947 Sep 2 14:42 .xsession-errors
drwxr-xr-x 5 vampyr vampyr 4096 Sep 2 14:42 Desktop/ ❷
drwx------ 2 vampyr vampyr 4096 Aug 6 19:32 tmp/
-rw-r--r-- 1 vampyr vampyr 3836 Oct 13 16:44 notes.txt ❸
</nowiki>}}


:❶ A symbolic link, indicated by the ->, and showing the location it is linked to. 
:❷ An ordinary folder. 
:❸ An ordinary file.


{{Tag|imageobjectco}}
</translate><translate>


:Currently unused in KDE Documentation.


{{Tag|mediaobjectco}}


:Currently unused in KDE Documentation.


{{Tag|areaset}}
</translate><translate>


:Currently unused in KDE Documentation. This and the above two elements will be used eventually (just as soon as I figure out how they work).


{{Tag|graphicco}}
</translate><translate>


:Not to be used in KDE Documentation at all.


{{Prevnext2
| prevpage=Documentation Primer/Manual/DocBook Reference/Programming
| prevtext=Markup for programming
| nextpage=Documentation Primer/Manual/DocBook Reference/Reference
| nexttext=References, indexes, and glossaries
| index=Documentation Primer/Manual
| indextext=Back to Menu
}}

</translate>

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

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

@@ Line 215: / Line 215: @@
 <!--T:35-->
 {{Prevnext2
-| prevpage=Documentation Primer/Manual/DocBook Reference/Programming
+| prevpage=Special:myLanguage/Documentation Primer/Manual/DocBook Reference/Programming
 | prevtext=Markup for programming
-| nextpage=Documentation Primer/Manual/DocBook Reference/Reference
+| nextpage=Special:myLanguage/Documentation Primer/Manual/DocBook Reference/Reference
 | nexttext=References, indexes, and glossaries
-| index=Documentation Primer/Manual
+| index=Special:myLanguage/Documentation Primer/Manual
 | indextext=Back to Menu
 }}
 </translate>

Documentation Primer/Manual/DocBook Reference/Callouts - Revision history

Claus chr: Corrected links

Claus chr at 08:31, 2 September 2012

Claus chr at 09:09, 1 September 2012

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

Annew: Marked this version for translation