GNOME.org
 

Patch to remove distro-specific references in Evolution docs

(Cross-posting to evolution-patches and to gnome-doc-list)

Attached is a first-pass at a patch to the Evolution documentation. 
Doesn't yet have a ChangeLog since I'd like feedback from the Evolution
and GNOME docs people.

It moves any Novell-specific references I found into entities, defined
at the top of the document, with a proposed "generic" GNOME version; I
also added some entities for things that I think distributions may want
to customise.

This covers things like "how to install packages", the layout of the
main GNOME menu etc.

I also introduced VERSION and DATE entities, and fixed things up to use
these where I've seen them, so lots of occurrences of "2.0" are now
"2.2"

I've tested successfully with yelp (both with my generic version, and my
"Novell" version of the entities), though this was with yelp 2.6.0 as
I'm currently stuck at home owing to a blizzard last night :-(

The latter should appear exactly as the current docs appear.

I also moved a reference from "evolution" to
"<filename>.evolution</filename>"

I've left the legal appendix as-is apart from a modification to use the
VERSION and DATE entities.

If distributions want to make minor patches to these entities, can
they?  The GNU FDL appears to impose some onerous restrictions on doing
Modified Versions; in particular, it looks like we'd need to create a
History section.  Also, for me (albeit on the increasingly ancient yelp
2.6) the legal info doesn't render properly, which is a bit of an issue
if it must be preserved verbatim.  This may apply to translators as
well.  Usual disclaimers apply; I am not a lawyer.

Some stylistic questions regarding markup: how do the maintainers feel
about me adding <guimenu>/<guimenuitem> tags where appropriate?  How
about me adding an entity for the separator for these?  Is there policy
for this within the GNOME documentation team?

Dave Malcolm


? distro-fixes.patch
? help/C/less
Index: help/C/evolution.xml
===================================================================
RCS file: /cvs/gnome/evolution/help/C/evolution.xml,v
retrieving revision 1.5
diff -u -p -r1.5 evolution.xml
--- help/C/evolution.xml	20 Feb 2005 04:29:19 -0000	1.5
+++ help/C/evolution.xml	9 Mar 2005 20:50:31 -0000
@@ -7,21 +7,49 @@
  <!ENTITY z-CLM "(CLM)" >
  <!ENTITY z-nbhyph "-" >
  <!ENTITY z-nbspace " " >
+
+ <!ENTITY VERSION "2.2" >
+ <!ENTITY VERSION_SERIES "&VERSION;.x" >
+ <!ENTITY DATE "March 9th 2005" >
+
+<!-- Entities for a generic GNOME version of the documentation, with hooks for distro-specific customisation: -->
+ <!ENTITY SUPPORT_NOTES "" >
+ <!ENTITY DOCUMENTATION_UPDATES "" >
+ <!ENTITY PARA_ABOUT_GREATER_THAN_SYMBOL "" >
+ <!ENTITY STARTING_EVOLUTION_FROM_PANEL "Click the Applications Menu icon &gt; Office &gt; Evolution." >
+ <!ENTITY CONNECTOR_AVAILABILITY_SENTENCE "" > 
+ <!ENTITY INSTALLING_THE_CONNECTOR_PARA "<para>The Evolution Connector for Microsoft Exchange is a separate package to Evolution, and must be installed in its own right.  The precise way to do this varies between distributions; consult your distribution's documentation for more information.</para>" >
+ <!ENTITY SPELLING_INSTALLATION_NOTES "" >
+ <!ENTITY ADDITIONAL_HELP_PARA "" >
+ <!ENTITY KNOWLEDGEBASE_INFO_ON_CONNECTOR_PARA "" >
+
+<!-- Suggested Novell versions here: -->
+<!--
+ <!ENTITY SUPPORT_NOTES "<listitem><para>For support, late-breaking news, and errata, visit the Novell support center at <ulink url='http://support.novell.com'>support.novell.com</ulink>.</para></listitem>" >
+ <!ENTITY DOCUMENTATION_UPDATES "<bridgehead>Documentation Updates</bridgehead><para>For the most recent version of the<citetitle> Evolution &VERSION; User Guide</citetitle>, see the <ulink url='http://www.novell.com/documentation/ximian.html'>Evolution Documentation Web site</ulink>.</para>" >
+ <!ENTITY PARA_ABOUT_GREATER_THAN_SYMBOL "<para>In Novell documentation, a greater-than symbol (&gt;) is used to separate actions within a step and items in a cross-reference path.</para>" >
+ <!ENTITY STARTING_EVOLUTION_FROM_PANEL "Click the Applications Menu icon &gt; Office &gt; Evolution." >
+ <!ENTITY CONNECTOR_AVAILABILITY_SENTENCE "It is available through Red Carpet in its own channel." > 
+ <!ENTITY INSTALLING_THE_CONNECTOR_PARA "<para>To install the Evolution Connector, run Red Carpet by clicking System &gt; Get Software. Subscribe to the Evolution Connector for Microsoft Exchange channel, select the Evolution Connector for Microsoft Exchange 2000, then click the Install button. You can also install the Connector by downloading the individual packages from ftp.ximian.com if you wish.</para>" >
+ <!ENTITY SPELLING_INSTALLATION_NOTES "You must install the gnome-spell package, available through Red Carpet, for spell-checking to be available in Evolution. Additional dictionaries are also available through Red Carpet and are detected automatically if you have installed them." >
+ <!ENTITY ADDITIONAL_HELP_PARA "<para>If you need additional help with Evolution, visit the Novell support site at <ulink url='http://support.novell.com'>Novell support</ulink>.</para>" >
+ <!ENTITY KNOWLEDGEBASE_INFO_ON_CONNECTOR_PARA "<para>The Novell Web site knowledgebase, at <ulink url='http://support.novell.com'>support.novell.com</ulink>, has additional information about checking to make sure that your Exchange server accepts connections from Evolution.</para>" >
+-->
 ] >
 
 <book id="index" lang="en">
-<title>Evolution User Guide 2.0</title>
+<title>Evolution User Guide &VERSION;</title>
 
  <bookinfo id="Front">
   <productname>Evolution&trade;</productname>
-  <productnumber>2.0</productnumber>
-  <invpartnumber>September 9, 2004</invpartnumber>
+  <productnumber>&VERSION;</productnumber>
+  <invpartnumber>&DATE;</invpartnumber>
   <title>User guide</title>
  </bookinfo>
 
  <preface id="preface">
   <title>About This Guide</title>
-  <para>This guide describes how to use and manage Evolution&trade; 2.0.x client software. This guide is intended for users and is divided into the following sections:</para>
+  <para>This guide describes how to use and manage Evolution&trade; &VERSION_SERIES; client software. This guide is intended for users and is divided into the following sections:</para>
   <itemizedlist>
    <listitem>
     <para><link linkend="usage-mainwindow">Getting Started</link></para>
@@ -61,22 +89,19 @@
    </listitem>
   </itemizedlist>
   <bridgehead>Finding Help</bridgehead>
-  <para>You can find additional help in three places. </para>
+  <para>You can find additional help in these places. </para>
   <itemizedlist>
    <listitem>
     <para>For information about command line options, open a terminal window and type <command>evolution --help</command>.</para>
    </listitem>
-   <listitem>
-    <para>For support, late-breaking news, and errata, visit the Novell support center at <ulink url="http://support.novell.com";>support.novell.com</ulink>.</para>
-   </listitem>
+&SUPPORT_NOTES;
    <listitem>
     <para>In the Evolution interface, click Help &gt; Contents.</para>
    </listitem>
   </itemizedlist>
-  <bridgehead>Documentation Updates</bridgehead>
-  <para>For the most recent version of the<citetitle> Evolution 2.0 User Guide</citetitle>, see the <ulink url="http://www.novell.com/documentation/ximian.html";>Evolution Documentation Web site</ulink>.</para>
+&DOCUMENTATION_UPDATES;
   <bridgehead>Documentation Conventions</bridgehead>
-  <para>In Novell documentation, a greater-than symbol (&gt;) is used to separate actions within a step and items in a cross-reference path.</para>
+&PARA_ABOUT_GREATER_THAN_SYMBOL;
   <para>A trademark symbol (&reg;, &trade;, etc.) denotes a Novell trademark. An asterisk (*) denotes a third-party trademark.</para>
  </preface>
 
@@ -98,7 +123,7 @@
    <title>Starting Evolution for the First Time</title>
    <procedure>
     <step id="bs4u1a6">
-     <para>Click the Applications Menu icon &gt; Office &gt; Evolution.</para>
+     <para>&STARTING_EVOLUTION_FROM_PANEL;</para>
      <para>or</para>
      <para>Enter <command>evolution</command> at the command line.</para>
     </step>
@@ -106,7 +131,7 @@
 
    <section id="bse54o0">
     <title>Using the First-Run Assistant</title>
-    <para>The first time you run Evolution, it creates a directory called evolution in your home directory, where it stores all of its local data. Then, it opens a first-run assistant to help you set up e-mail accounts and import data from other applications.</para>
+    <para>The first time you run Evolution, it creates a directory called <filename>.evolution</filename> in your home directory, where it stores all of its local data. Then, it opens a first-run assistant to help you set up e-mail accounts and import data from other applications.</para>
     <para>Using the first-run assistant takes approximately two to five minutes.</para>
     <para>Later on, if you want to change this account, or if you want to create a new one, select Tools &gt; Settings, then click Mail Accounts. Select the account you want to change, then click Edit. Alternately, add a new account by clicking Add. See <link linkend="config-prefs-mail">Mail Preferences</link> for details.</para>
 
@@ -2470,7 +2495,7 @@ Accepting and Replying to a Meeting Requ
 
   <section id="bs4tpft">
    <title>Configuring Evolution for GroupWise</title>
-   <para>In order to have the best support for GroupWise in Evolution, you should immediately upgrade Evolution to 2.0.</para>
+   <para>In order to have the best support for GroupWise in Evolution, you should immediately upgrade Evolution to &VERSION;.</para>
    <para>If this is your first time starting Evolution, the Evolution Account Assistant window appears. If the Evolution Account Assistant window does not appear, click Tools &gt; Settings, then click Mail Accounts. </para>
    <procedure>
     <step id="brugnl1">
@@ -2539,7 +2564,7 @@ Accepting and Replying to a Meeting Requ
 
  <chapter id="usage-exchange">
   <title>Connecting to Exchange Servers</title>
-  <para>The Evolution&trade; Connector for Microsoft Exchange allows Evolution clients to access accounts on Microsoft Exchange 2000 servers. It is available through Red Carpet in its own channel. Like Evolution, it is free software and licensed under the GPL. </para>
+  <para>The Evolution&trade; Connector for Microsoft Exchange allows Evolution clients to access accounts on Microsoft Exchange 2000 servers. &CONNECTOR_AVAILABILITY_SENTENCE; Like Evolution, it is free software and licensed under the GPL. </para>
   <itemizedlist>
    <listitem>
     <para><link linkend="new-in-connector">What's New in Connector 2.0</link></para>
@@ -2642,7 +2667,7 @@ Accepting and Replying to a Meeting Requ
 
   <section id="install">
    <title>Installing the Connector</title>
-   <para>To install the Evolution Connector, run Red Carpet by clicking System &gt; Get Software. Subscribe to the Evolution Connector for Microsoft Exchange channel, select the Evolution Connector for Microsoft Exchange 2000, then click the Install button. You can also install the Connector by downloading the individual packages from ftp.ximian.com if you wish.</para>
+   &INSTALLING_THE_CONNECTOR_PARA;
   </section>
 
   <section id="exchange-configure">
@@ -2660,7 +2685,7 @@ Accepting and Replying to a Meeting Requ
       <para>You are permitted to access the account with WebDAV. This is the default setting for the Exchange server, so unless your system administrator has specifically turned it off, no changes should be necessary.</para>
      </listitem>
     </itemizedlist>
-    <para>The Novell Web site knowledgebase, at <ulink url="http://support.novell.com";>support.novell.com</ulink>, has additional information about checking to make sure that your Exchange server accepts connections from Evolution.</para>
+    &KNOWLEDGEBASE_INFO_ON_CONNECTOR_PARA;
    </section>
 
    <section id="config-client">
@@ -3218,7 +3243,7 @@ Accepting and Replying to a Meeting Requ
 
    <section id="bshpjuj">
     <title>Spell Checking</title>
-    <para>To choose a spell-checking language, select it here. You must install the gnome-spell package, available through Red Carpet, for spell-checking to be available in Evolution. Additional dictionaries are also available through Red Carpet and are detected automatically if you have installed them. To have the composer automatically check your spelling while you type, select Check Spelling While I Type.</para>
+    <para>To choose a spell-checking language, select it here. &SPELLING_INSTALLATION_NOTES; To have the composer automatically check your spelling while you type, select Check Spelling While I Type.</para>
     <para>Check the spelling of messages by clicking Edit &gt; Spell Check Document. </para>
    </section>
   </section>
@@ -3601,7 +3626,7 @@ Accepting and Replying to a Meeting Requ
   <title>Known Bugs and Limitations</title>
   <para>A complete list of feature requests and other issues with Evolution&trade; is available online in the Ximian&reg; bug tracking system. You can learn more about the Evolution development process at <ulink url="http://developer.ximian.com";>developer.ximian.com</ulink>. </para>
   <para>Evolution bug tracking is done at the <ulink url="http://bugzillaximian.com";>Ximian&reg; bug tracking System</ulink>. You can use that, or the GNOME Bug Report Tool (known as bug-buddy at the command line) if you find bugs or would like to request new features.</para>
-  <para>If you need additional help with Evolution, visit the Novell support site at <ulink url="http://support.novell.com";>Novell support</ulink>.</para>
+  &ADDITIONAL_HELP_PARA;
  </appendix>
 
  <glossary id="apx-gloss">
@@ -3882,8 +3907,8 @@ Accepting and Replying to a Meeting Requ
     <member>U.S.A.</member>
     <member>www.novell.com</member>
    </simplelist>
-   <para id="Bktitle">Evolution User Guide 2.0</para>
-   <para>September 9, 2004</para>
+   <para id="Bktitle">Evolution User Guide &VERSION;</para>
+   <para>&DATE;</para>
    <simplelist>
     <member>To access the online documentation for this and other Novell products, and to get updates, see www.novell.com/documentation.</member>
    </simplelist>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]