Move Tutorials from tdebase. Add docbook & markup tutorials. Tutorials need

editing and updating. Thus the default configuration is -DBUILD_TUTORIALS=OFF.

3 files changed, 478 insertions, 0 deletions

diff --git a/doc/tutorials/styleguide/CMakeLists.txt b/doc/tutorials/styleguide/CMakeLists.txt
new file mode 100644
index 0000000..396682f
--- /dev/null
+++ b/doc/tutorials/styleguide/CMakeLists.txt
@@ -0,0 +1,9 @@
+#################################################
+#
+#  Improvements and feedback are welcome
+#
+#  This file is released under GPL >= 2
+#
+#################################################
+
+tde_create_handbook( DESTINATION khelpcenter/styleguide )
diff --git a/doc/tutorials/styleguide/Makefile.am b/doc/tutorials/styleguide/Makefile.am
new file mode 100644
index 0000000..4169155
--- /dev/null
+++ b/doc/tutorials/styleguide/Makefile.am
@@ -0,0 +1,3 @@
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/tutorials/styleguide/index.docbook b/doc/tutorials/styleguide/index.docbook
new file mode 100644
index 0000000..8c94356
--- /dev/null
+++ b/doc/tutorials/styleguide/index.docbook
@@ -0,0 +1,466 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kde-authors '<personname><surname>The &kde; Documentation Team</surname></personname>'>
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE"><!-- change language only here -->
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &tde; Style Guide</title>
+
+<authorgroup>
+<author>&kde-authors;</author>
+<author>&tde-authors;</author>
+</authorgroup>
+
+<copyright>
+<year>2002</year>
+<holder>The KDE e.V.</holder>
+</copyright>
+<copyright>
+<year>&tde-copyright-date;</year>
+<holder>&tde-team;</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>&tde-release-date;</date>
+<releaseinfo>&tde-release-version;</releaseinfo>
+
+<abstract>
+<para>
+A reference guide to &tde; style standards for writing documentation.
+Please report any errors or omissions to
+<email>trinity-devel@lists.pearsoncomputing.net</email>.
+</para>
+</abstract>
+
+<keywordset>
+<keyword>TDE</keyword>
+<keyword>Docbook</keyword>
+<keyword>Documentation</keyword>
+<keyword>Authors</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>The purpose of writing documentation for the &tde; Project, is
+to create for all the users, a complete, well organized set of
+documentation for each and every component of the &tde; project. In
+order to achieve this goal, we have drafted the following guide to
+help.</para>
+
+<para>This document is very new, and at the moment, very
+sparse.</para>	
+
+<para>If you have comments or additions, please do not hesitate to
+suggest them on the kde-doc-english@kde.org mailing list.</para>
+
+<para>In the meantime, here are some short notes based on content that
+was previously on the <ulink url="http://i18n.kde.org/">&tde;
+i18n</ulink> website.</para>
+
+</chapter>
+
+<chapter id="consistency">
+<title>Consistency</title>
+
+<sect1 id="dates-and-revisions">
+<title>Dates and Revision Numbers</title>
+
+<para>While it may seem like a minor issue, and a minor part of your
+document, it is very important that the following guidelines are
+adhered to:</para>
+
+<itemizedlist>
+<listitem>
+<para>All dates which are part of the text of your document
+should be spelled out &ie; <quote>March 2, 2000</quote></para>
+<para>This is the only way to be sure that <quote>03/02/2000</quote>
+is interpreted correctly in all languages, and by all readers.</para>
+<important><para>Exception: in the <sgmltag>date</sgmltag> tag, dates
+should be in the <quote>YYYY-MM-DD</quote> format.</para>
+</important>
+</listitem>
+<listitem>
+<para>All information included between the <sgmltag
+class="starttag">releaseinfo</sgmltag> and <sgmltag
+class="endtag">releaseinfo</sgmltag> should match the release number
+of the application.</para>
+</listitem>
+</itemizedlist>
+</sect1>
+
+<sect1 id="screenshots">
+<title>Screenshot Consistency</title>
+
+<para>To create consistent screenshots, use an environment where all requirements can
+be configured without interfering with your normal production environment. One option
+is a virtual machine. Another option is creating at least two themes. One theme is the
+normal everyday theme for production. The other theme is for handbook screenshots.
+Toggle between the two themes as necessary. A third option is a separate user
+account configured as required.</para>
+
+<para>To strive for a look of consistency with screenshots, please abide by the
+following requirements.</para>
+
+<itemizedlist>
+
+<listitem>
+<para>No personal information. That includes login names. Be careful when including
+window decorations because the title bar could include such information. Use a testing
+account or a virtual machine when such information cannot be avoided.</para>
+</listitem>
+<listitem>
+<para>Use &ksnapshot;. Normally use the <guilabel>Window Under Cursor</guilabel> option. Use the
+<ulink url="help:/ksnapshot"> &ksnapshot; Handbook</ulink> to learn more.</para>
+</listitem>
+<listitem>
+<para>Using the &ksnapshot; <guilabel>Include window decorations</guilabel> option is not
+required and not forbidden. Just ensure the decorations to do not interfere with the
+purpose of the screenshot.</para>
+</listitem>
+<listitem>
+<para>PNG images only.</para>
+</listitem>
+<listitem>
+<para>Window decorations: KDE2, Keramik, or Plastik.</para>
+</listitem>
+<listitem>
+<para>Widget style: KDE Classic, Keramik, or Plastik.</para>
+</listitem>
+<listitem>
+<para>In &kcontrol;->Style, enable <guilabel>Show icons on buttons</guilabel>.</para>
+</listitem>
+<listitem>
+<para>Colors: TDE defaults.</para>
+</listitem>
+<listitem>
+<para>Background: No wallpaper, no gradients.</para>
+</listitem>
+
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="other-consistency-issues">
+<title>Other Consistency Issues</title>
+
+<itemizedlist>
+<listitem>
+<para>Please submit only plain <acronym>ASCII</acronym> text, or
+Docbook &XML;. Anything else will be returned to you. (Docbook &XML; is
+preferred.)</para>
+</listitem> 
+<listitem>
+<para>Make sure you first read, and follow, the documentation template
+provided. You can find this in the source folder for &tde;. Simply
+point a browser to <filename
+class="directory">tdelibs/doc/kdoctools/template.docbook</filename></para>
+<note><para>If there is existing documentation (from the developer, or
+from &tde; 1.x or 2.x), then use that as a base to work from, but it
+needs to conform to the layout from the documentation
+template.</para></note>
+</listitem>
+<listitem>
+<para>Spell things according to Standard American spelling, except for
+proper names, places, &etc;</para>
+</listitem>
+<listitem>
+<para>Make sure to set your spell checker to US English. Make sure you
+<emphasis>use</emphasis> your spell checker.</para>
+</listitem>
+<listitem>
+<para>If there is a non-English word, which is used in an English
+sentence, be sure to spell this correctly, using appropriate accent
+marks, and any special characters. Use the &kcharselect; application
+if you don't have the correct keys on your keyboard.</para>
+</listitem>
+<listitem>
+<para>Abbreviations should be capitalized, unless they are
+specifically intended      to not be capitalized. (&ie; is a good
+example).</para>
+</listitem>
+<listitem>
+<para>Punctuation within numbers should be Americanized:
+10,000.00</para>
+</listitem>
+<listitem>
+<para>It is more legible to use written numbers where the number has
+no technical value, &eg; <quote>There are three buttons on the
+dialog</quote>. In this context <quote>3</quote> is not technically
+significant. Numbers with technical significance should be written as
+figures. (&ie; <quote>a 10 MB file</quote>, not <quote>a ten MB
+file</quote>.)</para>
+</listitem>
+<listitem>
+<para>Spell check and proofread your work before you send it in. Or
+even better, have someone else read it over. Spell checking programs
+won't catch incorrect words such as using <quote>their</quote> for
+<quote>there</quote>.</para>
+</listitem>
+</itemizedlist>
+</sect1>
+
+</chapter>
+
+<chapter id="writing-well">
+<title>Writing Well</title>
+
+<para>Some things to think about when writing documentation</para>
+
+<para>How many times have you attempted to read a man page, and given
+up in frustration &mdash; all the facts are there, but the writing is
+too dry and technical for you to make sense of them? We want to avoid
+this with the documentation you're writing. </para>
+
+<para>It's difficult to avoid the very dry, choppy style we're all too
+familiar with, but do try to make the writing flow and keep it
+<emphasis>user-friendly</emphasis>. Try to be as friendly as you can
+manage without being patronizing, and without sacrificing clarity or
+detail.</para>
+
+<para> Things you should consider: </para>
+
+<itemizedlist>
+
+<listitem>
+<para>Make sure you explain all aspects of the interface, and that you
+don't leave out any command line options available. </para>
+</listitem>
+
+<listitem>
+<para>It's important to keep a logical progression of difficulty. Keep
+the first few pages of the document simple, and accessible to users
+who have never seen the application before. More technical information
+should appear towards the end of the document. </para>
+</listitem>
+
+<listitem>
+<para>Be sure to write to the level of the intended reader. By this we
+mean, a Samba control module has a very different user base than a
+user of a game, and the manuals should reflect this. Don't insult the
+Samba networker's intelligence, and don't assume knowledge for the
+gamer that might not be there.</para> 
+</listitem>
+
+<listitem>
+<para>It is highly encouraged to use screenshots, pictures of action
+buttons, &etc; These are &GUI; applications, and a picture can be worth a
+thousand words. </para>
+</listitem> 
+
+<listitem>
+<para>Please define computer abbreviations, unless they are well
+understood by all computer users (There's no need to define
+<acronym>RAM</acronym>, <acronym>PC</acronym>, &etc;).</para>
+
+<para>For example, <quote>If you are going to use
+<acronym>PPP</acronym> (Point to Point Protocol),
+then.....</quote>. Define it only once though, in this example you
+could now use <acronym>PPP</acronym> without explanation for the rest
+of the document.</para>
+
+<para>The first time you introduce the word you should use <sgmltag
+class="starttag">firstterm</sgmltag> or consider setting up a glossary
+and using <sgmltag class="starttag">glossentry</sgmltag>.</para>
+</listitem>
+
+<listitem>
+<para>Remember the small things: If it's dockable, explain how to do
+that. Don't forget to mention where it installs itself in the K
+menu. If there are any environment settings required, and if they must
+be set manually, explain how to do that - if they're set
+automatically, they still need to be documented.</para>
+</listitem>
+
+<listitem>
+<para>Write something you would be happy to read as a user who doesn't
+know how the application works. Perhaps if you have a friend or family
+member who isn't familiar with the application you're writing about,
+have them work through using it, with your documentation as a
+guide. </para>
+</listitem>
+</itemizedlist>
+
+</chapter>
+
+<chapter id="more-hints">
+<title>Other general tips and hints for good writing</title>
+
+<para>A good way to catch simple errors is to read the text out loud,
+or have someone else read it to you. Passages that don't
+<quote>flow</quote> or have obviously awkward construction of the type
+you may miss on the screen, will usually become blindingly obvious
+when you hear them. This is especially the case with detecting really
+long sentences, as you will run out of breath and turn blue.</para>
+
+<para>Be concise, be specific, and be direct. Choose your words
+carefully, and  be certain you know the exact meaning of every word
+you use. Is it the right word? Use a dictionary, and find out.</para>
+
+<para>Use complete sentences. Not fragments. Like these ones.</para>
+
+<para>While talking about sentences:</para>
+<itemizedlist>
+<listitem>
+<para>Avoid run on sentences, sentences that cover several different
+subjects, or sentences that could be broken up into several sentences;
+avoid sentences that can fill a whole paragraph all by themselves and
+that are really long, like this one, which is all of the above.</para>
+</listitem>
+<listitem>
+<para>
+Use a comma before <quote>and</quote> in compound sentences, &eg;
+<quote>Use the left mouse button to select and copy text, and the
+middle mouse button to paste it.</quote></para>
+</listitem>
+<listitem>
+<para>Keep to logical sentence order.</para>
+<para>For example, <quote>&konqueror; is a web browser with the
+ability to browse file systems and it includes a javascript
+interpreter.</quote> (Do you see why this is awkward?)</para>
+</listitem>
+<listitem>
+<para>Try not to use the same word several times in the same sentence.
+An exception to this, is an application command or technical word,
+where this repetition is necessary, and improves clarity.</para>
+</listitem>
+<listitem>
+<para>Do not start sentences with any of <quote>and,</quote>
+<quote>so,</quote> <quote>but,</quote> <quote>because,</quote> or
+<quote>however.</quote></para>
+</listitem>
+<listitem>
+<para>Try to avoid contractions, rather spell out both words; &eg;,
+<quote>it is</quote> rather than <quote>it's</quote>; <quote>can
+not</quote> rather than <quote>can't</quote></para>
+</listitem>
+<listitem>
+<para>There is no need to worry about simple text formatting such as
+leaving two spaces after punctuation or indenting paragraphs. This is
+all handled by Docbook &XML; and the <acronym>XSLT</acronym>
+stylesheets in use.</para>
+</listitem>
+</itemizedlist>
+
+<para>Remember, we have also an active proofreading team, and there is
+always someone to help you with grammar, so just
+write and have fun!</para>
+
+</chapter>
+
+<chapter id="resources">
+<title>Resources</title>
+
+<sect1 id="general-purpose-sites">
+<title>General Purpose Websites</title>
+
+<para>A few sites you may find worth bookmarking, or at least
+visiting.</para>
+
+<sect2 id="dictionary-sites">
+<title>Dictionary Sites</title>
+
+<itemizedlist>
+<listitem>
+<para><ulink url="http://www.m-w.com/">Merriam Webster
+Online</ulink></para>
+</listitem>
+<listitem>
+<para><ulink
+url="http://www.dictionary.com/">Dictionary.com</ulink></para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="thesaurus-sites">
+<title>Thesaurus Sites</title>
+
+<itemizedlist>
+<listitem>
+<para><ulink url="http://www.m-w.com/">Merriam-Webster</ulink> have a
+thesaurus as well as a dictionary</para>
+</listitem>
+<listitem>
+<para><ulink url="http://www.thesaurus.com/">Roget's
+Thesaurus</ulink></para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="other-style-guides">
+<title>Style Guides and Other Resources</title>
+
+<itemizedlist>
+<listitem>
+<para><ulink
+url="http://www.cc.columbia.edu/acis/bartleby/strunk/">Strunk &amp;
+White</ulink> is the base style guide for many newspapers and press
+galleries. If you want to look up a grammar or usage question, this is
+the place to go.</para> </listitem>
+
+<listitem>
+<para>The <ulink
+url="news://alt.usage.english">alt.usage.english</ulink> newsgroup.
+If you'd like every sentence chewed over, dissected, and then
+rewritten several conflicting ways, or some great advice about bacon,
+you'll find both here. Many real live editors and authors hang out
+here, and they do know their stuff. Just make sure you read all ten
+or so <acronym>FAQ</acronym>'s before asking a question.</para>
+</listitem>
+</itemizedlist>
+<para>Other possibly useful sites</para>
+
+<itemizedlist>
+<listitem><para><ulink
+url="http://hotwired.lycos.com/hardwired/wiredstyle/biblio/">The Wired 
+      Style Guide Bookmarks section</ulink></para>
+</listitem>
+
+<listitem>
+<para><ulink
+url="http://www2.rscc.cc.tn.us/%7Ejordan_jj/OWL/Clutter.html">http://www2.rscc.cc.tn.us/~jordan_jj/OWL/Clutter.html</ulink>
+If you tend to write very wordy sentences, here's a page with some
+help for you. Includes a useful table of ways to rewrite common
+mistakes.</para>
+</listitem>
+<listitem>
+<para><ulink
+url="http://owl.english.purdue.edu/Files/116.html">http://owl.english.purdue.edu/Files/116.html
+</ulink> is a page about how to make sentences <quote>flow</quote>
+better</para>
+</listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+
+</chapter>
+
+<!-- &trademarks; -->
+
+
+<chapter id="credits-and-license">
+<title>Credits and Licenses</title>
+
+<para>The &tde; Documentation Style Guide</para>
+
+<!-- FIXME proper credits section -->
+<para>Copyright 2002, Lauri Watts, Mike McBride, Eric Bischoff,
+Frederik Fouvry.</para>
+<para>Copyright &tde-copyright-date;, &tde-authors;.</para>
+
+&underFDL;
+
+</chapter>
+
+<!-- &wordlist; -->
+
+</book>