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

Claus chr at 11:07, 9 September 2012

2012-09-09T11:07:30Z

Claus chr at 11:05, 9 September 2012

2012-09-09T11:05:25Z

Claus chr: Corrected links

2012-09-09T10:39:31Z

Corrected links

Claus chr at 08:31, 2 September 2012

2012-09-02T08:31:38Z

Claus chr at 09:09, 1 September 2012

2012-09-01T09:09:05Z

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

2012-09-01T08:47:34Z

1 revision: Moving Docbook Primer from UserBase to TechBase

Claus chr: Indented boxes lo longer work

2012-08-08T09:00:25Z

Indented boxes lo longer work

New page

<translate>

=== Markup for programming === 


:For formally marking up code examples or making a synopsis, you should study the Duck Book and the [[Documentation Primer/Manual/DocBook Reference/Synopsis|The synopsis elements]] chapter. The elements described below are mainly for marking up of pieces of source code that appear in the running text. Remember that KDE and KDE applications are written almost exclusively in C++, so our useage may differ in places from the examples in the Duck book, which may be describing other programming languages.


:To Developers reading this, remember most of the authors who may be documenting your work are unfamiliar with source code, and many of them like it that way. Therefore, the explanations here are more concerned with how to tell things apart than what they are for, and may make you cringe.


:To everyone reading this, this section is very much under construction so to speak. If you already need to use this markup, you can ask questions on the kde-docbook mailing list, which is the most likely place to get correct and up to date answers.


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


:Used to identify the name of a class in a programming language. In KDE Documentation, you won't see this much in the user documentation, except for those applications which contain an API reference chapter, and occasionally in others. You will find it used a lot in the '''KDevelop''' documentation.


:For non-programmers, as we're almost exclusively discussing KDE applications written in C++ and using Qt™, classnames are fairly easy to distinguish: They start with a capital Q or K, and are usually one word only, in the form of <tt>KApplication</tt> or <tt>QListBox</tt>.


{{Tag|function}}, {{Tag|methodname}}
</translate><translate>
</translate><translate>


:A function or "subroutine". In C++, a function generally looks something like this: <tt>foo();</tt>. The semi-colon may not always be present and there may or may not be content inside the braces.


:If you see things that have the form <tt>Kfoo::bar()</tt> these are not just functions, but also methods, so you would use the {{Tag|methodname}} for these.


:Constructors are methods where the parts before and after the :: are the same, e.g. <tt>KFoo::Kfoo()</tt>. Destructors look like Constructors, but have a <tt>~</tt> after the :: e.g. <tt>Kfoo::~Kfoo()</tt>. The same things apply as with functions and methods: there may or may not be a ; at the end, and there may or may not be content inside the braces of a constructor (there is never content for a destructor).


:These are normally marked up as {{Tag|methodname}}, but if you need to make a synopsis of a method, there are specific elements available: [[#constructorsynopsis|{{Tag|constructorsynopsis}}]] and [[#destructorsynopsis|{{Tag|destructorsynopsis}}]]


:To recap:


:Function
::<tt>foo()</tt>


:Methodname
::<tt>Kfoo::bar()</tt>


:Constructor
::<tt>Kfoo::Kfoo()</tt> These are methods in ordinary text, but when making a synopsis, have a more specific tag to use.


:Destructor
::<tt>Kfoo::~Kfoo()</tt> These are methods in ordinary text, but when making a synopsis, have a more specific tag to use.


:Sometimes you really cannot tell the difference, especially when they are being mentioned in passing in the text. Also, programmers tend to shorten and make shortcuts when referring to snippets of source. If it's very unclear what something is, mark it up with {{Tag|function}} and ask the developer.


{{Tip|1=Asking a developer "What is foo?" will likely result in a two page explanation of a finer point of C++ programming, which, if you could understand it, you wouldn't have needed to ask the question in the first place. It saves everyone a lot of time and frustration if you word the question "Out of function, method, constructor and destructor, which is the best fit for foo?".}}


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


:The name of a variable.


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


:The value returned by a function.


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


:A token is a placeholder, something that is replaced by an actual value during processing. (I need to come up with a useful example for a token)


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


:A constant. In the snippet:


:{{Input|1=enum MyType { Red = 0, Green, Blue, Yellow };}}


:<tt>Red</tt>, <tt>Green</tt>, <tt>Blue</tt> and <tt>Yellow</tt> should be marked up as {{Tag|constant}}


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


:Used to classify a value. In the snippet:


:{{Input|1=enum MyType { Red = 0, Green, Blue, Yellow };}}


:<tt>MyType</tt> is a {{Tag|type}}


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


:Use this to wrap any source code examples in your document. You don't need to use this for short snippets that are inline in the text, but you should use it for any examples longer than a line or two, or that are a separate block of text.


{{Tag|structname}},{{Tag|structfield}}
</translate><translate>
</translate><translate>


:Not used in KDE Documentation, primarily because they are rare in KDE source code, and are almost certainly never going to require marking up.


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


:Parameters can be used for commandlines as well as for code samples.


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


:A class synopsis


:{{Input|1=<nowiki>
DCOPStub {
? not sure about what goes here ? enum Status(''CallSucceeded'', ''CallFailed'');
}
</nowiki>}}


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


:An initializer


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


:An exception name

</translate>



<translate>


{{Prevnext2
| prevpage=Documentation Primer/Manual/DocBook Reference/Synopsis
| prevtext=The synopsis elements
| nextpage=Documentation Primer/Manual/DocBook Reference/Callouts
| nexttext=Making Callouts
| 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 167: / Line 167: @@
 <anchor id="constructorsynopsis"/>
 <anchor id="destructorsynopsis"/>
 <anchor id="methodparam"/>
 <anchor id="methodsynopsis"/>

@@ Line 5: / Line 5: @@
 <!--T:2-->
-:For formally marking up code examples or making a synopsis, you should study the Duck Book and the [[Documentation Primer/Manual/DocBook Reference/Synopsis|The synopsis elements]] chapter.  The elements described below are mainly for marking up of pieces of source code that appear in the running text.  Remember that KDE and KDE applications are written almost exclusively in C++, so our useage may differ in places from the examples in the Duck book, which may be describing other programming languages.
+:For formally marking up code examples or making a synopsis, you should study the Duck Book and the [[Special:myLanguage/Documentation Primer/Manual/DocBook Reference/Synopsis|The synopsis elements]] chapter.  The elements described below are mainly for marking up of pieces of source code that appear in the running text.  Remember that KDE and KDE applications are written almost exclusively in C++, so our useage may differ in places from the examples in the Duck book, which may be describing other programming languages.
 <!--T:3-->
@@ Line 38: / Line 38: @@
 <!--T:12-->
-:These are normally marked up as {{Tag|methodname}}, but if you need to make a synopsis of a method, there are specific elements available: [[#constructorsynopsis|{{Tag|constructorsynopsis}}]] and [[#destructorsynopsis|{{Tag|destructorsynopsis}}]]
+:These are normally marked up as {{Tag|methodname}}, but if you need to make a synopsis of a method, there are specific elements available: [[Special:myLanguage/Documentation Primer/Manual/DocBook Reference/Programming#constructorsynopsis|{{Tag|constructorsynopsis}}]] and [[Special:myLanguage/Documentation Primer/Manual/DocBook Reference/Programming#destructorsynopsis|{{Tag|destructorsynopsis}}]]
 <!--T:13-->
@@ Line 176: / Line 176: @@
 <!--T:47-->
 {{Prevnext2
-| prevpage=Documentation Primer/Manual/DocBook Reference/Synopsis
+| prevpage=Special:myLanguage/Documentation Primer/Manual/DocBook Reference/Synopsis
 | prevtext=The synopsis elements
-| nextpage=Documentation Primer/Manual/DocBook Reference/Callouts
+| nextpage=Special:myLanguage/Documentation Primer/Manual/DocBook Reference/Callouts
 | nexttext=Making Callouts
-| index=Documentation Primer/Manual
+| index=Special:myLanguage/Documentation Primer/Manual
 | indextext=Back to Menu
 }}
 </translate>