Claus chr: Corrected links

2012-09-09T10:06:36Z

Corrected links

Claus chr at 08:26, 2 September 2012

2012-09-02T08:26:52Z

Claus chr at 09:02, 1 September 2012

2012-09-01T09:02:27Z

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

2012-09-01T08:47:35Z

1 revision: Moving Docbook Primer from UserBase to TechBase

Yurchor: Marked this version for translation

2012-05-23T04:42:06Z

Marked this version for translation

New page

<languages />
<translate>

== Writing Documentation: Procedures and Tools == 


If you're worried about having to learn a lot of new tools and procedures in order to write documentation, you don't need to, because the information we've covered so far is everything you need to know to be able to contribute. Although we ''do'' have some tools we use and procedures we follow, it's not vital that everyone knows them in detail, especially when starting out.


For example, all KDE documentation is written in DocBook XML, but we're very happy to receive documentation written in plain text. There are people on the documentation team who are very familiar with DocBook, and can easily add the markup if the content is there.


Another example: if you are starting to document an application from scratch, you don't need to get the sources of the current documentation. But if you are starting from existing documentation, you don't need to know about how to get the sources, there are other means to do that.


Of course, if you want to learn about DocBook, you can. After a little practice, you will probably find that it's not as hard as it looks. And if you learn about dealing with a svn repository, you will be able to integrate yourself to the regular KDE development process (upload your changes, work together with other developers, etc.)

</translate><translate>

=== Getting the Documentation Sources === 


{{Note|1=If you are starting your document from scratch, you probably do not need to read this section, and may start working right now.}}


You are welcome to use plain text to contribute to KDE documentation. It is a great way to start, and we strongly encourage it. If you will miss the power of the DocBook format as you improve your documentation skills, then you can learn it. In the mean time, someone will manually edit the plain text to add the DocBook markup and commit it to KDE svn or git repository, removing the burden of doing most of the more complex stuff covered in this very guide. We'll take a look at writing in DocBook and using svn or git later in this document, so if you're interested, read on, but if you want to use plain text, you can go directly to [[#Working with plain text sources]].


Documentation for KDE, like the rest of the source code, is kept in a svn or git repository. svn and git provide a way for many developers to work on the same source code (or in our case, the same documentation), and has many useful features to help with this. For example, previous versions of every file are saved so that any mistakes can be quickly backed out, if they cannot be easily corrected.


The basic principle behind svn is simple: one server stores a definitive copy of the files making up a project. This is known as the ''repository''. Each developer can download the files to make their own private copy, named ''working copy'' or ''sandbox''. Using svn, the developers can upload their modifications to the main repository (a process called "committing") or update their own copy to reflect recent changes made by others.


There are two main ways edit the contents of a KDE document you want to improve: using plain text or DocBook.

</translate><translate>

==== Working with plain text sources ==== 


The [http://docs.kde.org/ docs.kde.org website] displays most of the KDE documentation in HTML format, updated weekly from the svn and git repositories. There are two versions available in the website: the [http://docs.kde.org/index.php?language=en&branch=stable stable version] and the [http://docs.kde.org/index.php?language=en&branch=development KDE development version]. You will always use the latest version of the documentation, i.e. the [http://docs.kde.org/index.php?language=en&branch=development KDE development version].


The [http://docs.kde.org/index.php?language=en&branch=development docs.kde.org website] presents a quick and easy method of retrieving the latest version of the KDE documentation. Clicking the name of the application you want to document in the list will open the documentation in your web browser. Simply copy the text from the website to your favorite text editor, edit it, and submit the results in plain text to the [mailto:kde-doc-english@kde.org KDE Documentation mailing list]. Please note that not all KDE applications are listed there. If you cannot find the documentation of the application you want to work with, then you can request it by sending a message to the KDE Documentation mailing list.</translate>

<translate>

==== Retrieving the DocBook sources ==== 
</translate><translate>


The latest DocBook sources are located inside the KDE repository. Now you need to find and retrieve them.


The software inside the KDE repository is divided into ''modules'', which are used to organize the different
software projects inside the repository. Modules are the top-level folders in the svn repository folder tree, and each one contains a group of related applications. These modules are sometimes released in binary
form as ''packages''. If you know the name of the package your application belongs to, you probably know the module name as well, as they are frequently the same. You need to know in which module your application is, to retrieve its DocBook sources. For instance, '''KMix''' is in the kdemultimedia module, '''Lokalize''' in the kdesdk module and so on. If you need any help in this process, don't hesitate to ask. Each module contains a folder named "doc", and inside it, you can find the DocBook sources.


To access the svn repository, you can use the kdesvn or browse the [http://websvn.kde.org KDE WebSVN website (websvn.kde.org)].


The [http://websvn.kde.org websvn.kde.org] is a web based representation of the contents of the svn repository. It is easy to download files using [http://websvn.kde.org websvn.kde.org], the operating system or desktop you use does not matter.


Retrieving your own working copy of the repository has many advantages. You will be able to use your working copy to create files containing the changes you made, to update your copy with changes made by other documenters, and if you get a KDE svn account, to upload your changes directly to the repository. But this is out of the scope of this section. Here we will show you simply how to retrieve the sources using svn the easiest way we can.
</translate><translate>


'''Retrieving documentation sources using WebSVN'''


# Go to [http://websvn.kde.org http://websvn.kde.org] using your favorite web browser. Let's suppose you are looking for '''Lokalize's''' documentation sources.</translate>
<translate>

# The KDE repository is divided into "trunk" (also known as HEAD, where development is going on, "branches", where both stable and working branches live, and "tags", where you can retrieve snapshots of sources at a release. Most work for documentation goes on in "trunk", so click there.</translate>
<translate>

# The main KDE modules are in the "KDE" folder, so click on that.</translate>
<translate>

# Click the "trunk" link to get the main branch listing. Click on "KDE" to get the list of modules from a KDE release.</translate>
<translate>

#'''Lokalize''' is part of the kdesdk module (KDE software development kit module). Therefore, click the "kdesdk" item on the list. The contents of the kdesdk module will be displayed.</translate>
<translate>

# Click the "doc" item on the list, to see the contents of the documentation folder of the module. The contents of the doc (documentation) folder will be displayed.</translate>
<translate>

# Select the application you want to work with from the list (in our case, "lokalize"). All '''Lokalize's''' documentation source files will be displayed, being images or DocBook files.</translate>
<translate>

# Now you reached the list of files that are part of '''Lokalize's''' documentation, including images and DocBook sources. The DocBook sources are files in the format <tt>*.docbook</tt>. In this case, there is only one file file in this format: <tt>index.docbook</tt>. Click this file on the list. A list of ''revisions'' (versions) of that file will be displayed.</translate>
<translate>

# Click the "download" link from the revision on the top of the list. It is the most recent one. Save the file. Repeat this process with all the files you want to download.


We use '''Lokalize's''' documentation sources as example in the following procedures.


'''Retrieving documentation sources using svn'''


# Check if you have the svn client installed (hint: enter <code>svn</code> in the terminal screen). If not, install the svn package using the tools provided by your distribution.</translate>
<translate>

# Now it is time to download, or ''checkout'' the sources. Using svn, type in the terminal:</translate> <translate>
{{Input|1=<nowiki>mkdir </nowiki>'''''path/to/working/folder'''''<nowiki>
cd </nowiki>'''''path/to/working/folder'''''<nowiki>
svn checkout svn://anonsvn.kde.org/home/kde/</nowiki>'''''trunk/KDE/module'''''/doc/'''''application'''''}}</translate> <translate>
where '''''path/to/working/folder''''' is the folder you want to install the sources in your system, '''''trunk/KDE/module''''' is the application's module location in the repository and '''''application''''' is the application name. Remember to use small caps to type the application and module names. In our example, '''Lokalize''' is in the kdesdk module, so you would enter:</translate> <translate>
{{Input|1=<nowiki>svn checkout svn://anonsvn.kde.org/home/kde/trunk/KDE/kdesdk/doc/lokalize</nowiki>}}


Note that only applications which are part of a regular KDE release are under '''''trunk/KDE/'''''. '''Amarok''' docs, for instance, is in the multimedia module of extragear. Extragear contains mature applications which are not part of a KDE release. To get '''KMyMoney''' docs, type in the terminal:
{{Input|1=<nowiki>svn checkout svn://anonsvn.kde.org/home/kde/trunk/extragear/office/doc/kmymoney</nowiki>}}

</translate><translate>

=== Kate === 


'''Kate''' is an extensible and powerful text editor which is part of the kdebase module. Kate can syntax highlight DocBook documents out of the box, and is generally a very powerful editor, but you can get even more XML specific functionality installing the XML plugin for '''Kate'''.


'''Installing the XML plugin for Kate'''


# The XML plugin for '''Kate is part of the kate module.</translate>
<translate>

# Open the '''Configure Kate''' dialog by choosing the <menuchoice>Settings -> Configure Kate...</menuchoice> menu item.</translate>
<translate>

# Select the <menuchoice>Plugins</menuchoice> item from the <menuchoice>Application</menuchoice> tree. Check the <menuchoice>XML Completion</menuchoice> and the <menuchoice>XML Validation</menuchoice> boxes. [[Image:Kate-plugin.png|thumb|350px|center|A screenshot of Kate's Plugin Manager Configure
Dialog]]</translate>
<translate>

# Press <menuchoice>OK</menuchoice>.


With the XML plugin for Kate installed, you will have autocompletion, autoclosing for DocBook tags and entities. Since KDE documentation uses entities widely, this is a very welcome feature. Additional XML tools will be available trough the <menuchoice>XML</menuchoice> menu (in special, trough the <menuchoice>Validate XML</menuchoice> menu item, which will allow you to check your DocBook documents). The output of this action will appear in the <menuchoice>XML Checker Output</menuchoice> button in the side bar located in the lower part of '''Kate's''' main window.


[[Image:Kate-validate-xml.png|thumb|350px|center|A screenshot of Kate's Main Window showing the XML Checker Output]]

</translate> <translate>

</translate><translate>

=== Emacs and Psgml === 


The venerable '''Emacs''' editor has a powerful SGML and XML editing mode called psgml. The price of this power is a steeper learning curve than the other editors, so if you haven't used '''Emacs''' before, you will probably want to try the other editors first. If, on the other hand, you're already familiar with
'''Emacs''', then psgml is your best choice.


Installation of psgml is beyond the scope of this document, but it should simply be a case of installing appropriate packages for your distribution. The relevant configuration for KDE-related documentation is simple. Just tell psgml where the KDE catalog files are located with the following line in your <tt>.emacs</tt> file:


{{Input|1=(setq sgml-catalog-files
(list "CATALOG" "'''''KDEDIR'''''/share/apps/ksgmltools2/customization/catalog"))}}


where you should replace '''''KDEDIR''''' with the path to your KDE installation. You might also want to use the following line to instruct '''Emacs''' to use psgml to open all <tt>.docbook</tt> files:


{{Input|1=(setq auto-mode-alist
(cons '("\\.docbook$" . sgml-mode) auto-mode-alist))}}


There are of course plenty of other settings in psgml mode which you can change to your taste: see the psgml <code>info</code> documentation for more details.
</translate><translate>


Some basic keystrokes in psgml are:


;<keycap>Ctrl + C /</keycap>
:End current element. This inserts an end tag for the currently open element.


;<keycap>Meta + Tab</keycap>
:Completes the current tag or entity, context-sensitively. This will only complete on tags that are allowed at the current point in the document. Note that, because indentation is rarely used in KDE documentation, it is generally safe to remap this function to just the <keycap>Tab</keycap> key.


;<keycap>Ctrl + C</keycap> <keycap>Ctrl + F</keycap> <keycap>Ctrl + E</keycap>
:Fold current element. This compresses the current element so that only the starting tag appears. One use of this is to fold all the <tt>chapter</tt> elements in a document, to get an overview of the document on one screen, and make navigation around a long document easier. You can unfold elements with the shortcut <keycap>Ctrl + C</keycap> <keycap>Ctrl + U</keycap> <keycap>Ctrl + E</keycap>


One particularly useful psgml feature that isn't well documented is the sgml-parent-document variable. Setting this variable appropriately tells psgml that this file is part of a larger document. This enables the full range of psgml features for this file, such as context-sensitive element completion. To use this feature, place the following in a comment at the end of the child file (with the arguments adjusted appropriately):


{{Input|1=Local Variables:
sgml-parent-document:("index.docbook" "book" "chapter")
End:}}


The first argument is the name of the parent file (which will almost always be <tt>index.docbook</tt> in KDE
documentation). The second argument is the top-level (or "root") element of the whole document (i.e., in the parent file). The third argument is the top-level element in this file.

</translate><translate>

=== Checking and Viewing the Documents === 


There are a couple of KDE-specific tools for manipulating DocBook files, namely '''meinproc4''' and '''checkxml'''. '''checkxml''' (as the name suggests) is used to check that documents are valid, well-formed
XML, and '''meinproc4''' converts DocBook files to HTML. Here's some hints on using each of them:

==== Using checkXML ==== 


'''checkXML''' is a simple command with only one argument: the file to check. However, the output can be a bit daunting, since one small mistake can cause a cascade of errors. The trick is to look at the first error, fix that error, save the file, and run '''checkXML''' again. Often, fixing that one error will get rid of all the other error messages. When running '''meinproc4''', the same procedure applies.</translate>
<translate>


Most errors in DocBook sources fall into one of a few categories. Here are descriptions of some of the most common errors and their solutions:


;Opening and ending tag mismatch
{{Output|1=index.docbook:880: parser error : Opening and ending tag mismatch: para
line 879 and sect2
</sect2>
^}}
This is possibly the most common type of error. It's caused either by an element that hasn't been closed, or by tags that overlap. The error above was generated by the following markup:
{{Input|1=


<sect2>
...
878: running &meinproc;, the same procedure applies.
879: &checkxml; is a simple command with
880: </sect2>
...}}
The <code>para</code> tag on line 879 has not been closed before the <code>sect2</code> on line 880, causing the error. The simple fix in this case is to add a <code>para</code> before the closing <code>sect2</code>.


;Element does not follow the DTD
{{Output|1=index.docbook:932: element qandaentry: validity error : Element qandaentry content
does not follow the DTD, expecting (blockinfo? , revhistory? , question , answer*), got (answer)
</para></answer></qandaentry>
^}}
This error is caused by an element in the document not matching the requirements of the DocBook DTD (Document Type Definition). The DTD specifies what each element must contain. This list is shown after <tt>expecting</tt> in the error message. This so-called "content model" is quite difficult to understand at first: refer to the Duck Book and the section "Understanding Content Models" for full information.
 
The text after <tt>got</tt> shows the content actually found in the document.
 
In the example above, we have a <code>qandaentry</code> which is missing the required <code>question</code> element. This was generated by the following input:
{{Input|1=<qandaset>
<qandaentry><answer>An answer
</answer></qandaentry>
</qandaset>}}
Adding a <code>question</code> element before the <code>answer</code> fixes the problem.
 
An easy mistake to make is to forget to put a <code>para</code> element around text in, for example, a <code>listitem</code> or a <code>sect'''''n'''''</code>. This will be shown as <tt>CDATA</tt> in the <tt>got</tt> section of the error.

==== Using meinproc4 ==== 


The most common way to run '''meinproc4''' is simply as


{{Input|1=meinproc4 '''''docbook-file'''''}}


where '''''docbook-file''''' is usually <tt>index.docbook</tt>. This command creates HTML pages from the DocBook file. Note that these pages are only viewable in KDE-based browsers (like '''Konqueror'''). If you need to view the HTML output in another browser (for example, if you're placing it on line), use


{{Input|1=meinproc4 --stylesheet '''''stylesheet-name''''' '''''docbook-file'''''}}


where '''''stylesheet-name''''' is the full path to one of the XSL stylesheets in <tt>$KDEDIR/share/apps/ksgmltools/customization</tt>. To produce output suitable for the web, you can use <tt>kde-web.xsl</tt> or <tt>kde-chunk-online.xsl</tt>. See the <tt>README</tt> file in that folder for more details.


{{Prevnext2
| prevpage=Documentation_Primer/Manual/Getting Started
| prevtext=Getting Started
| nextpage=Documentation_Primer/Manual/DocBook
| nexttext=DocBook Introduction
| index=Documentation_Primer/Manual
| indextext=Back to Menu
}}
</translate>

← Older revision		Revision as of 08:26, 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 24: / Line 24: @@
 <!--T:8-->
-You are welcome to use plain text to contribute to KDE documentation. It is a great way to start, and we strongly encourage it. If you will miss the power of the DocBook format as you improve your documentation skills, then you can learn it. In the mean time, someone will manually edit the plain text to add the DocBook markup and commit it to KDE svn or git repository, removing the burden of doing most of the more complex stuff covered in this very guide. We'll take a look at writing in DocBook and using svn or git later in this document, so if you're interested, read on, but if you want to use plain text, you can go directly to [[#Working with plain text sources]].
+You are welcome to use plain text to contribute to KDE documentation. It is a great way to start, and we strongly encourage it. If you will miss the power of the DocBook format as you improve your documentation skills, then you can learn it. In the mean time, someone will manually edit the plain text to add the DocBook markup and commit it to KDE svn or git repository, removing the burden of doing most of the more complex stuff covered in this very guide. We'll take a look at writing in DocBook and using svn or git later in this document, so if you're interested, read on, but if you want to use plain text, you can go directly to [[Special:myLanguage/Documentation Primer/Manual/Writing#Working with plain text sources|Working with plain text sources]].
 <!--T:9-->
@@ Line 294: / Line 294: @@
 <!--T:76-->
 {{Prevnext2
-| prevpage=Documentation_Primer/Manual/Getting Started
+| prevpage=Special:myLanguage/Documentation_Primer/Manual/Getting Started
 | prevtext=Getting Started
-| nextpage=Documentation_Primer/Manual/DocBook
+| nextpage=Special:myLanguage/Documentation_Primer/Manual/DocBook
 | nexttext=DocBook Introduction
-| index=Documentation_Primer/Manual
+| index=Special:myLanguage/Documentation_Primer/Manual
 | indextext=Back to Menu
 }}
 </translate>

Documentation Primer/Manual/Writing - Revision history

Claus chr: Corrected links

Claus chr at 08:26, 2 September 2012

Claus chr at 09:02, 1 September 2012

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

Yurchor: Marked this version for translation