editing and updating. Thus the default configuration is -DBUILD_TUTORIALS=OFF.pull/1/head
Darrell Anderson
10 years ago
parent
fd63c2d407
commit
dd581bd656
@ -0,0 +1,9 @@
|
||||
#################################################
|
||||
#
|
||||
# Improvements and feedback are welcome
|
||||
#
|
||||
# This file is released under GPL >= 2
|
||||
#
|
||||
#################################################
|
||||
|
||||
tde_auto_add_subdirectories()
|
||||
@ -0,0 +1,4 @@
|
||||
KDE_LANG = en
|
||||
KDE_DOCS = AUTO
|
||||
SUBDIRS = $(AUTODIRS)
|
||||
|
||||
@ -0,0 +1,9 @@
|
||||
#################################################
|
||||
#
|
||||
# Improvements and feedback are welcome
|
||||
#
|
||||
# This file is released under GPL >= 2
|
||||
#
|
||||
#################################################
|
||||
|
||||
tde_create_handbook( DESTINATION khelpcenter/docprimer )
|
||||
@ -0,0 +1,3 @@
|
||||
KDE_LANG = en
|
||||
KDE_DOCS = AUTO
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
|
After Width: | Height: | Size: 79 KiB |
|
After Width: | Height: | Size: 69 KiB |
|
After Width: | Height: | Size: 27 KiB |
|
After Width: | Height: | Size: 12 KiB |
|
After Width: | Height: | Size: 6.7 KiB |
|
After Width: | Height: | Size: 59 KiB |
|
After Width: | Height: | Size: 28 KiB |
|
After Width: | Height: | Size: 53 KiB |
|
After Width: | Height: | Size: 455 B |
|
After Width: | Height: | Size: 257 B |
@ -0,0 +1,9 @@
|
||||
#################################################
|
||||
#
|
||||
# Improvements and feedback are welcome
|
||||
#
|
||||
# This file is released under GPL >= 2
|
||||
#
|
||||
#################################################
|
||||
|
||||
tde_create_handbook( DESTINATION khelpcenter/markup )
|
||||
@ -0,0 +1,3 @@
|
||||
KDE_LANG = en
|
||||
KDE_DOCS = AUTO
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,9 @@
|
||||
#################################################
|
||||
#
|
||||
# Improvements and feedback are welcome
|
||||
#
|
||||
# This file is released under GPL >= 2
|
||||
#
|
||||
#################################################
|
||||
|
||||
tde_create_handbook( DESTINATION khelpcenter/styleguide )
|
||||
@ -0,0 +1,3 @@
|
||||
KDE_LANG = en
|
||||
KDE_DOCS = AUTO
|
||||
|
||||
@ -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, ⪚ <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 — 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, ⪚
|
||||
<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; ⪚,
|
||||
<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 &
|
||||
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>
|
||||
@ -0,0 +1,11 @@
|
||||
#################################################
|
||||
#
|
||||
# Improvements and feedback are welcome
|
||||
#
|
||||
# This file is released under GPL >= 2
|
||||
#
|
||||
#################################################
|
||||
|
||||
install( FILES
|
||||
.directory docprimer.desktop markup.desktop styleguide.desktop
|
||||
DESTINATION ${DATA_INSTALL_DIR}/khelpcenter/plugins/Tutorials )
|
||||
@ -0,0 +1,4 @@
|
||||
tut_DATA = .directory docprimer.desktop markup.desktop styleguide.desktop
|
||||
tutdir = $(kde_datadir)/khelpcenter/plugins/Tutorials
|
||||
|
||||
|
||||
@ -0,0 +1,4 @@
|
||||
[Desktop Entry]
|
||||
Name=The TDE Documentation Primer
|
||||
DocPath=help:/khelpcenter/docprimer/index.html
|
||||
Icon=khelpcenter
|
||||
@ -0,0 +1,4 @@
|
||||
[Desktop Entry]
|
||||
Name=The TDE DocBook Markup Guide
|
||||
DocPath=help:/khelpcenter/markup/index.html
|
||||
Icon=khelpcenter
|
||||
@ -0,0 +1,4 @@
|
||||
[Desktop Entry]
|
||||
Name=The TDE Help Handbook Style Guide
|
||||
DocPath=help:/khelpcenter/styleguide/index.html
|
||||
Icon=khelpcenter
|
||||
Loading…
Reference in new issue